ADLC Team Skills

Agent skills for the Twelve-Factor Agentic SDLC workflow — team directives management, product decision records, and architecture analysis.

Relationship to 12 factors: This repo is referenced from team-ai-directives and together with the 12-factor methodology forms the Foundation layer of the ADLC stack. The skills implement Factors III, IV, VII, VIII, IX, X, XI, and XII.

Quickstart

# Install skills globally
npx skills add tikalk/adlc-team-skills -a claude -g

# Or for a specific project
npx skills add tikalk/adlc-team-skills -a claude

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

Before anything else: Run team-setup once to configure the team AI directives path, or ensure .adlc/init-options.json is present.

---

#1: The Agent Doesn't Know How Your Team Works

Factor X — Context Engineering. Factor XI — Directives as Code. Factor XII — Team Capability.

An agent assigned to your repo has no idea about your team's coding conventions, review standards, architectural principles, or product strategy. Without structured context injection, every session starts from zero — and every session drifts.

team-boot loads the team constitution, PDR and ADR indexes, and relevant context modules automatically on session start. team-discover retrieves the specific personas, rules, and examples relevant to the current task. No prompt walls, no manual context dumping.

team-boot      → auto-loads constitution + PDR/ADR indexes + discover
team-discover  → fetches rules/personas/examples for the current task
team-constitution → create or amend the team constitution interactively
team-repair    → re-index CDR.md, scan for conflicts, verify freshness

---

#2: Lessons From Sessions Evaporate

Factor IX — Traceability. Factor XI — Directives as Code. Factor XII — Team Capability.

Every agent session surfaces patterns, gotchas, and team knowledge. Without a structured capture mechanism, that knowledge is lost when the session ends.

LevelUp skills capture session traces, extract reusable Context Directive Records (CDRs), and publish them back to the team AI directives repository as skills, rules, personas, or examples — creating a closed feedback loop where every session enriches the next.

levelup-init      → brownfield CDR discovery from codebase + paired evals
levelup-specify    → extract CDRs + paired evals from current session
levelup-clarify    → review, accept, reject, or defer CDRs (evals gate ON)
levelup-publish    → compile into team directives + evals goldensets + draft PR

---

#3: Product Decisions Are Invisible

Factor III — Mission Definition.

Without documented product decisions, every implementation session re-derives (or misinterprets) the product's intent. Feature scope, target audience, business constraints, and trade-offs are locked in someone's head or buried in a Slack thread.

Product skills capture product decisions as individual PDR files, refine them through a clarification workflow, and compile them into a self-contained PRD.md. The product-roadmap skill tracks milestone progress from decisions through execution, evidence, and gates — with live issue counting via MCP.

product-init      → discover PDRs from existing codebase/docs (brownfield)
product-specify   → create PDRs interactively (greenfield)
product-clarify   → refine, validate, and approve PDRs
product-implement → generate PRD.md from accepted PDRs
product-analyze   → check PDR↔PRD consistency
product-roadmap   → track milestone progress (decisions + issues + code + gates)

---

#4: Architecture Decisions Are Invisible

Factor IV — Structured Planning.

Unrecorded architecture decisions produce inconsistent implementations, duplicated effort, and systems that are harder to maintain or evolve. The adage "the architecture is in the code" is only true if you're willing to reverse-engineer every decision from the source.

Architecture skills capture Architectural Decision Records (ADRs) and compose them into a unified Architecture Description (AD) using the Rozanski & Woods viewpoints methodology.

architect-init      → reverse-engineer ADRs from codebase (brownfield)
architect-specify   → create ADRs from PRD or feature description (greenfield)
architect-clarify   → refine and validate ADRs
architect-implement → generate AD.md from accepted ADRs
architect-analyze   → check ADR↔AD consistency and quality

---

#5: End-to-End Feature Work Spans Many Skills

Factor III — Mission Definition. Factor XIII — Loop Engineering.

A real feature isn't one skill — it's specify → plan → tasks → implement ↔ converge, with gates, a circuit breaker, resume across sessions, and an audit trail. Orchestrating that by hand is error-prone and loses state on every compaction. mission-brief structures the description into a Mission Brief (goal, constraints, success criteria), generates an ordered step list with prompts that trigger installed SDD skills via model invocation or command-file discovery, and walks those steps to converged implementation. No YAML workflow files, no per-framework profiles — the step prompts use canonical SDD terminology that works with any installed skill set. Supports 30+ agents via externalized command discovery (references/agent-integrations.md).

mission-brief            → brief → generate steps → run end-to-end (sync default, --async across sessions)
mission-brief --resume   → continue an interrupted mission from the persisted checkpoint

Runs sync (interactive, gated) or async (ungated, checkpoint across sessions), with a converge loop, circuit breaker, spec-correction routing (config-gated), per-step model tiers, and a mission-log.json audit trail.

---

Reference

Team Directives (6 skills)

Model-invoked

• team-boot — Bootstrap session: load constitution, PDR/ADR indexes, discover context. Auto-triggered on session start.
• team-discover — Fetch relevant personas, rules, examples, PDRs, and ADRs for the current task. Auto-triggered.

User-invoked

• team-constitution — Create or amend the team constitution interactively. Say "Create our team constitution" or "Amend our team principles."
• team-repair — Re-index CDR.md, .skills.json, AGENTS.md; health check; conflict scan; freshness verification. Say "Check our team directives health" (--health-only), "Repair our CDR index," or "Scan for rule conflicts" (--conflicts).
• team-skills — Browse and install team skills from the team AI directives. Say "Show me available team skills."
• team-setup — Clone, scaffold, or configure a team AI directives repository. Say "Set up team directives for this project."

LevelUp / CDR Lifecycle (5 skills)

All user-invoked. Capture and publish reusable patterns to team-ai-directives, including paired directive compliance evals.

• levelup-init — Brownfield CDR discovery from existing codebase, including paired eval CDRs from code patterns. Say "Discover directives from this codebase."
• levelup-specify — Extract CDRs and paired eval CDRs from the current session. Say "Extract lessons from this session."
• levelup-clarify — Review, accept, reject, or defer pending CDRs. Evals regression gate runs by default. Say "Review pending CDRs."
• levelup-publish — Compile accepted CDRs into team directives artifacts, evals goldensets, and draft PR. Say "Publish accepted CDRs" or "Build one skill from a CDR" (--skill CDR-NNN).

Product / PDR Lifecycle (6 skills)

All user-invoked. Document product decisions as individual PDRs and compile into a self-contained PRD.md.

• product-init — Brownfield PDR discovery from existing codebase and documentation. Say "Discover product decisions from this codebase."
• product-specify — Greenfield PDR creation through interactive product exploration. Say "Let's define our product strategy."
• product-clarify — Refine, validate, and approve PDRs before PRD generation. Say "Review our product decisions."
• product-implement — Generate PRD.md from accepted PDRs (multi-agent DAG orchestration). Say "Generate our PRD."
• product-analyze — Read-only PDR↔PRD consistency and quality analysis. Say "Analyze our product docs."
• product-roadmap — Track milestone progress: decision status, live issues via MCP, code evidence, and gates. Say "Show roadmap progress."

Architecture (5 skills)

All user-invoked. Create and manage Architecture Decision Records using the Rozanski & Woods methodology.

• architect-init — Reverse-engineer ADRs from an existing codebase (brownfield). Say "Reverse-engineer architecture from this codebase."
• architect-specify — Create ADRs from a PRD or feature description (greenfield). Say "Create ADRs from this PRD."
• architect-clarify — Refine and validate existing ADRs. Say "Refine and validate my ADRs."
• architect-implement — Generate an Architecture Description (AD.md) from accepted ADRs. Say "Generate AD.md from my ADRs."
• architect-analyze — Check ADR↔AD consistency and architecture quality. Say "Analyze architecture consistency."

Governance / Verification (6 skills)

All user-invoked. Build and maintain application-level evaluation suites following EDD (Eval-Driven Development) principles (PromptFoo or DeepEval).

• evals-init — Initialize evaluation directory structure (evals/{system}/) with security baseline. Say "Initialize my evaluation harness."
• evals-specify — Extract eval criteria from specs and production failure traces (bottom-up open coding). Say "Specify evaluation criteria from this failure log."
• evals-clarify — Cluster related patterns, refine criteria, isolate 20% holdout split, and publish goldset. Say "Clarify and accept my draft evaluations."
• evals-implement — Generate executable graders and test configs, automatically running unit tests to verify evaluator correctness. Say "Generate graders from the goldset."
• evals-validate — Run the evaluation pyramid (Tier 1 fast checks + Tier 2 LLM judges) and compute quality metrics (TPR/TNR, SLA headroom). Say "Validate my evaluation suite."
• evals-analyze — Deep-analyze trajectory failure traces, routing spec-level failures to levelup-specify (rules) and generalization failures to backlog. Say "Analyze evaluation failures."

Missions (1 skill)

User-invoked. Structure a feature description into a Mission Brief and run it end-to-end with any installed SDD skill set.

• mission-brief — Takes a description, structures it into a Mission Brief (goal, constraints, success criteria), generates an ordered step list with prompts that trigger installed SDD skills, and walks those steps to converged implementation. Sync (gated) or --async (ungated, checkpoint across sessions). Say "Build this feature end to end" or mission-brief "add dark mode". Resume with mission-brief --resume.

---

Output File Layout

All skills write to .adlc/ (project root) and the team AI directives repo.

Team Directives (inside the team AI directives repository):

• AGENTS.md — agent instructions (loading order, rules, skills)
• CDR.md — index of approved context contributions
• .skills.json — skills manifest (schema v2.0.0)
• .mcp.json.example — MCP servers config example
• context_modules/constitution.md — team constitution (OKF frontmatter)
• context_modules/{rules,personas,examples}/**/*.md — context modules
• context_modules/{type}/index.md — progressive disclosure per concept type
• context_modules/{type}/log.md — chronological change log per concept type
• skills/{name}/SKILL.md + .skills-entry.json — published team skills
• evals/{directive-id}/goldset.md + goldset.json — directive compliance goldensets

LevelUp (inside .adlc/ of the target project):

• .adlc/drafts/cdr/CDR-{NNN}.md — proposed/discovered CDRs (including eval CDRs)
• .adlc/drafts/cdr/cdr.md — auto-generated CDR index
• .adlc/init-options.json — team AI directives path config

Product (inside .adlc/ and repo root):

• .adlc/drafts/pdr/PDR-{NNN}.md — proposed/discovered PDRs
• .adlc/drafts/pdr/pdr.md — auto-generated PDR index
• .adlc/memory/pdr/PDR-{NNN}.md — accepted/completed PDRs
• .adlc/memory/pdr/pdr.md — accepted PDR index
• .adlc/product/sections/{feature-area}/{section}.md — PRD section build artifacts
• .adlc/product/state.json — DAG execution state
• PRD.md — Product Requirements Document (repo root)

Architecture (inside .adlc/ and repo root):

• .adlc/drafts/adr/ADR-{NNN}.md — proposed/discovered ADRs
• .adlc/drafts/adr/adr.md — auto-generated ADR index
• .adlc/memory/adr/ADR-{NNN}.md — accepted ADRs
• .adlc/memory/adr/adr.md — accepted ADR index
• AD.md — Architecture Description (repo root)
• .adlc/architect/ — per-view DAG artifacts

Missions (inside .adlc/ of the target project):

• .adlc/workflow/workflow-config.yml — mission execution/supervision/budgets config
• .adlc/workflow/.mission-state.json — step list, completed steps, brief, discovery results
• .adlc/workflow/runs/<feature>/mission-log.json — final audit trail
• .adlc/workflow/runs/<feature>/iterations.md — per-implement audit entries

Governance (inside target project and repo root):

• .adlc/drafts/evals/EVAL-{NNN}.md — proposed/discovered eval criteria drafts
• .adlc/drafts/evals/evals.md — draft evals index
• .adlc/memory/evals/EVAL-{NNN}.md — accepted/completed eval criteria
• .adlc/memory/evals/evals.md — accepted evals index
• .adlc/memory/evals/holdout.json — isolated/reserved holdout test dataset
• evals/{system}/goldset.md — published goldset (human-readable)
• evals/{system}/goldset.json — published goldset (machine-readable)
• evals/{system}/config.yml — evaluation framework configuration
• evals/{system}/config.{js,py} — framework test config
• evals/{system}/graders/check_*.py — generated binary Python graders / metrics
• evals/{system}/tests/test_check_*.py — generated unit tests verifying grader correctness
• evals/results/validation_report.md — statistical validation results report

OKF Compliance

Generated context modules include Open Knowledge Format (OKF) v0.1 compliant frontmatter alongside custom fields.

OKF field	Status	Source
type	✅	CDR context type
title	✅	CDR title
description	✅	CDR descriptor
resource	✅	Relative path to artifact
tags	✅	Context type tag
timestamp	✅	ISO 8601 datetime

Custom fields co-exist with OKF frontmatter: id, cdr_ref, created, modified, verified, age_days, evidence.

Directory structure: context_modules/{type}/index.md (progressive disclosure), context_modules/{type}/log.md (change history), cross-links between related concepts.

Workflows

Team Directives setup:

team-setup → team-constitution → team-boot (auto on every session)

Product lifecycle:

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

Architecture lifecycle:

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

LevelUp / CDR lifecycle:

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:

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

Application Evaluation lifecycle:

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

Full product → architecture → team:

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

12-Factor Alignment

Factor	Skills	How
III — Mission Definition	Product skills	PRD/PDR lifecycle ensures product decisions are documented, reviewed, and traceable before execution
IV — Structured Planning	Architecture skills	ADRs and AD.md provide structured planning artifacts using Rozanski & Woods viewpoints
VII — Verification-First Evals	LevelUp skills	Eval CDRs with binary pass/fail cases test directive compliance; evals regression gate in levelup-clarify
VIII — Ratchet Effect	LevelUp skills	Each session extracts eval CDRs alongside directive CDRs — quality strictly increases
IX — Traceability	Product + Architecture	Every decision traces from PDR → PRD → feature and from ADR → AD → code
X — Context Engineering	Team Directives	team-boot and team-discover load only relevant context per task, preventing bloat
XI — Directives as Code	Team + LevelUp + Product + Architecture	All directive lifecycles (CDR, PDR, ADR) live in version-controlled repos, each with draft → clarify → accept → publish → analyze stages
XII — Build to Delete	team-repair	--build-to-delete runs evals without directives via LLM calls; if model passes, proposes deletion (Harness Decay)

---

Release Process

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

License

MIT — see LICENSE.