Agentic Development

Spec-driven development workflow with OpenSpec for change tracking. Supports both interactive (human-in-loop) and fully automated (Ralph Loop) execution.

When to Use

dot

digraph when_to_use {
    "New feature or change?" [shape=diamond];
    "Bug fix or typo?" [shape=diamond];
    "Use /agentic-dev proposal" [shape=box];
    "Fix directly, skip OpenSpec" [shape=box];
    "Proposal approved?" [shape=diamond];
    "Human available?" [shape=diamond];
    "/agentic-dev apply (interactive)" [shape=box];
    "/agentic-dev apply --mode=auto" [shape=box];
    "Implementation complete?" [shape=diamond];
    "Use /agentic-dev done" [shape=box];

    "New feature or change?" -> "Bug fix or typo?" [label="yes"];
    "Bug fix or typo?" -> "Fix directly, skip OpenSpec" [label="yes"];
    "Bug fix or typo?" -> "Use /agentic-dev proposal" [label="no - new capability"];
    "Use /agentic-dev proposal" -> "Proposal approved?";
    "Proposal approved?" -> "Human available?" [label="yes"];
    "Human available?" -> "/agentic-dev apply (interactive)" [label="yes"];
    "Human available?" -> "/agentic-dev apply --mode=auto" [label="no - Ralph Loop"];
    "/agentic-dev apply (interactive)" -> "Implementation complete?";
    "/agentic-dev apply --mode=auto" -> "Implementation complete?";
    "Implementation complete?" -> "Use /agentic-dev done" [label="yes"];
}

Three-Phase Workflow

Phase	Command	Output
1. Proposal	`/agentic-dev proposal`	OpenSpec proposal files
2. Apply	`/agentic-dev apply <id> [--mode]`	Implemented code
3. Done	`/agentic-dev done <id>`	Archived + specs updated

Phase Details

Phase 1: Proposal

Creates OpenSpec change proposal through brainstorming:

•Understand context - Check project state
•Ask questions - One at a time, multiple choice preferred
•Propose approaches - 2-3 options with trade-offs
•Incremental design - Present in 200-300 word sections, validate each
•Create tasks - Break into implementable tasks
•Generate OpenSpec files - proposal.md, design.md, tasks.md, spec deltas

Methodology: @prompts/brainstorming.md

Completion signal: <promise>PROPOSAL COMPLETE</promise>

Phase 2: Apply

Two modes available:

Interactive Mode (default)

bash

/agentic-dev apply add-shortcuts

•Review checkpoints after each task
•Human can intervene between tasks
•Higher quality assurance

Auto Mode (Ralph Loop)

bash

/agentic-dev apply add-shortcuts --mode=auto

•One task per iteration
•Self-review only
•Updates tasks.md as state machine
•Unattended execution

Methodology: @prompts/tdd.md, @prompts/review.md

Completion signal: <promise>IMPLEMENTATION COMPLETE</promise>

Phase 3: Done

Completes and archives the change:

•Verify all tasks completed in tasks.md
•Verify tests pass
•Present branch options (merge/PR/keep/discard)
•Archive to OpenSpec
•Validate specs updated

Methodology: @prompts/branch-completion.md

Completion signal: <promise>ARCHIVE COMPLETE</promise>

Output Structure

code

openspec/changes/<change-id>/
├── proposal.md      # Metadata
├── design.md        # Architecture and approach
├── tasks.md         # Implementation tasks (state machine)
└── specs/           # Spec deltas
    └── <capability>/
        └── spec.md

Methodology Files

File	Purpose
`@prompts/brainstorming.md`	Collaborative design exploration
`@prompts/tdd.md`	Test-driven development
`@prompts/review.md`	Self and code review
`@prompts/branch-completion.md`	Branch finishing workflow

Ralph Loop Integration

For fully automated implementation:

bash

/ralph-loop "/agentic-dev apply <change-id> --mode=auto" \
  --completion-promise "IMPLEMENTATION COMPLETE" \
  --max-iterations 50

Self-check mechanism: Each iteration reads tasks.md, finds next uncompleted - [ ] item, executes it, updates to - [x], outputs promise, stops. Ralph Loop re-invokes until all done.

Promise Tags

Event	Promise
Proposal complete	`<promise>PROPOSAL COMPLETE</promise>`
Single task done	`<promise>TASK N COMPLETE</promise>`
All implementation done	`<promise>IMPLEMENTATION COMPLETE</promise>`
Archive complete	`<promise>ARCHIVE COMPLETE</promise>`

Mode Comparison

Aspect	Interactive	Auto
Review	Self + checkpoints	Self only
Human	Can intervene	Unattended
Cost	Higher	Lower
Quality	Maximum	Good (TDD enforced)
Use case	Complex features	Overnight runs

Prerequisites

•OpenSpec configured in project (openspec/ directory)
•ralph-loop plugin (optional, for auto mode)

Quick Reference

bash

# Phase 1: Create proposal
/agentic-dev proposal
> I want to add keyboard shortcuts support...

# Phase 2: Implement (interactive - human present)
/agentic-dev apply add-shortcuts

# Phase 2: Implement (auto - Ralph Loop)
/ralph-loop "/agentic-dev apply add-shortcuts --mode=auto" --completion-promise "IMPLEMENTATION COMPLETE"

# Phase 3: Archive
/agentic-dev done add-shortcuts