Delta-Spec

This project uses delta-spec for specification-driven development.

REQUIRED: Use delta-spec for all changes

When the conversation shifts from discussion to implementation—phrases like:

• "let's add that"
• "make that change"
• "can you implement..."
• "go ahead and..."
• "update the code to..."

STOP. Before using Edit or Write on any project file, run /ds:new <name> first.

Exceptions (direct edits OK)

• Fixing typos or formatting
• Changes already tracked by an active delta-spec change
• CLAUDE.md or README.md updates

Workflow

1. /ds:new <name> - Create proposal
2. /ds:plan - Explore codebase, create design + delta specs
3. /ds:tasks - Generate implementation tasks
4. Implement the changes
5. /ds:archive - Merge specs when complete

Before Starting Any Work

• Run /ds:status to check for active changes
• Review existing proposals in specs/.delta/ to avoid conflicts

Skills

Codebase Map

Use this to orient before exploring. Reduces redundant file discovery.

delta-spec/
├── .claude-plugin/
│   ├── plugin.json            # Plugin name, version (0.2.0)
│   └── marketplace.json       # Marketplace listing config
├── skills/
│   ├── _shared/
│   │   ├── version-check.md    # Shared version check procedure
│   │   ├── cycle-detection.md  # Shared cycle detection algorithm
│   │   ├── spec-format.md      # Shared base spec format + guidelines
│   │   ├── delta-format.md     # Shared delta spec format
│   │   ├── determine-change.md # Shared change resolution procedure
│   │   ├── proposal-template.md # Shared proposal template
│   │   ├── design-template.md  # Shared design document template
│   │   ├── task-format.md      # Shared task file format
│   │   └── dependency-signals.md # Shared dependency keyword patterns
│   ├── init/SKILL.md           # /ds:init
│   ├── new/SKILL.md            # /ds:new <name>
│   ├── plan/SKILL.md           # /ds:plan [name]
│   ├── tasks/SKILL.md          # /ds:tasks [name]
│   ├── archive/SKILL.md        # /ds:archive [name]
│   ├── drop/SKILL.md           # /ds:drop [name]
│   ├── spec/SKILL.md           # /ds:spec [domain|search]
│   ├── status/SKILL.md         # /ds:status
│   ├── quick/SKILL.md          # /ds:quick [name]
│   ├── adopt/SKILL.md          # /ds:adopt [name]
│   └── batch/
│       ├── SKILL.md            # /ds:batch
│       ├── references/
│       │   └── consolidation.md # Consolidation algorithm detail
│       └── examples/
│           └── batch-session.md # Example batch sessions
├── specs/
│   ├── .delta-spec.json        # Version tracking (0.1.0)
│   ├── skills.md               # Skill requirements (main spec)
│   ├── workflow.md             # Change lifecycle spec
│   ├── spec-format.md          # Spec format definition
│   ├── validation.md           # Validation rules spec
│   └── .delta/
│       └── archive/            # Completed changes (proposal + design + tasks)
├── scripts/
│   └── validate-specs.sh       # Spec format validation
├── CLAUDE.md → AGENTS.md       # Symlink
├── README.md                   # User-facing documentation
└── CHANGELOG.md                # Release history

Conventions

1. Specs are the source of truth - Code should match specs
2. Delta changes - Don't edit main specs directly, use delta format
3. Codebase-aware planning - /ds:plan explores actual code to fit approach
4. Persistent tasks - Use tasks.md files, not Claude Code's native TaskCreate
5. Archive preserves context - Completed changes kept in specs/.delta/archive/
6. Keep README in sync - After any changes to skills, workflow, or features, update README.md to match
7. Keep codebase map current - After /ds:archive, update the Codebase Map above if files were added, removed, or moved. Skip for content-only changes.

Spec Domains

Create specs by domain (e.g., auth.md, payments.md, api.md). Each spec file covers one bounded context.

Version Handling

The .delta-spec.json file tracks the version used to initialize specs:

{
  "version": "0.0.1",
  "initialized": "2026-02-02"
}

Skills check this version against the current plugin version (in .claude-plugin/plugin.json). On mismatch, warn the user and offer migration options.

Conventional Commits

All commits MUST follow Conventional Commits:

<type>(<scope>): <description>

Types

Scopes

Breaking Changes

Add ! after type/scope:

feat(spec)!: change requirement header format

Learnings

Always update this section when discovering workflow insights, gotchas, or best practices while using delta-spec.

Planning vs Implementation Dependencies

Dependencies declared in proposals are informational during planning but enforced during implementation:

• /ds:plan - Notes dependencies, proceeds without blocking (planning is safe)
• /ds:tasks - Warns about unsatisfied dependencies (implementation order matters)
• /ds:archive - Warns about unsatisfied dependencies (merge order matters)

This allows batch planning of multiple dependent changes in sequence.

Batch Workflow Pattern

When planning multiple related changes, use /ds:batch:

1. Run /ds:batch and describe all features in free-form prose
2. Review the inferred dependency graph and confirm
3. Optionally run /ds:plan for all when prompted
4. Run /ds:tasks to generate tasks (processes in dependency order)
5. Implement and archive in dependency order

Alternative (manual): /ds:new for each → /ds:plan for each → /ds:tasks

Task Ordering for Multiple Changes

When /ds:tasks is run without a name and multiple planned changes exist:

1. Independent changes (no dependencies) are processed first
2. Dependent changes follow in topological order
3. Tasks are numbered sequentially across all changes
4. Changes with only proposals (not yet planned) are skipped

Dogfooding

When improving delta-spec itself, always use delta-spec to track the changes. This:

• Validates the workflow works as intended
• Catches friction points and UX issues
• Ensures specs stay up to date with the codebase
• Demonstrates the value of spec-driven development

If a workflow feels awkward while dogfooding, that's a signal to improve it.

README Synchronization

After making changes, check if README.md needs updates. Key sections to verify:

• Skills table - Must match available /ds:* skills
• Workflow diagram - Must reflect current skill flow
• Project Structure - Must match actual directory layout
• Installation - Must reflect current setup process
• How It Works - Examples should use current syntax

When in doubt, read README.md and compare against the change you just made.