AI-Assisted Development Workflows

The Hero Flow

Every significant AI-assisted task MUST follow the Hero Flow:

┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│ EXPLORE │ → │  PLAN   │ → │  CODE   │ → │ VERIFY  │ → │ COMMIT  │
└─────────┘    └─────────┘    └─────────┘    └─────────┘    └─────────┘

1. Explore

MUST read and understand before writing any code.

Read the authentication code in src/auth/ and explain:
1. How login currently works
2. Where tokens are stored
3. What middleware validates requests

Don't write any code yet.

Trigger deeper analysis with explicit thinking requests:

Phrase	Depth
think about	Basic reasoning
think step-by-step	Structured analysis
think hard	Thorough consideration
think very carefully	Deep analysis
analyze thoroughly	Maximum depth

Think step-by-step about how we should add OAuth2 support
alongside the existing JWT auth. Consider:
- Backwards compatibility
- Session management
- Token refresh flows

2. Plan

MUST align on approach before implementation.

Create a detailed plan for adding OAuth2 support.
Include:
1. Files to create/modify
2. Order of changes
3. Testing approach
4. Potential risks

Don't implement yet — let's align on the plan first.

MUST get explicit confirmation:

Does this plan look right? Any concerns before I implement?

Why planning matters:

• Catches misunderstandings early (cheap to fix)
• Aligns AI’s approach with your expectations
• Creates documentation of decisions
• Prevents wasted implementation effort

4. Verify

This is the most important step. Without verification, AI output quality is inconsistent.

Verify your implementation:
1. Run the tests
2. Run the linter
3. Check types
4. Try the happy path manually

Report any failures and fix them.

Types of verification:

• Automated: Tests, linters, type checkers
• Visual: Screenshots, UI inspection
• Manual: Try the feature yourself
• Review: Have AI (or human) review the changes

Where verification is automated through hooks or wrapper scripts, those checks MUST surface failures rather than absorb them — see Automated Checks MUST NOT Swallow Failures.

5. Commit

MUST document changes properly:

Create a commit for this change. Include:
1. What changed and why
2. Any migration steps needed
3. Update relevant documentation

Commit checklist:

• All tests passing
• Linter passing
• Types checking
• Documentation updated
• Commit message explains “why”

---

TDD and the 3-Way Compare

When working with AI, MUST maintain alignment between three artifacts:

              ┌──────────────┐
              │     SPEC     │
              │  (What we    │
              │   want)      │
              └──────┬───────┘
                     │
             ┌───────┴───────┐
             │               │
             ▼               ▼
     ┌──────────────┐ ┌──────────────┐
     │    TESTS     │ │    CODE      │
     │  (How we     │ │  (How we     │
     │   verify)    │ │   build)     │
     └──────────────┘ └──────────────┘

The 3-Way Compare

All three MUST align:

Artifact	Contains	Source of Truth For
Spec	Requirements, acceptance criteria	What we’re building
Tests	Assertions, expected behavior	Whether it works
Code	Implementation	How it works

Minimum Iterations

SHOULD iterate at least 2-3 times:

Pass	Focus
1st	Structure and layout
2nd	Styling and spacing
3rd	Polish and edge cases

Tools for Visual Iteration

• Manual: Paste screenshots into conversation
• Browser extensions: Auto-capture tools
• Built-in browser integration: Where the tool ships one, prefer it — Claude Code drives Chrome directly, with no MCP server to install (Claude Code CLI)
• Playwright MCP: Programmatic screenshots via a version-pinned @playwright/mcp server
• Visual regression: CI-based comparison

Screenshot tooling MUST be pinned to an exact version and reviewed before use. @anthropic/mcp-puppeteer, still widely copied from older guides, does not exist on the npm registry, and @modelcontextprotocol/server-puppeteer is deprecated; both fail before the first screenshot.

---

Completion Criteria

MUST define explicit completion criteria:

This task is complete when:
1. All tests pass (npm test exits 0)
2. Linter passes (npm run lint exits 0)
3. Type check passes (npm run typecheck exits 0)
4. The feature works end-to-end (manual verification)
5. Documentation is updated

Keep working until all criteria are met.

Automated continuation is bounded. Where a tool re-prompts the agent from a completion hook, it caps the number of consecutive continuations — Claude Code stops after eight². Completion criteria MUST be treated as a gate that reports unfinished work, not as a guarantee that the agent never stops early: check the result yourself before treating a long-running task as done.

Verification Between Steps

SHOULD verify after each significant change:

After each file you modify:
1. Run relevant tests
2. Run linter on that file
3. Verify no type errors introduced

Only proceed if all checks pass.

Automated Checks MUST NOT Swallow Failures

An automated check is only worth running if its failure reaches the agent. Wrapper commands that mask a non-zero status defeat the whole loop:

# Don't: the hook reports success whatever the formatter did
npm run format -- --write "$file" || true

# Don't: a per-file check that only ever prints to a log nobody reads
npm run lint:file -- "$file" 2>/dev/null

# Do: fail loudly, with the reason on stderr
if ! output=$(npm run lint:file -- "$file" 2>&1); then
  printf 'lint failed on %s:\n%s\n' "$file" "$output" >&2
  exit 2  # the exit status your runner treats as blocking
fi

Rules:

• Per-file automation MUST NOT append || true or otherwise rewrite a failing status as success.
• A failing check MUST produce a short, specific reason the agent can act on — the failing command, the file, and the first lines of its output.
• Per-file checks are a fast signal, not proof. Every task MUST end with a deterministic whole-change gate that runs the full test, lint, and type-check commands over the repository.
• The gate’s exit status MUST match the convention its runner treats as blocking. Claude Code, for example, blocks on exit code 2 and ignores exit code 1²; see Claude Code CLI.