Iterative Dev

Iterative Development Workflow

Autonomous, incremental development with quality gates. One feature at a time. Implement → verify → refine → next.

Core Loop

FOR each feature (highest priority first):
    1. IMPLEMENT  — launch subagent to build, test, and commit
    2. VERIFY     — parent checks: commit exists, screenshots exist (web), tests prove outcomes
    3. REFINE     — launch subagent to polish UX + code quality, write report, commit
    4. NEXT       — immediately proceed to next feature

All three steps are mandatory. Skipping refinement is as wrong as skipping verification.

Principles

1. ONE feature at a time — finish, test, commit before moving on
2. feature_list.json is the single source of truth — see references/core/feature-list-format.md
3. Git commit after every feature and every refinement
4. Autonomous execution — never stop to ask the human, the human may be asleep
5. Subagent per feature — isolation prevents context overflow
6. Verification is non-negotiable — every feature proven working per project type
7. Refinement is non-negotiable — every feature polished for delight, not just function
8. Standards are auditable — quality lives in reference docs, verified systematically

Subagent Anti-Patterns (MUST AVOID)

These patterns were found in real sessions and waste significant time:

Project Types

Workflow: Initialize Scope

Directory Structure

project-root/
├── specs/{scope}/
│   ├── spec.md, feature_list.json, progress.txt
│   ├── screenshots/
│   └── refinements/
├── .active-scope
├── spec.md → specs/{scope}/spec.md        (symlink)
├── feature_list.json → specs/{scope}/...  (symlink)
├── progress.txt → specs/{scope}/...       (symlink)
└── init.sh

Steps

1. Check state: ls specs/ && cat .active-scope

2. Create scope: mkdir -p specs/{scope}/{screenshots,refinements}, write spec.md

3. Switch: echo "{scope}" > .active-scope, create symlinks

4. Determine project type: Browser→web, Terminal→cli, Import→library, HTTP→api, Phone→mobile, Data→data

5. Create feature list — two methods:

   • New features: Follow references/core/feature-list-format.md
   • Constitution/standards alignment: Follow references/core/constitution-audit.md

   Critical rules for features:

   • Outcome-oriented (what user can DO, not what components exist)
   • Full-stack vertical slices (backend + frontend together) — see feature-list-format.md
   • Self-contained (each feature includes its own tests — no separate "testing" features)
   • UI features MUST include screenshot + interaction test steps
   • Include "type" field in feature_list.json

6. Create init.sh — see references/core/init-script-template.md

7. Commit

Workflow: Continue Session

Startup

pwd && cat progress.txt && cat feature_list.json && git log --oneline -20
bash init.sh

Verify existing features work before implementing new ones.

Feature Loop (NON-STOP until all features pass)

Never stop to report progress. Never ask the human. Keep going until done.

For each incomplete feature (highest priority first):

Step 1: IMPLEMENT

Read references/templates/feature-subagent.md for the full prompt template. Launch via Agent tool.

Reference doc paths: The references/ directory is in THIS SKILL's install directory, not the project. Resolve to absolute paths using {skill_base_dir} shown at top of this prompt.

Step 2: VERIFY (parent agent — mandatory gates)

After the implementation subagent completes:

a. Compile gate (run BEFORE other gates — catches most subagent mistakes):

If compilation fails, launch a fix subagent immediately — do not proceed to other gates.

b. Commit gate: git log --oneline -1 — confirm feat: commit exists c. Feature list gate: confirm "passes": true in feature_list.json d. Type-specific gate:

e. If any gate fails, launch a fix subagent before proceeding. Include the FULL error output in the subagent prompt so it can fix the root cause directly.

Step 3: REFINE (mandatory — not optional)

Read references/templates/refinement-subagent.md for the full prompt template. Launch via Agent tool.

Why refinement exists: Implementation subagents build features that work. Refinement subagents make features delightful. Without refinement, UX issues (spacing, hierarchy, micro-interactions) and code smells (duplication, naming, complexity) ship uncaught. It's the quality difference between "functional" and "users love it".

Refinement gate (parent must verify after subagent completes):

# At least one refinement report must exist for this feature (each pass creates a new timestamped file)
ls specs/{scope}/refinements/feature-{id}-refinement-*.md | head -1
# Commit must exist
git log --oneline -1 | grep "refine:"

If either is missing, launch the refinement subagent again. Do NOT proceed without refinement.

Step 4: NEXT

Loop back immediately to the next incomplete feature. No pausing, no reporting.

Periodic Standards Audit

When: Every 5 features AND at session end.

For each applicable standards doc, launch audit subagent (see references/templates/audit-subagent.md). Fix violations before proceeding.

Applicable standards by type:

• All: core/code-quality.md, core/gitignore-standards.md, core/session-handoff-standards.md
• web/mobile: also web/ux-standards.md, web/frontend-design.md

Session End

Only end when ALL features have "passes": true and all refinements are committed, or a truly unrecoverable error occurs.

Before ending: final standards audit, run all tests, verify references/core/session-handoff-standards.md.

Decision Making (autonomous — human may be asleep)

Reference Files

Templates (subagent prompts)

• references/templates/feature-subagent.md — Implementation subagent prompt
• references/templates/refinement-subagent.md — Refinement subagent prompt
• references/templates/audit-subagent.md — Standards audit subagent prompt

Core Standards (all types)

• references/core/code-quality.md — File organization, testability, unit testing
• references/core/gitignore-standards.md — Files that must never be committed
• references/core/feature-list-format.md — Feature list structure and rules
• references/core/session-handoff-standards.md — Clean state at session end
• references/core/init-script-template.md — init.sh templates by project type
• references/core/constitution-audit.md — Audit workflow for compliance scopes

Web Standards (web/mobile)

• references/web/ux-standards.md — Loading/empty/error states, responsive, accessibility
• references/web/frontend-design.md — Typography, color, composition

Verification (one per type)

• references/verification/{web,api,cli,library,data,mobile}-verification.md