agentic-dev

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

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:

1. Understand context - Check project state
2. Ask questions - One at a time, multiple choice preferred
3. Propose approaches - 2-3 options with trade-offs
4. Incremental design - Present in 200-300 word sections, validate each
5. Create tasks - Break into implementable tasks
6. 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)

/agentic-dev apply add-shortcuts

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

Auto Mode (Ralph Loop)

/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:

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

Methodology: @prompts/branch-completion.md

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

Output Structure

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:

/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

# 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