---
name: dicklesworthstone/specs-dev
source: https://app.decimal.ai/s/dicklesworthstone-specs-dev@1/SKILL.md
source_sha256: 642e04137d2b
---

# Specs-Dev Workflow

A disciplined, review-gated development workflow ensuring quality through structured planning and iterative implementation.

## When to Use

- Implementing new features
- Complex refactoring
- Any task requiring planning before coding
- When user requests "plan first" or "spec-driven" approach
- Multi-file changes that benefit from review gates

## Workflow Overview

| Phase             | Purpose                       | Exit Criteria                |
| ----------------- | ----------------------------- | ---------------------------- |
| 1. Discovery      | Understand requirements       | User approves summary        |
| 2. Planning       | Create reviewed plan          | Plan reviewed and approved   |
| 3. Implementation | Iterative coding with reviews | All tasks complete, reviewed |
| 4. Completion     | Final validation              | Tests pass, docs updated     |

## Phase 1: Discovery

**Goal:** Reach shared understanding before planning.

1. Interpret the request — state initial understanding
2. Ask clarifying questions (goals, constraints, success criteria, out-of-scope)
3. Iterate — reflect answers, tighten understanding
4. Summarize — present final requirements

**Gate A:** "Do I understand correctly? Should I proceed to create the plan?" — Wait for approval.

## Phase 2: Planning

**Goal:** Create a comprehensive, reviewed implementation plan.

1. Draft plan using `references/templates/plan.md`
2. Review loop with reviewer (max 3 rounds) — see `references/agents/reviewer.md`
3. Integrate feedback, iterate until approved
4. **Gate B:** Present to user, wait for approval
5. Create session: `.agents/sessions/{YYYY-MM-DD}-{feature-name}/`
6. Save `plan.md` and `tasks.md` (use `references/templates/`)

Quality gates: see `references/gates.md`

## Phase 3: Implementation

**Goal:** Implement tasks iteratively with approval-gated review loops.

> ⚠️ **MANDATORY: You MUST follow `references/loop.md`** — Read and execute the implementation loop exactly as specified. Do not skip or deviate from the defined state machine.

**Summary:** For each task:

```
IMPLEMENTING → VALIDATING → REVIEWING → loop until approved → COMMITTING → DOCUMENTING → NEXT TASK
```

**Required Steps:**

1. **Read `references/loop.md`** before starting any implementation
2. Follow the state machine transitions exactly
3. Complete each state's requirements before transitioning
4. Max 3 iterations per task before escalating to user
5. Subagents: `references/agents/worker.md`, `references/agents/reviewer.md`

Quality gates: see `references/gates.md`

## Phase 4: Completion

**Goal:** Final validation and wrap-up.

1. Run full test suite
2. Update `plan.md` with results, final status, known issues
3. Verify all tasks complete in `tasks.md`
4. Summarize completed work, risks, outcomes
5. Confirm with user — session ready for merge/release

Quality gates: see `references/gates.md`

## Subagent Delegation

**Reviewer** — Plan reviews, code reviews:

```
Context: references/agents/reviewer.md
Task: Review [plan/code] for completeness, security, performance, patterns
```

**Worker** — Focused implementation:

```
Context: references/agents/worker.md
Task: Implement [objective] in [files] with [acceptance criteria]
```

## Session Structure

```
.agents/sessions/{YYYY-MM-DD}-{feature-name}/
├── plan.md      # Strategic plan
└── tasks.md     # Tactical tasks
```

## References

```
references/
├── loop.md          # Phase 3 state machine, steps, fix routing
├── gates.md         # Quality gates for all phases
├── help.md          # Common issues, best practices
├── agents/
│   ├── reviewer.md  # Reviewer subagent context
│   └── worker.md    # Worker subagent context
└── templates/
    ├── plan.md      # Plan document template
    └── tasks.md     # Tasks document template
```

| File                 | When to Read                      |
| -------------------- | --------------------------------- |
| `loop.md`            | Phase 3 (MANDATORY — must follow) |
| `agents/reviewer.md` | Plan/code reviews                 |
| `agents/worker.md`   | Task implementation               |
| `templates/plan.md`  | Phase 2                           |
| `templates/tasks.md` | Phase 2                           |
| `gates.md`           | Each phase exit                   |
| `help.md`            | When stuck                        |