A repository template for AI-first software development with Claude Code that organizes the entire software development lifecycle (SDLC) into four phases — Objectives, Design, Code, Deploy — each with folder structure, artifacts, and agent instructions that encode what to check, when to check it, and what to do, so that all project knowledge lives inside the repository and a human can supervise at a high level.

It is not a tool, a library, or an application. It is a starting scaffold — you clone or copy it, then fill it in as your real project takes shape.

The scaffold is built on four core principles:

1. AI-first development model — designed for AI agents doing the work while a human supervises, defines objectives, and steers direction.
2. Everything-in-repo — objectives, requirements, architecture, decisions, and task tracking all live alongside the source code, versioned and always accessible to agents without external tools.
3. Context-window efficiency — hierarchical instructions, two-file decision records, and phase-level indexes minimize how many tokens an agent must load.
4. Decision capture, not suppression — agents decide autonomously within established patterns; all decisions are recorded in the repository for human review and consistency.

For a deeper discussion of the rationale, core principles, and design choices see RATIONALE.md.

npx degit pangon/ai-sdlc-scaffold my-project
cd my-project
rm -f CONTRIBUTING.md CONTRIBUTORS.md LICENSE NOTICE RATIONALE.md README.md
git init && git add -A && git commit -m "Initial scaffold"

degit copies the repository contents without carrying over git history, giving you a clean starting point. It requires Node.js but does not install any dependency in your project. The rm step removes repo-specific files that are not part of the scaffold.

1. Download or clone this repository.
2. Copy all files and directories (including hidden ones like .claude/) into your new project folder.
3. Remove the .git/ directory to start with a fresh history.
4. Remove repo-specific files: rm -f CONTRIBUTING.md CONTRIBUTORS.md LICENSE NOTICE RATIONALE.md README.md.
5. Initialize a new repository: git init && git add -A && git commit -m "Initial scaffold".

1. Run /SDLC-init in Claude Code: the initialization skill sets up the project description in CLAUDE.md so agents have the right context from the start.
2. Work through the phases (Objectives → Design → Code → Deploy) using the built-in skills — type / followed by a skill name to automate each step, from requirements gathering to deployment. Alternatively, you can use custom prompts: the CLAUDE.<phase>.md hierarchy provides all the context the agent needs to operate correctly in each phase.

Manual edits are strongly discouraged. All changes to artifacts and code should go through an AI agent whose behavior is governed by the instruction files, existing artifacts, and ideally a skill. This ensures that procedures are followed, decisions are recorded, and the system stays consistent.

├── CLAUDE.md                         # Root AI instructions (start here)
├── RATIONALE.md                      # Core principles and design rationale
│
├── 1-objectives/                     # WHAT and WHY
│   ├── CLAUDE.objectives.md          # Phase instructions and artifact indexes
│   ├── stakeholders.md               # Stakeholder definitions
│   ├── goals/                        # GOAL-kebab-name.md + _template.md
│   ├── user-stories/                 # US-kebab-name.md + _template.md
│   ├── requirements/                 # REQ-CLASS-kebab-name.md + _template.md
│   ├── assumptions/                  # ASM-kebab-name.md + _template.md
│   └── constraints/                  # CON-kebab-name.md + _template.md
│
├── 2-design/                         # HOW
│   ├── CLAUDE.design.md              # Phase instructions and decisions index
│   ├── architecture.md               # System architecture overview
│   ├── data-model.md                 # Data structures and schemas
│   ├── api-design.md                 # API specifications
│   └── decisions/                    # DEC-kebab-name.md + DEC-kebab-name.history.md
│
├── 3-code/                           # BUILD
│   ├── CLAUDE.code.md                # Phase instructions, decisions index, component guidelines
│   ├── tasks.md                      # Development task tracker
│   └── <component>/                  # Per-component directories (created by /SDLC-decompose)
│       └── CLAUDE.<component>.md     # Component description, decisions index, addressed requirements
│
├── 4-deploy/                         # SHIP
│   ├── CLAUDE.deploy.md              # Phase instructions
│   └── runbooks/                     # Operational procedures + _template.md
│
└── .claude/skills/                   # Claude Code skills (automation layer)
    ├── SDLC-init/SKILL.md            # guided project initialization
    ├── SDLC-elicit/SKILL.md          # requirements elicitation
    ├── SDLC-design/SKILL.md          # design documents
    ├── SDLC-decompose/SKILL.md       # component identification
    ├── SDLC-implementation-plan/SKILL.md  # task generation
    ├── SDLC-execute-next-task/SKILL.md    # task execution
    └── SDLC-status/SKILL.md          # /SDLC-status — project dashboard

• Phase-based development: each phase has a directory and a CLAUDE.<phase>.md file that extends the root CLAUDE.md. Phase gates define minimum preconditions before advancing.
• Traceability: every artifact references others by descriptive ID (GOAL-reduce-latency, REQ-F-search-by-name, DEC-use-postgres), creating a chain from business need to running code. Index tables link directly to artifact files for easy navigation.
• Two-file decisions: active record (DEC-kebab-name.md) for enforcement, history file (DEC-kebab-name.history.md) for audit trail. Indexed per phase with trigger conditions.
• Context-window efficiency: hierarchical instructions, phase-level indexes, and the active/history split minimize how many tokens an agent needs to load.

The scaffold starts empty. Project-specific artifacts are created progressively as you work through each phase — not all at once.

• At project start (/SDLC-init): set the project description in CLAUDE.md so agents have the right context from the start.
• During the Objectives phase (/SDLC-elicit): define stakeholders, goals, constraints, assumptions, user stories, and requirements.
• During the Design phase (/SDLC-design): draft architecture, data model, API design. Decisions are recorded as they emerge during design work.
• At the start of the Code phase (/SDLC-decompose, /SDLC-implementation-plan): identify components (creating per-component directories under 3-code/), then generate the task backlog.
• During the Code phase (/SDLC-execute-next-task): implement tasks one at a time — each call picks the next pending task, writes code and tests, and updates the task status.

Claude skills automate each phase of the lifecycle. Type /skill-name in Claude Code to invoke them. Each skill reads the root CLAUDE.md and the relevant phase instructions before acting.

/SDLC-init                  ← set up project
/SDLC-elicit                ← define stakeholders, goals, requirements
                            ← human approves artifacts (Draft → Approved)
/SDLC-design                ← draft architecture, data model, API design
/SDLC-decompose             ← identify components, create directories
/SDLC-implementation-plan   ← generate task backlog
/SDLC-execute-next-task     ← execute tasks one by one
/SDLC-status                ← anytime: full project overview

Licensed under the Apache License, Version 2.0. See LICENSE.

Contributions are accepted under the same license (inbound = outbound). See CONTRIBUTING.md.