adlc-team-skills

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: