State Driven Development with Agentic AI

State Driven Development (SDD) is a lightweight methodology for keeping coding-agent work state inside the repository being changed.

Instead of relying only on chat history, SDD gives agents such as Codex, Claude Code, OpenCode, GitHub Copilot, and similar tools a durable file-based workflow for tracking:

• the active feature
• planned and active tasks
• task progress
• blockers and decisions
• validation steps
• handoff notes for the next agent or session

This repository contains the SDD skill blueprint and agent-specific packages for Codex, Claude Code, OpenCode, and GitHub Copilot. Each package teaches its agent how to operate the methodology through /sdd commands or repository custom instructions.

The Problem

Agentic coding work often spans more than one prompt. Context can disappear or become unreliable when:

• a chat is compacted
• a session is closed
• work resumes days later
• another agent or developer takes over
• multiple features are in progress
• decisions and validation notes live only in conversation history

When that happens, the next agent has to rediscover intent, inspect the same files again, guess the current state, and risk repeating or breaking work.

SDD solves this by storing the workflow state in plain repository files under .ai/sdd/. The repository becomes the source of truth for what is being built, what has been done, what is blocked, and what must happen next.

Why Chat Is Not Enough

Chat is useful for collaboration, but it is a weak place to store project state.

• Chat can be compacted: long conversations are often summarized, and summaries can lose decisions, failed attempts, commands, files, or edge cases.
• Chat can disappear: a session can close, expire, or become unavailable to the next agent.
• Chat is not shared state: another agent, tool, or developer may not have access to the same conversation.
• Chat can become stale: the repository may change after a message was written, so old conversation context may no longer match the code.
• Chat mixes topics: bugs, features, refactors, questions, and experiments can all appear in one thread, making the active work unclear.
• Chat hides validation evidence: test commands, failures, manual checks, and known gaps are easy to lose in the conversation.
• Chat is hard to audit: repository files are visible to the project; private or tool-specific chat history usually is not.

SDD treats chat as the place where work happens and .ai/sdd/ as the place where essential working memory is preserved. The next agent should not need the previous conversation to know the active feature, task state, blockers, validation status, and next step.

The Method

SDD is built around a simple lifecycle:

1. Initialize .ai/sdd/ in a project.
2. Create or select a feature.
3. Run feature intake before creating task files.
4. Inspect the repository so the plan matches the actual code.
5. Break the feature into typed tasks with dependencies, likely files, and validation.
6. Work one active task at a time.
7. Update task state and context as work progresses.
8. Move implemented work to to-be-validated.
9. Mark work done only after validation.
10. Write a handoff before pausing, switching work, or changing agents.

The method keeps three things connected: user intent, code changes, and validation evidence.

Why It Helps

SDD gives teams and agents:

• Continuity: work can resume without depending on previous chat context.
• Traceability: every feature and task has state, notes, and validation expectations.
• Better planning: agents ask intake questions and inspect code before creating task files.
• Safer handoffs: another agent can read the active feature and task context before editing.
• Less repeated discovery: likely files, blockers, and prior commands are captured.
• Simple adoption: state is plain text and Markdown, with no external database or service.
• Agent portability: the same methodology can be adapted to different coding agents.

SDD is not a replacement for Git, issue trackers, or tests. It is a small working-memory layer for agentic development.

Core Concepts

Concept	Meaning
Feature	A unit of work that delivers user value
Task	A smaller activity that contributes to a feature
State	A plain-text status record for a feature or task
Context	Markdown notes that let future agents resume safely
Intake	Questions used to understand a feature before planning tasks
Handoff	A compact update before pausing, switching, or changing agents
Index	A derived summary of features and tasks

Generated Project Layout

When SDD is initialized inside a target project, it creates this structure:

.ai/sdd/
├── conventions.md
├── index.md
├── current
└── features/
    └── <feature-name>/
        ├── state
        ├── description.md
        └── tasks/
            └── <task-name>/
                ├── state
                └── context.md

Key files:

• .ai/sdd/current stores the active feature name, or is empty when no feature is active.
• description.md stores feature goal, scope, acceptance criteria, constraints, and planned tasks.
• context.md stores task type, dependencies, likely files, progress, validation, notes, and handoff entries.
• index.md is a derived view built from the feature/task tree.
• state files use <state> <YYYY-MM-DD> <agent-name>.

Example state file:

in-progress 2026-04-27 codex

State Lifecycle

Valid states:

State	Meaning
todo	Planned, not started
in-progress	Actively being worked on
blocked	Waiting on a dependency, decision, or fix
to-be-validated	Implemented, awaiting review or validation
done	Completed and validated

Preferred task flow:

todo -> in-progress -> to-be-validated -> done
                  \-> blocked
blocked -> in-progress

Feature state follows task state:

• any in-progress task makes the feature in-progress
• otherwise, any blocked task makes the feature blocked
• otherwise, any to-be-validated task makes the feature to-be-validated
• if all tasks are done, the feature becomes to-be-validated
• a feature becomes done only through explicit validation

This rule prevents a feature from being silently completed just because implementation tasks finished.

Feature Intake

For a new feature, SDD should not create task files from only a name. The agent first collects enough information to plan useful work:

• goal or user outcome
• problem being solved
• in-scope work
• out-of-scope work
• acceptance criteria or validation steps
• constraints, dependencies, risks, or affected areas

After intake, the agent inspects relevant project files and proposes a task breakdown. Task files are created only after the user confirms or adjusts the plan.

Task Planning

Tasks are intentionally concrete. Each task should include:

• type
• description
• dependencies
• likely files or areas
• progress checklist
• validation steps
• notes and handoff history

Supported task types:

• discovery
• implementation
• test
• documentation
• validation
• cleanup

Handoff Discipline

Before ending a session, switching features, or handing work to another agent, SDD expects a handoff note with:

• current state and progress
• changed or likely touched files
• commands run and validation results
• blockers, risks, or unresolved decisions
• next recommended step

The goal is practical: the next agent should be able to inspect .ai/sdd/current, read the feature description and task context, then continue without relying on the previous chat.

Repository Contents

.
├── Agent.md
├── README.md
├── blueprint-skill.md
├── references/
│   └── conventions.md
├── codex/
│   ├── SKILL.md
│   ├── agents/
│   │   └── openai.yaml
│   └── references/
│       └── conventions.md
├── claude-code/
│   ├── SKILL.md
│   └── references/
│       └── conventions.md
├── opencode/
│   ├── SKILL.md
│   └── references/
│       └── conventions.md
└── github-copilot/
    └── .github/
        ├── copilot-instructions.md
        └── instructions/
            └── sdd-state.instructions.md

• blueprint-skill.md is the agent-agnostic blueprint for skill behavior and commands.
• references/conventions.md explains the shared workflow concepts and conventions.
• codex/ is the Codex-specific skill package.
• claude-code/ is the Claude Code-specific skill package.
• opencode/ is the OpenCode-specific skill package.
• github-copilot/ is the GitHub Copilot custom-instructions package.
• Agent.md explains how future agents should maintain this repository.

Agent-specific packages should mirror shared workflow changes from the blueprint unless the difference is deliberate and documented.

Installation

Install the package for your agent runtime.

For Codex, copy or symlink the codex/ package into your local skills directory:

mkdir -p ~/.codex/skills/sdd
cp -R codex/. ~/.codex/skills/sdd/

For Claude Code, copy or symlink the claude-code/ package into your Claude skills directory:

mkdir -p ~/.claude/skills/sdd
cp -R claude-code/. ~/.claude/skills/sdd/

For OpenCode, copy or symlink the opencode/ package into your OpenCode skills directory:

mkdir -p ~/.config/opencode/skills/sdd
cp -R opencode/. ~/.config/opencode/skills/sdd/

For GitHub Copilot, copy the package contents into the target repository root so Copilot can read .github/copilot-instructions.md:

cp -R github-copilot/. .

After installation, invoke or request the skill in the style your agent supports:

Use the sdd skill to initialize SDD in this repo.
/sdd init

The skill also supports implicit use when you mention SDD, state-driven development, .ai/sdd/, or /sdd commands.

Quick Start

In a repository where you want to use SDD, ask your agent to initialize the workflow:

/sdd init

Create a feature:

/sdd feature create user-auth Add login, logout, and session handling

The agent will ask for missing intake details, inspect the repository, propose typed tasks with dependencies and validation, then ask for confirmation before creating task files.

Check current workflow state:

/sdd status

Resume active or validation-ready work later:

/sdd resume

Write a handoff before pausing or switching agents:

/sdd handoff

Commands

Core commands:

/sdd
/sdd status
/sdd help
/sdd init
/sdd resume
/sdd handoff
/sdd index rebuild

Feature commands:

/sdd feature create <name> [description]
/sdd feature list
/sdd feature current
/sdd feature switch <name>
/sdd feature description <name> <text>
/sdd feature done <name>
/sdd feature delete <name>

Task commands:

/sdd task create <feature> <name> [description]
/sdd task list <feature>
/sdd task update <feature> <task> <state>
/sdd task mark <feature> <task> <state>
/sdd task context <feature> <task> [--edit]

Workflow Rules

• Read .ai/sdd/current before starting feature or task work.
• Keep feature and task names in kebab-case.
• Ask intake questions and inspect repository context before creating tasks for a new feature.
• Put task type, dependencies, likely files, validation, and handoff notes in task context.
• Update task context before ending a session or switching work.
• Use /sdd handoff before pausing, switching agents, or ending a session.
• Treat .ai/sdd/index.md as derived from the filesystem.
• Rebuild the index if it appears stale.
• Do not automatically mark a feature done just because all tasks are done.
• Use /sdd feature done <name> only after validation.

Design Principles

SDD deliberately uses simple repository files instead of a database or external service. The files are readable by humans, portable across agents, and easy to version if a team wants workflow state committed with the project.

The source of truth is the feature and task tree under .ai/sdd/features/. The index is only a convenience view.

The methodology should stay lightweight. It exists to preserve engineering context and support better agent behavior, not to create process for its own sake.