adlc-team-skills

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

Table of contents

• How it works
• The developer journey
• The problems these skills solve
• Install
• The software factory
• Universal orchestration
• What's inside
• Philosophy
• When something goes wrong
• Security
• Contributing
• Reference details
• Release process
• License

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 of your team's rules — 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.

The index lives in a git repo — your team-ai-directives — versioned, reviewed by PR, shared by the whole team. No more personal CLAUDE.md files that live on one machine, drift out of date, and don't transfer between teammates or tools.

When you ask the agent to build something, it doesn't jump to code. factory-mission forces a contract first — goal, constraints, non-goals, success criteria (the mission-brief format) — then walks specify → plan → implement ↔ converge, with gates, a circuit breaker, resume, and an audit trail. When a session surfaces a hard-won fix, team-levelup extracts it as a Context Directive Record (CDR), scores it by confidence, and publishes accepted CDRs back to the team repo. Usage data and confidence scores live in the adlc orphan branch — the next session starts smarter and CDRs rank by real usage.

Verification, history, and tech selection have loops of their own. When a rule or skill's behavior needs proof, the evals-* skills build executable graders — binary checks where code can verify, LLM judges only for what static checks can't — validated with holdout splits and TPR/TNR. When you touch old code and wonder why it looks like this, change-init mines git history for issue-linked commits and recovers the past-change rationale as ChDRs. And when a tech choice comes up, tech-radar-boot injects the Tikal Tech Radar's opinion — adoption ring, quadrant — before the selection is captured as an ADR.

That session loop sits inside a bigger one: the software factory. factory-queue triages incoming work, factory-mission executes it as spec-gated missions in isolated worktrees, factory-review grades the resulting PRs against policy-as-code, and factory-learn feeds what the runs taught back into team-ai-directives — with human gates (⭐) at every decision point. One platform: intake → mission → review → learning.

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 developer journey

What it actually looks like to get from zero to a factory, in order.

0. Prerequisites

• A coding agent (opencode, Claude Code, Cursor, Codex, Gemini CLI, …)
• adlc-cli — npx works, no install needed
• jq — the team-boot script parses the directives index with it

1. Install — one command per project

npx adlc-cli team setup tikalk/adlc-team-skills -a opencode

This installs the skills (via npx skills add), generates the /name slash commands, wires the event hooks, then runs /team-setup headlessly to clone, link, or scaffold your team-ai-directives repo. It writes .adlc/init-options.json (agent, skills source, directives path) so every later command knows where things live.

Plain npx adlc-cli skills add tikalk/adlc-team-skills -a <agent> installs skills + commands + events without the team configuration.

2. First session — context arrives on its own

Open a session in the project. team-boot fires on session_start and injects the index (constitution titles, CDR index ranked by confidence, Class Boots catalog, skills registry, MCP servers). On an unconfigured project it points you to /team-setup; /team-constitution fills in your team's principles once. There is nothing to remember after this point — skills trigger when the task matches.

3. Daily work — index, class boots, decision capture

• The agent checks the directives index before any task; full rule bodies load on demand.
• Class boots fire when a decision class shows up: architect-boot (ADR index), product-boot (PDR index), change-boot (ChDR index), tech-radar-boot (radar opinion before a tech selection).
• Decision capture runs continuously: decisions detected mid-session land as lightweight drafts in .adlc/drafts/{adr,pdr,chdr,cdr,evals}/. The file_edited hook notices each draft landing and nudges the matching clarify skill (adr→/architect-clarify, pdr→/product-clarify, …).
• When harness compaction summarizes history away, session_compact re-injects the index.

4. Session end — learnings become records

team-levelup fires on session_end: it extracts hard-won fixes as CDRs + paired eval CDRs, scores confidence, batch-reviews them, and publishes accepted CDRs as a draft PR to team-ai-directives. Drafts and usage reports live in the adlc orphan branch (drafts/cdr/ + reports/).

5. Individual lifecycles — on demand

Each record class has its own skill loop you invoke explicitly:

Product:     product-specify|init → product-clarify (accept + promote to memory) → product-implement → product-analyze
Architecture: architect-specify|init → architect-clarify (accept + promote to memory) → architect-implement → architect-analyze
Team:        team-init → team-levelup (extract + review + publish) → team-repair (--update-confidence)
Change:      change-init → change-clarify → change-publish (change-boot injects the chdr.md index)
Evals:       evals-init → evals-specify → evals-clarify → evals-implement → evals-validate

Accepted PDRs/ADRs are promoted to memory on approval — no gap between "Accepted in drafts" and "moved to memory".

6. The software factory — the outer loop

Running intake → execution → review → learning unattended? The factory takes over from queue to PR — see The software factory.

Ongoing maintenance

adlc-cli team update     # git pull team-ai-directives + skills update + confidence update
adlc-cli team repair     # full repair via agent run (reindex, conflicts, freshness)
adlc-cli team repair --update-confidence  # deterministic confidence aggregation (no agent)

team-repair --build-to-delete re-runs evals without a rule and proposes deletion when the model passes anyway; --validate-drafts validates draft files in .adlc/drafts/ without modifying them.

The problems these skills solve

Install

# One command: install skills + configure team-ai-directives (runs /team-setup interactively)
npx adlc-cli team setup tikalk/adlc-team-skills -a opencode

# Or just install skills (no team-setup)
npx adlc-cli skills add tikalk/adlc-team-skills -a opencode

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

Selective installs resolve closures automatically: --skill architect-implement also pulls its canonical home (architect-clarify) via .skills-deps.json, so shared helpers are never orphaned. Borrower skills fail fast with the exact recovery command if their canonical home is missing.

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

adlc-cli wraps npx skills add and additionally generates /name slash commands and wires the four event hooks declared in this repo's .events.json — session_start and session_compact (team-boot), session_end (team-levelup), and file_edited (team-boot, draft-written nudges) — for the 9 coding agents with native hook support. team setup also runs the /team-setup skill via agent run to clone, link, or scaffold your team-ai-directives repo. 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.

The software factory

The factory skills are the full outer loop of an agentic SDLC: they take a brownfield repo from bootstrap all the way to merged, reviewed PRs — and turn what each run learned into team memory. Every automated stage is advisory; humans hold the gates (⭐).

 brownfield repo
        │
        ▼
┌─────────────────┐  unified bootstrap: product → architect → change
│  factory-init   │  tracks + PDR↔ADR↔ChDR↔code coverage matrix
└────────┬────────┘  (--refresh = recurring alignment sweep)
         │ PRD.md · AD.md · .adlc/memory/
         ▼
┌──────────────────────────┐  PDRs → PRD.md  ·  ADRs → AD.md
│ factory-product /        │  (clarify⭐ human gates)
│ factory-architect        │
└────────┬─────────────────┘
         │ Mission Brief (goal + constraints + success criteria)
         ▼
  Intent Gate ⭐  (human approves the brief; AI triage scores are advisory)
         │
         ▼
┌─────────────────┐  spec-gated into the tracker (the Q, single source of truth)
│  factory-queue  │
└────────┬────────┘
         │ --issue ref
         ▼
┌─────────────────┐  inner loop: specify → plan → implement ↔ converge
│ factory-mission │  (comment bus · worktrees · TDD test/code split · circuit breaker)
└────────┬────────┘
         │ agent-authored PR
         ▼
┌─────────────────┐
│ factory-review  │──▶ Merge Gate ⭐ (human code-owner approval)
└────────┬────────┘
         ▼
┌─────────────────┐  CDRs/ChDRs → team-ai-directives PR
│  factory-learn  │  workflow memories → memory.jsonl
└────────┬────────┘
         │
         └─▶ back to factory-mission (memories)
             + team-boot (CDR index — closes the context loop)

What each station adds:

• factory-setup — one command wires a repo to its issue tracker: provider pick (detect-from-remote, explicit, or already-configured), writes .adlc/issues-provider.yml (never credentials, never overwrite).
• factory-init — one command onboards an existing repo onto ADLC and emits the PDR↔ADR↔ChDR↔code coverage matrix (--refresh for the recurring alignment sweep).
• factory-queue — mission brief intake: AI-assisted advisory triage scoring, intent gate, gating label stamping, milestones/epics generation.
• factory-mission — the execution engine: spec-gated inner loop (specify → plan → implement ↔ converge) with tracker-agnostic integration, an inter-agent comment bus, worktree isolation, lease-based liveness, stall detection, and a mandated TDD test/code split (RED gate + GREEN gate, enforced at the skill level, not just the prompt level).
• factory-review — severity-ranked PR compliance against REVIEW.md policy-as-code; babysits agent PRs to merge, never auto-merges past the human gate. --self-heal runs a three-sub-agent converge loop (Review→Fix→Converge) with maker-checker separation and circuit breaker.
• factory-learn — retrospectives into team-ai-directives: build-to-delete pruning, promote-to-check for mechanical rules.
• factory-product / factory-architect — lifecycle coordinators maintaining PRD.md and AD.md with clarify⭐ gates.
• factory-tickets — read-only worklist across trackers, classified by next actionable move.
• factory-clean — resource inventory and reclamation, approval-gated.

flowchart LR
    FQ["factory-queue<br/>Ingestion & Triage"] ~~~ IG{"Intent Gate"}
    FP["factory-product<br/>Product Lifecycle"] ~~~ CG1{"clarify⭐ Gate"}
    FA["factory-architect<br/>Architecture Lifecycle"] ~~~ CG2{"clarify⭐ Gate"}
    FM["factory-mission<br/>Execution Engine"] ~~~ CB{"Circuit Breaker"}
    FR["factory-review<br/>PR Compliance"] ~~~ MG{"Merge Gate"}
    FL["factory-learn<br/>Learning Loop"] ~~~ CG3{"clarify⭐ Gate"}
    FC["factory-clean<br/>Resource Cleanup"] ~~~ UG{"Approval Gate"}
    FT["factory-tickets<br/>Read-Only Worklist"]
    FI["factory-init<br/>Brownfield Bootstrap"]

    TR[("Issue Tracker<br/>GitHub / GitLab / Linear / Jira")]
    TD[["team-ai-directives<br/>repo"]]

    FQ -->|"spec-gated labels"| TR
    TR -->|"--issue ref"| FM
    FP -->|"PRD.md"| FQ
    FA -->|"AD.md"| FQ
    FM -->|"agent-authored PRs"| TR
    TR -->|"PR diff + checks"| FR
    FR -->|"twice-mistake rule"| FL
    FL -->|"memory.jsonl"| FM
    FL -->|"draft PR"| TD
    FC -.->|"reads state files"| FM
    FT -.->|"read-only"| TR
    FI -.->|"via product-* leaves"| FP
    FI -.->|"via architect-* leaves"| FA
    FI -.->|"via change-* leaves (one-time deep)"| FL

Universal orchestration

factory-mission 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:

What's inside

44 skills across 8 categories.

Team directives — every session, every user

• team-boot — session-start bootstrap; injects the always-relevant layer (constitution titles, CDR index ranked by confidence, Class Boots catalog, skills registry) and dispatches to per-class boots on demand. Auto-triggered; re-declared for session_compact so the index survives harness compaction. Also fires the session-end friction trigger for CDR capture, and file_edited draft-written nudges suggesting the matching clarify skill.
• team-setup — clone, link, or scaffold a team-ai-directives repo.
• team-constitution — define or amend team principles interactively.
• team-discover — manual re-scan; structured match table (/team-discover).
• team-repair — re-index, conflict scan, freshness, --build-to-delete, --validate-drafts, deterministic-enforcement coverage check.
• team-skills — browse/install team skills from the directives repo.
• team-diagnose — evidence-first diagnosis when team context doesn't appear: walks the chain (init-options → jq → boot.sh → artifact sync) and routes injection-side bugs to adlc-cli.

The software factory — the outer loop

• factory-init — unified brownfield bootstrap + PDR↔ADR↔ChDR↔code coverage matrix (--refresh).
• factory-queue — queue intake, AI advisory triage scoring, intent gate, milestone generation.
• factory-mission — execution engine: tracker-agnostic, comment bus, worktree isolation, mandated TDD RED/GREEN gates (Test Agent writes failing tests first, Implement Agent writes code to pass them), circuit breaker.
• factory-review — severity-ranked PR policy compliance against REVIEW.md; babysits agent PRs to merge.
• factory-product / factory-architect — product/architecture lifecycle coordinators.
• factory-learn — continuous improvement loops targeting team-ai-directives: build-to-delete pruning, promote-to-check (EVAL-010) for mechanical rules.
• factory-tickets — read-only personal worklist across trackers.
• factory-clean — resource inventory and reclamation (approval-gated).

Mission-driven development

• factory-mission — spec-contract pipeline with converge loop, circuit breaker, resume (factory-mission "feature", --resume).

Learning loop (CDR lifecycle)

• team-levelup — session-end CDR lifecycle: extract patterns, score confidence, batch review (A/B/C/D/P), and publish accepted CDRs as a draft PR. Auto-triggers on session_end event. Drafts live in the adlc orphan branch of team-ai-directives (drafts/cdr/ + reports/ for usage data).
• team-init — brownfield CDR discovery from an existing codebase. Writes to the adlc branch; handoff to team-levelup for review/publish.
• team-repair --update-confidence — aggregate usage data from the adlc branch into confidence scores, update OKF frontmatter, rebuild CDR.md with confidence column. team-boot ranks CDRs by confidence in the injected index.

Evals — verification over vibes

• 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 deterministic checks, context rules, or evaluator backlog.

Product & architecture lifecycles

• product-boot / product-init / product-specify — PDR index, brownfield discovery, greenfield creation.
• product-clarify — refine and approve. product-implement — generate PRD.md.
• product-analyze — PDR↔PRD consistency. product-roadmap — milestone progress across decision, execution, evidence, and gate layers.
• architect-boot / architect-init / architect-specify — ADR index, reverse-engineering, creation (routes tech selection through tech-radar-boot).
• architect-clarify — refine. architect-implement — generate AD.md. architect-analyze — ADR↔AD consistency.

Change history (ChDRs)

• change-boot — class boot: injects the chdr.md index when past-change rationale matters + ChDR mining capture.
• change-init — mine git history for Change Decision Records via issue-linked commits.
• change-clarify — review mined ChDRs (provenance gate on Decision claims).
• change-publish — promote accepted ChDRs to .adlc/memory/chdr/.

Tech selection

• tech-radar-boot — class boot: injects Tikal Tech Radar context (adoption ring, quadrant, opinion) for tech selection + ADR capture pairing. Auto-triggered. The radar dataset is fetched live from https://tikalk.com/radar.json on every invocation — no bundled snapshot to go stale.

Workspace

• workspace — multi-repo workspace: --init creates .adlc/ structure, discover/link/audit child repos (--link, --status, --ignore-only).

Skill authoring — contributors

• writing-skills — TDD-for-skills: baseline the failure without the skill (RED), write the minimal skill (GREEN), close rationalization loopholes (REFACTOR). Iron Law: no skill without a failing baseline first (EVAL-011). Includes the SKILL.md template and the testing methodology.

Philosophy

• Index, not injection. Long contexts measurably degrade LLM performance — even with perfect retrieval (arXiv:2510.05381, 13.9%–85% degradation by length alone). 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.
• Rules should shrink over time, not grow. Base models improve; yesterday's scaffolding becomes today's context noise. --build-to-delete re-runs evals without a rule and proposes deletion when the model passes anyway. Mechanical rules that survive are flagged for promotion to deterministic checks.
• Evidence over vibes. Anything code can check gets a binary grader — plain assertions, Tier 1. LLM judges are Tier 2, reserved for what static checks can't verify. Nothing auto-merges; pipelines end at a PR a human reviews.
• Decisions as code. Every decision class — product (PDR), architecture (ADR), change (ChDR), context (CDR) — lives in version-controlled repos with a draft → clarify → accept → promote → publish → analyze lifecycle, and traces from record to document to code. Accepted records are promoted to memory atomically with approval — never left in drafts.

When something goes wrong

• Team context didn't appear at session start — check .adlc/init-options.json points at an existing team-ai-directives checkout; on an unconfigured project run /team-setup. The session_start hook (.events.json → dispatcher → team-boot's scripts/boot.sh) needs jq available. Full chain contract: docs/event-hook-contract.md; run scripts/acceptance-test.sh to verify the whole loop from scratch. For evidence-first diagnosis of injection failures, run /team-diagnose (traces init-options → jq → boot.sh → artifact sync → injection; EVAL-013).
• Team context vanished mid-session after compaction — re-injection after compaction is a declared contract (session_compact in .events.json); the injection side is implemented by adlc-cli — if your agent's adapter doesn't map the event yet, file it there.
• Skill descriptions or commands look stale — the install layer is CLI-generated (.agents/skills/, .opencode/commands/, skills-lock.json). Regenerate: npx adlc-cli skills add tikalk/adlc-team-skills -a <agent> -y. tests/unit/test_generated_artifacts_sync.py catches drift locally.
• Index is inconsistent or rules conflict — run /team-repair (re-index, conflict scan, freshness check, orphan detection).
• Something else — open an issue. To verify a suspected skill-behavior bug yourself, follow the manual testing protocol (scratch project, real agent, report table). The repo's testing model — two directories, three tiers — is mapped in docs/testing.md.

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.

Contributing

See CONTRIBUTING.md. New skills must be agreed in an issue first, ship with eval coverage, and follow the writing-skills methodology — no skill without a failing baseline first.

Reference details

skills/
├── team/          # team-* (9) + workspace + templates/ (team-helpers canonical in team-setup)
├── evals/         # evals-* (6) + evals-templates/
├── product/       # product-* (7) + product-templates/ + templates/ (pdr-lib canonical in product-clarify)
├── architect/     # architect-* (6) + templates/ (setup-architect + generators canonical in architect-clarify)
├── change/        # change-* (4) + templates/
├── tech-radar/    # tech-radar-boot (1) — live radar fetch, no bundled dataset
├── authoring/     # writing-skills (1; templates live inside the skill)
└── factory/       # factory-* (10) — platform orchestration

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: team-init → team-levelup (extract + review + publish) → team-repair
Session:    team-levelup (extract + review + publish) → team-repair
History:    change-init → change-clarify → change-publish (change-boot injects chdr.md)
Build to Delete: team-repair --build-to-delete → team-levelup (review deletion CDRs)
Confidence:   team-repair --update-confidence → team-boot (ranks CDRs by confidence)

factory-mission "feature" → review brief → execute steps → converge → run archive (.adlc/workflows/runs/<run_id>/)

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

Release process

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

License

MIT — see LICENSE.