adlc-team-skills

Agent skills that give coding agents your team's context at session start, so they stop working like strangers.

The problem

Coding agents start every session knowing nothing about your team. They don't know your conventions, which patterns you deprecated, or why service X never calls service Y. Developers compensate with personal CLAUDE.md files, but those live on one machine, drift out of date, and don't transfer between teammates or tools.

What this does

#1: The agent doesn't know how your team works

team-boot runs at session start and injects an index of your team's rules, personas, and decisions — names and one-line descriptors, roughly a hundred tokens. Not the rules themselves. When the active task matches a rule, the agent pulls that rule's full text on demand. A task touching SQL loads the SQL rule; nothing else loads.

team-boot        → auto-runs at session start (event hook), injects the index
team-discover    → /team-discover for a structured match table
team-constitution → interactively define your team's principles
team-repair      → re-index, conflict scan, freshness check

The index lives in a git repo (team-ai-directives) — versioned, reviewed by PR, shared by the whole team.

#2: The agent guesses instead of asking

LLMs fill ambiguity with invention. mission-brief forces a contract first: goal, constraints, non-goals, success criteria — then runs specify → plan → tasks → implement ↔ converge. When the agent gets something wrong, you fix the spec, not the code.

mission-brief "add user profile API with JWT"
mission-brief --resume    # continue an interrupted mission

#3: The maker grades its own work

The evals skills build executable evaluation suites (PromptFoo or DeepEval). Anything that can be checked by code gets a binary grader — plain assertions, Tier 1. LLM judges are Tier 2, reserved for what static checks can't verify. Nothing auto-merges; the pipeline ends at a PR a human reviews.

evals-init → evals-specify → evals-clarify → evals-implement → evals-validate → evals-analyze

#4: Session learnings evaporate

When a session surfaces a hard-won fix, levelup-specify extracts it as a Context Directive Record (CDR) and commits it back to the team repo — the next session starts smarter.

levelup-init → levelup-specify → levelup-clarify → levelup-publish

#5: Product and architecture decisions are invisible

product-* skills capture product decisions as PDR files and compile them into PRD.md. architect-* skills capture architecture decisions as ADRs (Rozanski & Woods viewpoints) and compose them into AD.md. Every decision traces from record to document to code.

product-init|specify → product-clarify → product-implement → product-analyze
architect-init|specify → architect-clarify → architect-implement → architect-analyze

#6: Rules pile up and rot

Base models improve; yesterday's scaffolding becomes today's context noise. team-repair --build-to-delete re-runs evals without a rule; if the model passes anyway, the rule is proposed for deletion. Rules should shrink over time, not grow.

A note on context stuffing

Long contexts measurably degrade LLM performance — even with perfect retrieval (arXiv:2510.05381, 13.9%–85% degradation by length alone). This repo exists because of that failure mode, not in spite of it: agents get an index by default and pull full rules only when relevant. If your instinct is "more rules in context don't work" — we agree. That's the design.

How it works

It starts the moment you open a session. team-boot fires via the session_start event hook and injects a lean index — your team's constitution, CDR index, PDR/ADR indexes, and skills registry — roughly a hundred tokens of names and one-line descriptors. Not the rules themselves. When the active task matches a rule, the agent pulls that rule's full text on demand. A task touching SQL loads the SQL rule; nothing else does.

On an unconfigured project, team-boot points you to /team-setup, which clones, links, or scaffolds your team-ai-directives repo. team-constitution fills in your principles.

When you ask it to build something, it doesn't jump to code. mission-brief forces a contract first — goal, constraints, non-goals, success criteria — then generates an ordered step list and walks specify → plan → implement ↔ converge, with gates, a circuit breaker, resume, and an audit trail. At mission start it scans installed skills directories, reads each SKILL.md frontmatter, and hands the inventory to the subagent; the model picks the skill that fits each step — this repo's product-specify, superpowers' brainstorming, spec-kit's commands, or your own.

For new products, product-specify captures Product Decision Records (PDRs), product-clarify refines them, and product-implement compiles them into PRD.md. The architect-* skills do the same for Architecture Decision Records (ADRs, Rozanski & Woods viewpoints) and compose them into AD.md.

The evals skills build executable evaluation suites — binary graders (Tier 1, plain assertions) for anything code can check, LLM judges (Tier 2) only for what static checks can't. evals-validate runs the pyramid with holdout splits, TPR/TNR, and SLA headroom. Nothing auto-merges; the pipeline ends at a PR a human reviews.

When a session surfaces a hard-won fix, levelup-specify extracts it as a Context Directive Record (CDR) — with a paired eval CDR — and commits it back to the team repo. The next session starts smarter.

Rules rot, so team-repair --build-to-delete re-runs evals without a rule; if the model passes anyway, the rule is proposed for deletion. Rules should shrink over time, not grow.

And because the skills trigger automatically from the index, you don't do anything special once they're installed. Your coding agent just has your team's context.

The Basic Workflow

1. team-boot — auto-runs at session start (event hook); injects the directives index (constitution, CDR index, PDR/ADR indexes, skills registry). Full rules pulled on demand when the task matches.
2. team-setup — on an unconfigured project, clones/links/scaffolds the team-ai-directives repo. team-constitution fills in your principles.
3. mission-brief — before code, forces a spec contract (goal, constraints, non-goals, success criteria), then walks specify → plan → implement ↔ converge with gates, circuit breaker, resume, and audit trail.
4. product-specify / product-init — greenfield/brownfield capture of Product Decision Records (PDRs). → product-clarify refines → product-implement generates PRD.md → product-analyze checks consistency.
5. architect-specify / architect-init — same shape for Architecture Decision Records (ADRs, Rozanski & Woods). → architect-clarify → architect-implement generates AD.md → architect-analyze.
6. evals-init → evals-specify → evals-clarify → evals-implement → evals-validate — builds executable graders (binary Tier 1, LLM judge Tier 2), holdout split, TPR/TNR + SLA validation. Pipeline ends at a human-reviewed PR.
7. levelup-specify — at session end, extracts hard-won fixes as CDRs + paired eval CDRs. → levelup-clarify reviews → levelup-publish commits to team repo → next session starts smarter.
8. team-repair --build-to-delete — re-runs evals without a rule; if the model passes anyway, proposes the rule for deletion. Rules shrink over time, not grow.

The agent checks the directives index before any task. Skills trigger automatically when the active task matches — mandatory lifecycle, not suggestions.

Install

# Skills + slash commands + session_start events
npx adlc-skills-cli add tikalk/adlc-team-skills -a opencode

# Or plain skills (no commands/events)
npx skills add tikalk/adlc-team-skills -a claude -g

Works with any agent supporting the Agent Skills standard — Claude Code, Codex, OpenCode, Cursor, Copilot, and others.

adlc-skills-cli wraps npx skills add and additionally generates /name slash commands and wires session_start event hooks (via .events.json) for 9 coding agents. Skills repos without .events.json get commands only.

First run: team-boot fires at session start. On an unconfigured project it points you to /team-setup, which clones, links, or scaffolds your team-ai-directives repo. team-constitution fills in your principles.

Using agentic-sdlc-spec-kit alongside this repo? See Coexistence with Spec Kit for the conflict-free install flow.

Universal orchestration

mission-brief doesn't force a proprietary ecosystem. At mission start it scans installed skills directories, reads each SKILL.md frontmatter, and hands the inventory to the subagent — the model picks the skill that fits each step. Works alongside:

Security

On 2026-07-27 a supply-chain worm briefly injected a malicious payload into this repo's .claude/ and .vscode/ directories via a stolen maintainer token (exposure window ~11:06–18:30 UTC). The payload only executed if you cloned the repo and opened it in VS Code or started a Claude Code session inside it; the npx skills install path never shipped or ran those files.

History was rewritten to strip the payload from all commits and tags, tokens and secrets were rotated, and branch protection now blocks the vector used. Details and remediation steps: issue #1.

Lesson for any repo: treat .vscode/tasks.json and .claude/settings.json in a clone as executable code, and disable editor auto-run tasks.

Reference

Team Directives

• team-boot — session-start bootstrap; injects the directives index. Auto-triggered.
• team-discover — manual re-scan; structured match table (/team-discover).
• team-setup — clone, link, or scaffold a team-ai-directives repo.
• team-constitution — define or amend team principles interactively.
• team-repair — re-index, conflict scan, freshness, --build-to-delete.
• team-skills — browse/install team skills from the directives repo.

LevelUp / CDR lifecycle

• levelup-init — brownfield CDR discovery from an existing codebase.
• levelup-specify — extract CDRs + paired evals from the current session.
• levelup-clarify — review, accept, reject, or defer pending CDRs.
• levelup-publish — compile accepted CDRs into directives + goldensets + draft PR.

Change (ChDRs)

• change-init — mine git history for Change Decision Records via issue-linked commits; recovers the why behind past changes (reverts, fix chains).
• change-clarify — review, accept, reject, or defer mined ChDRs (provenance gate on Decision claims).
• change-publish — promote accepted ChDRs to .adlc/memory/chdr/; team-boot injects the chdr.md index at session start.

Product (PDRs)

• product-init — brownfield PDR discovery. product-specify — greenfield creation.
• product-clarify — refine and approve. product-implement — generate PRD.md.
• product-analyze — PDR↔PRD consistency. product-roadmap — milestone progress.

Architecture (ADRs)

• architect-init — reverse-engineer ADRs. architect-specify — create ADRs.
• architect-clarify — refine. architect-implement — generate AD.md.
• architect-analyze — ADR↔AD consistency.

Evals

• evals-init — scaffold evals/{system}/ with security baseline.
• evals-specify — extract criteria from specs / failure traces.
• evals-clarify — cluster, isolate holdout, publish goldset.
• evals-implement — generate graders + unit tests.
• evals-validate — run evaluation pyramid, TPR/TNR + SLA headroom.
• evals-analyze — route failures to rules or evaluator backlog.

Orchestration & misc

• mission-brief — spec-contract pipeline with converge loop, circuit breaker, resume.
• tech-radar-context — injects Tikal Tech Radar context for tech choices. Auto-triggered.
• workspace — multi-repo workspace: --init creates .adlc/ structure + .gitignore, discover/link/audit child repos.

skills/
├── architect/             # architect-* (5 skills)
├── product/               # product-* (6 skills) + product-templates/
├── levelup/               # levelup-* (4 skills) + levelup-helpers.{sh,ps1}
├── change/                # change-* (3 skills) — ChDRs from git history
├── mission-brief/         # core SDD orchestrator (1 skill)
├── evals/                 # evals-* (6 skills) + evals-templates/
├── tech-radar/            # tech-radar-* (1 skill) + resources/radar.json
├── workspace/             # workspace (1 skill) — multi-repo coordination
└── team/                  # team-* (6 skills) + team-helpers.{sh,ps1}

team-setup → team-constitution → team-boot (auto at session start)

Brownfield: product-init → product-clarify → product-implement → product-analyze
Greenfield: product-specify → product-clarify → product-implement → product-analyze
Roadmap:    product-roadmap (anytime)

Brownfield: architect-init → architect-clarify → architect-implement → architect-analyze
Greenfield: architect-specify → architect-clarify → architect-implement → architect-analyze

Brownfield: levelup-init → levelup-clarify → levelup-publish → team-repair
Session:    levelup-specify → levelup-clarify → levelup-publish → team-repair
History:    change-init → change-clarify → change-publish (team-boot injects chdr.md)
Build to Delete: team-repair --build-to-delete → levelup-clarify (review deletion CDRs)

mission-brief "feature" → review brief → execute steps → converge → mission-log.json

workspace --init → create .adlc/ structure + configure .gitignore
product-specify / architect-specify → create shared PDRs/ADRs in parent .adlc/
workspace --link → register child repos as submodules
workspace --status → audit branch, dirty, unpushed, SHA drift

Greenfield (Spec-Driven): evals-init → evals-specify (from spec) → evals-clarify → evals-implement → evals-validate
Brownfield (Error-Driven): evals-init → evals-specify (from failures) → evals-clarify → evals-implement → evals-validate → evals-analyze

Product:     product-specify → product-clarify → product-implement → product-analyze
Architecture: architect-specify → architect-clarify → architect-implement → architect-analyze
Team:        levelup-specify → levelup-clarify → levelup-publish → team-repair

Release Process

See RELEASE.md for the release runbook, tag naming conventions, and recovery procedures.

License

MIT — see LICENSE.