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.

1. The Decision Engine — RFC-0011 · RFC-0035

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

4. Operator Surface — RFC-0051 · RFC-0035

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:

1. 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.
2. 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.
3. CHARTER.md — project governance, IP policy, CNCF alignment.
4. 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.
5. 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

• Contributing: CONTRIBUTING.md — bug reports, feature requests, code, and spec changes (via RFC)
• Governance: GOVERNANCE.md — project roles, decision making, SIG structure
• Charter: CHARTER.md — mission, scope, IP policy, CNCF alignment
• License: Apache 2.0 — commercial and open-source use, no restrictions
• Code of Conduct: Contributor Covenant v2.1

---

Website · Documentation · Specification · Vision · Pricing

If you find this project useful, please consider giving it a star.