AI-SDLC Framework
The Decision Engine for spec-driven AI workflows
Website · Documentation · Specification · Getting Started · Vision · Contributing
What this is
AI-SDLC is the Decision Engine for spec-driven AI workflows — the execution-and-governance half of a spec-driven development stack. Operators frontload the load-bearing decisions through a Definition-of-Ready gate; a session hierarchy (cli-hierarchy) dispatches developer subagents through the dependency graph; cross-harness reviewers (Claude × Codex × …) verify the work in parallel; DSSE attestations seal every change; pull requests open themselves.
The leverage move is cost asymmetry: operator decisions made upfront — with full context, time to think, and access to stakeholders — are cheap and (mostly) correct. AI decisions made mid-execution under uncertainty are expensive and often wrong. The framework's value is not "AI writes code"; it's "AI executes well-specified contracts deterministically." Those are different products with different reliability profiles.
The operator's role shifts to decision steward — frame open questions, resolve them, sign off on resolutions, monitor the pipeline. Typing and rubber-stamping go to the framework.
AI-SDLC covers the contract → shipped half of the spec-driven funnel. Front-of-funnel tools like GitHub Spec Kit cover idea → contract; the two systems compose at the seam where a spec artifact becomes a backlog task ready for DoR. See RFC-0036 for the bridge design and adopter authoring model.
Read first: VISION.md is the organizing thesis — the design philosophy that grounds every RFC, every CLI, every gate. If something in this repo doesn't trace back to one of its principles, that's a signal we've drifted.
The problem AI-SDLC solves
AI agents can build small greenfield projects, but software falls apart as it grows. The data is consistent:
- Productivity paradox — Experienced developers using AI tools are 19% slower on mature codebases, despite believing they are 20% faster (METR 2025)
- Quality decline — Refactoring dropped from 25% to 10% of changes; code churn rose from 5.5% to 7.9% (GitClear 2024)
- Stability regression — Every 25% increase in AI adoption correlates with a 7.2% drop in system stability (Google DORA 2024)
- Trust gap — Only 3% of developers express high trust in AI output (Stack Overflow 2025)
The root cause is not that AI agents write bad code. It is that nobody orchestrates how they work as the codebase grows — every decision gets deferred to the worst possible moment, made by the actor with the least context. AI-SDLC flips that.
The five pillars
The framework is one cohesive system, but it ships as five pillars you can adopt incrementally.
A Definition-of-Ready gate (RFC-0011) refuses to dispatch tasks the operator hasn't actually decided yet. The shipped Decision Catalog (RFC-0035, cli-decisions) makes the operator's open-question queue a first-class resource — ranked by leverage, routed to the right actor, surfaced with framework recommendations + counter-arguments + sub-decision graphs. The framework recommends; the operator decides; the dispatch session executes. → Concept page
2. Session Hierarchy — RFC-0051
cli-hierarchy up starts a planner, a dispatch session and up to five executors, each a Claude Code session in its own tmux session. Dispatch walks the dependency graph (RFC-0014), admits tasks past the blocked, in-flight, DoR and dispatchability filters, and hands each to an executor in an isolated git worktree, which runs the Step 0-13 pipeline (dev agent → configured reviewers → attestation sign → PR open). Operators monitor; they don't type. → Concept page · Runbook
3. Cross-Harness Review — RFC-0010 §13
The configured reviewer set (.ai-sdlc/review-policy.md, reviewer-set-flag) runs in parallel on every change. DSSE envelopes carry a harness field that identifies the execution harness behind each review, and verify-attestation enforces independence by construction: if Claude implemented, Claude cannot also be the code or test reviewer. Codex reviews Claude's work and vice versa. Reviewer collusion is mechanically impossible. → Concept page · Runbook
The operator works through cli-hierarchy (status, attach, brief, down) and the Decision Catalog (cli-decisions), which foregrounds load-bearing decisions and stays out of the way for the rest. → Reference
5. Declarative Governance
Declarative resources for the whole lifecycle: Pipeline, Decision, AgentRole, QualityGate, AutonomyPolicy, AdapterBinding — all with JSON Schema (draft 2020-12) under spec/schemas/. Quality gates run advisory → soft-mandatory → hard-mandatory with cross-harness review and DSSE attestation. Adopters declare a compliance posture (RFC-0022) and the framework derives gate defaults — EU AI Act, NIST AI RMF, ISO 42001. → Specification
Getting started
# 1. Install the Claude Code plugin (recommended)
/plugin marketplace add ai-sdlc-framework/ai-sdlc
/plugin install ai-sdlc@ai-sdlc
/reload-plugins
# 2. Scaffold your repository
ai-sdlc init
# 3. Check the install and configuration are healthy
ai-sdlc doctor
# 4. Dispatch your first task
/ai-sdlc execute AISDLC-42
Full setup, runner configuration, agent-runner reference, and the session-hierarchy setup are in the documentation:
→ Getting Started · Tutorials · API Reference · Operations Runbooks
The framework is agent-agnostic — Claude Code, Codex, Cursor, Copilot, Aider, or any OpenAI-compatible API. See the Agent Runner Reference.
For AI agents and human contributors discovering this repo
If you are an AI agent or a new contributor coming to this codebase for the first time, read these documents in order. Each is canonical for its concern:
VISION.md — the organizing thesis (Decision Engine, cost asymmetry, operator-as-decision-steward, anti-patterns ruled out). Every decision in this repo should trace back here.CLAUDE.md — operating conventions for any agent or contributor working in this repo: git flow (always rebase, never merge), branch + commit conventions, pre-push hooks, attestation requirements, backlog workflow, Pattern-C worktree isolation, plugin MCP routing. Load this before doing any work.CHARTER.md — project governance, IP policy, CNCF alignment.spec/rfcs/README.md — the architectural decisions registry. Every load-bearing design choice lives as an RFC. The registry table is the canonical lookup for numbers and lifecycle states; the Critical Path section traces dependencies.spec/spec.md + spec/ — the normative specification: resource model, policy enforcement, autonomy, agents, adapters, metrics.
Canonical execution paths (when working inside a Claude Code session):
| Use case | Command | Billing |
|---|
| Internal dogfood (backlog tasks) | /ai-sdlc execute <task-id> | Subscription |
| Manual cleanup | /ai-sdlc cleanup [<task-id>] | n/a |
| Autonomous drain (session hierarchy) | /ai-sdlc hierarchy up | Subscription |
| GitHub issue / unattended / CI | pnpm --filter @ai-sdlc/dogfood watch --issue <id> | API key |
Rules of thumb to internalize before pushing code:
- Merging follows
governance.allowMerge in .ai-sdlc/agent-role.yaml, rendered into the session hard rules; when it permits merging, the only path is cli-merge-if-eligible; never run the raw merge command.
- Always rebase feature branches onto main. Never merge main in.
- Pattern C: the parent working tree is read-only. All code work happens in
.worktrees/<task-id>/. /ai-sdlc execute sets this up automatically.
- Attestation is required on
main. Code PRs that touch source must carry a DSSE envelope signed by the reviewer chain. Docs-only PRs bypass. See the review policy for what counts as a review, and the independence policy (.ai-sdlc/independence-policy.yaml requiredTier) to enforce reviewer independence.
- Cross-repo writes go through
permittedExternalPaths in the task frontmatter.
The plugin's slash commands and MCP tools are documented in ai-sdlc-plugin/README.md. The Step 0-13 pipeline is in pipeline-cli/README.md.
Packages
| Package | Path | Purpose |
|---|
@ai-sdlc/orchestrator | orchestrator/ | Orchestrator runtime — CLI, runners, admission, state store |
@ai-sdlc/pipeline-cli | pipeline-cli/ | Step 0-13 pipeline runtime; cli-orchestrator, cli-deps, cli-decisions, cli-tui |
ai-sdlc-plugin | ai-sdlc-plugin/ | Claude Code plugin — hooks, slash commands, reviewer subagents, MCP server |
@ai-sdlc/sdk | sdk-typescript/ | TypeScript SDK |
ai-sdlc-framework | sdk-python/ | Python SDK (pip install ai-sdlc-framework) |
sdk-go | sdk-go/ | Go SDK + Kubernetes-style operator CRDs |
@ai-sdlc/conformance | conformance/ | Language-agnostic conformance test suite |
spec/ | spec/ | Formal specification, RFCs, JSON schemas |
For development setup (pnpm install, build, test, schema validation), see docs/getting-started/ and CONTRIBUTING.md.
Specification & versioning
The specification follows Kubernetes-style API maturity: v1alpha1 today; v1beta1 follows a 9-month deprecation window; v1 follows a 12-month window. Resource types, policy enforcement levels, autonomy, agents, and adapters all live under spec/ with JSON Schema (draft 2020-12) under spec/schemas/.
Architectural changes go through the RFC process. The registry there is the canonical lookup for every RFC number — active, reserved, withdrawn, and implemented.
Contributing, governance, license
Website · Documentation · Specification · Vision · Pricing
If you find this project useful, please consider giving it a star.
