tikalk/adlc-team-skills

🐙 ADLC Team Skills — Agentic SDLC for Engineering Teams - tikalk/adlc-team-skills

2 stars · 0 forks · 0 watchers

README

ADLC Team Skills — Agentic SDLC for Engineering Teams

Stop Vibe Coding in Silos. Build a Shared Cognitive Layer for Your Engineering Team.

Individual prompt hacks create quick wins for solo developers, but when scaled across a team, "vibe coding" leads to chaotic technical debt, context rot, unreviewable PRs, and lost code ownership. Speed is solved; Trust and Verification is the new bottleneck in AI engineering. ADLC Team Skills (tikalk/adlc-team-skills) is the open-source Team Layer of the Twelve-Factor Agentic SDLC. It turns AI agents from isolated guessers into compliant, accountable team members that share your team's constitution, product strategy, architectural standards, and evaluation benchmarks. Team AI Directives (tikalk/agentic-sdlc-team-ai-directives) is the companion repository that holds your team's version-controlled context modules (constitution, rules, personas, examples), CDR index, and skills manifest.

Quickstart

Install skills + generate slash commands + wire session_start events

Or with npx skills only (skills without commands/events)

team-constitution → interactively replace the placeholder with your real principles

team-boot (auto) → assembles constitution + CDR index + PDR/ADR indexes + skills registry into the system prompt at session start

Already have a directives repo? team-setup offers three other modes:

Mode 1 — Clone from GitHub (e.g. fork tikalk/agentic-sdlc-team-ai-directives) Mode 2 — Point to existing local path (wire a repo you already have) Mode 4 — Already configured (verify an existing setup)

Directives as Code: The Four Team Pillars [ THE GREAT FILTER ] (Human Team Lead Macro-Review) ▲ │ ┌──────────────────┴──────────────────┐ │ Pillar 4: Governance & Evals │ │ (Tier 1 Fast Checks + LLM Judges) │ └──────────────────▲──────────────────┘ │ ┌──────────────────┴──────────────────┐ │ Pillar 3: Spec-Driven Workflow │ │ (Contract-First Mission Pipeline) │ └──────────────────▲──────────────────┘ │ ┌──────────────────┴──────────────────┐ │ Pillar 2: Product & Architecture │ │ (Product PDRs + Architecture ADRs)│ └──────────────────▲──────────────────┘ │ ┌───────────────────┴───────────────────┐ │ Pillar 1: Strategy & Team Directives│ │ (team-boot / levelup / CDR repository) │ └───────────────────────────────────────┘

🏛️ Pillar 1: Strategy & Team Directives (Team-First Alignment) Factor I — Developer as Orchestrator. Factor X — Context Engineering. Factor XI — Directives as Code. Put the team at the center of your AI strategy. Instead of individual developers hoarding prompt shortcuts on local machines, team standards live in a version-controlled Git repository (team-ai-directives).

team-boot: Auto-runs at session start via the event hook, assembling the team constitution, CDR index, PDR/ADR indexes, and skill registry into the system prompt. team-discover: Manually re-scan team context modules for explicit structured discovery tables. Available via /team-discover. team-constitution: Interactively define, review, or amend your engineering team's core principles. team-repair: Re-index CDR.md, scan for rule conflicts, and verify directive freshness.

team-boot → assembles constitution + CDR index + PDR/ADR + skills into system prompt team-discover → manual re-scan for structured discovery tables (/team-discover) team-constitution → create or amend the team constitution interactively team-repair → re-index CDR.md, scan for conflicts, verify freshness

🎯 Pillar 2: Product Strategy & Architectural Governance (PDRs & ADRs) Factor III — Mission Definition. Factor IV — Structured Planning. Factor IX — Traceability. Without documented decisions, every implementation session re-derives (or misinterprets) product intent and architectural rules.

Product Decision Records (product-*): Capture product decisions as individual PDR files, resolve ambiguities through an interactive clarification workflow, and compile them into a self-contained PRD.md. Architectural Decision Records (architect-*): Reverse-engineer or define architectural decisions using Rozanski & Woods viewpoints (Functional, Security, Deployment, Performance) and compose them into a unified AD.md. product-roadmap: Track milestone progress across four layers of truth — decisions (PDRs), execution (live issues via MCP), code evidence, and milestone gates.

Product: product-init → product-clarify → product-implement → product-analyze Architecture: architect-init → architect-clarify → architect-implement → architect-analyze Roadmap: product-roadmap (tracks PDRs + issues + code + gates)

📐 Pillar 3: Spec-Driven Workflow ("Debug the Spec, Not the Code") Factor III — Mission Definition. Factor IV — Structured Planning. Factor V — Triage & Execution. Factor XIII — Loop Engineering. AI is an obsessive guesser — when faced with ambiguity, it invents solutions instead of asking questions. Move from a Conversational model to a Contract model.

mission-brief: The team's autonomous pipeline runner. Takes a feature prompt, derives a formal contract (Goal, Constraints, Non-Goals, Success Criteria), generates an ordered step list, and walks a specify → plan → tasks → implement ↺ converge loop to completion. Mantra: "Debug the Spec, Not the Code": When an agent makes a mistake, don't just patch the code — add the missing constraint to the specification so the mistake is never repeated.

mission-brief "add user profile API with JWT" ├── Phase 2: Brief (Goal, Constraints, Non-Goals, Success Criteria) ├── Phase 3: Route Classification (spec | change | quick) ├── Phase 4: Discovery (auto-wires local installed skills & SDD frameworks) └── Phase 5: Execute (specify → plan → tasks → implement ↺ converge)

🛡️ Pillar 4: Team Governance, Verification-First Evals & "Build to Delete" Factor VII — Verification-First Evals. Factor VIII — Ratchet Effect. Factor IX — Traceability. Factor XII — Build to Delete. Never let the agent that wrote the code decide if the code is good. "Separate the Maker from the Checker."

evals skills: Build application-level evaluation suites (PromptFoo or DeepEval) using Eval-Driven Development (EDD). Runs Tier 1 fast checks + Tier 2 LLM judge subagents to test code against defined business risks before human macro-review in The Great Filter. levelup: Capture session wins into permanent team memory. levelup-specify extracts session execution traces and commits them to Git as reusable rules (Context Directive Records — CDRs). "Build to Delete": Prune outdated rules and prompt scaffolding as underlying foundation models improve using team-repair --build-to-delete.

LevelUp: levelup-init → levelup-specify → levelup-clarify → levelup-publish Evals: evals-init → evals-specify → evals-clarify → evals-implement → evals-validate → evals-analyze

🌐 Universal Skill & SDD Framework Orchestration — Zero Lock-In Factor XII — Build to Delete. Factor XIII — Loop Engineering. mission-brief acts as an open, vendor-agnostic orchestrator across all popular agent skill repositories and Spec-Driven Development (SDD) frameworks:

SDD Framework / Skill Source Supported Workflows

Agentic SDLC Spec-Kit (tikalk/agentic-sdlc-spec-kit) Twelve-Factor SDD pipeline, native specify CLI discovery, contract verification

Spec-Kit (specify_cli) Native command discovery and specification templates

OpenSpec Structured edge-case contracts and verification schemas

mattpocock/skills /tdd, /grill-me, /grill-with-docs, /code-review, /prototype

addyosmani/agent-skills Exit criteria checklists, quality gate skills

superpowers Developer tooling & workflow skills

ADLC Team Skills (this repo) product-specify, architect-specify, evals-validate, levelup-specify

Your Custom Skills Any skill following the SKILL.md standard

How it works

Discovery — At mission start, mission-brief scans all skills directories (.claude/skills, .agents/skills, etc.) and reads every SKILL.md frontmatter to build a vendor-agnostic inventory of installed skills with their names and descriptions. LLM-decided routing — Each step's delegation prompt includes the full skills inventory. The subagent decides which skill (if any) fits the current phase — the LLM matches, not a brittle lookup table. Graceful fallback — If no skill matches, the subagent executes directly. If a skill matches, it's invoked. Either way, the mission pipeline continues.

Install skills from multiple team or community sources

mission-brief discovers and routes them automatically

Repository Layout Skills are organized under the four pillars of the Twelve-Factor Agentic SDLC, flattened directly under the skills/ directory: 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 └── team/ # team-* (6 skills) + team-helpers.{sh,ps1}

This places every single skill exactly 2 levels deep, fully resolving the default depth limit of the skills CLI and ensuring all skills install out of the box.

Reference Team Directives (6 skills) Model-invoked

team-boot — Bootstrap session: assembles constitution, CDR index, PDR/ADR indexes, and skill registry into the system prompt at session start. Outputs a warning to run /team-setup on unconfigured projects. team-discover — Manually re-scan team context modules and produce a structured discovery table. Available via /team-discover. team-setup — Clone, scaffold, or configure a team AI directives repository. Model-invoked by team-boot (self-install) and available on demand. Say "Set up team directives for this project."

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."

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.

Tech Radar (1 skill) Model-invoked. Grounds tech stack choices in Tikal's Israeli Tech Radar.

tech-radar-context — Discovers technologies implied by the prompt, matches them against the Tikal Tech Radar (radar.json), and injects a context table with each technology's adoption ring (Keep/Start/Try/Stop), quadrant, and Tikal's "Why?" opinion — plus Tikal-aligned alternatives for anything on Stop. Auto-triggered whenever a technology, framework, database, library, or cloud tool is being chosen or evaluated. Fetches the live radar best-effort and falls back to a bundled snapshot at resources/radar.json.

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/

source