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.

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.

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}
├── 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
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.