SuperAPI AI Directory

agentic-dev

Coding & development

View repository

Updated 10-16 07:12

About this skill

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)

```bash
/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