Board Format Specification

The .super-human/board.md file is the single source of truth for a Super-Human execution. It tracks everything from intake through convergence and is designed to be both human-readable and machine-parseable.

File Location

{project-root}/.super-human/board.md

The .super-human/ directory may also contain:

• board.md - the main board file (always present)
• Historical boards renamed to board-{timestamp}.md (if running multiple sessions)

Board Metadata (YAML Frontmatter)

---
id: sh-{timestamp}
title: "{brief description of the overall task}"
status: intake | decomposing | discovering | planning | executing | verifying | converged | completed | abandoned
created: "{ISO 8601 timestamp}"
updated: "{ISO 8601 timestamp}"
git_tracked: true | false
total_tasks: {N}
completed_tasks: {N}
failed_tasks: {N}
current_wave: {N}
total_waves: {N}
---

Board Sections

The board is organized into sections that correspond to the 7 phases. Each section is populated as the relevant phase completes.

Section 1: Intake Summary

## Intake Summary

- **Task**: {one-line description}
- **Type**: feature | bug | refactor | greenfield | migration
- **Complexity**: simple | medium | complex
- **Problem**: {what needs to be built/fixed}
- **Success Criteria**: {what "done" looks like}
- **Constraints**: {patterns, libraries, conventions to follow}
- **Dependencies**: {external APIs, services, other work}
- **Edge Cases**: {known edge cases} (if complex)
- **Testing Strategy**: {approach to testing} (if complex)
- **Board Persistence**: git-tracked | gitignored

Section 2: Task Graph

## Task Graph

### Sub-tasks

| ID | Title | Type | Size | Dependencies | Wave | Status |
|----|-------|------|------|-------------|------|--------|
| SH-001 | {title} | code | S | - | 1 | done |
| SH-002 | {title} | code | M | SH-001 | 2 | in-progress |
| SH-003 | {title} | test | S | SH-002 | 3 | pending |

### Dependency Graph

{ASCII graph - see dependency-graph-patterns.md}

### Wave Assignments

- **Wave 1** (N tasks): SH-001, SH-002 [parallel]
- **Wave 2** (N tasks): SH-003 [serial]
- **Wave 3** (N tasks): SH-004, SH-005, SH-006 [parallel]

Section 3: Sub-task Details

Each sub-task gets its own subsection that grows as phases complete:

## Tasks

### SH-001: {title}
- **Type**: code | test | docs | infra | config
- **Size**: S | M
- **Dependencies**: none | [SH-XXX, SH-YYY]
- **Wave**: {N}
- **Status**: {current status}

#### Research Notes
{populated during DISCOVER phase}
- Key files: {list of relevant files}
- Reusable code: {functions/utilities to reuse}
- Patterns: {conventions observed}
- Risks: {any risks identified}
- External docs: {URLs referenced}

#### Execution Plan
{populated during PLAN phase}
- Files to create: {list}
- Files to modify: {list}
- Test files: {list}
- Approach: {brief description}
- Acceptance criteria:
  - [ ] {criterion 1}
  - [ ] {criterion 2}
- Test cases:
  - {test case 1}
  - {test case 2}

#### Verification
{populated during VERIFY phase}
- Status: PASS | FAIL
- Tests: {passed}/{total} ({new} new)
- Lint: clean | {issues}
- Type Check: pass | {errors}
- Build: pass | fail
- Retries: {used}/{max}
- Notes: {context}

Section 4: Execution Log

## Execution Log

### Wave 1 - {timestamp}
- Started: {timestamp}
- Tasks: SH-001, SH-002
- Agents: 2 parallel
- Completed: {timestamp}
- Result: all passed | {N} failed

### Wave 2 - {timestamp}
- Started: {timestamp}
- Tasks: SH-003
- Agents: 1 serial
- Completed: {timestamp}
- Result: all passed

Section 5: Convergence Summary

## Convergence Summary

### Files Changed
| File | Action | Lines |
|------|--------|-------|
| src/models/user.ts | created | +45 |
| src/api/auth.ts | created | +120 |
| src/api/auth.test.ts | created | +85 |
| src/middleware/auth.ts | modified | +30, -5 |

### Tests Added
- Total new tests: {N}
- Test files: {list}
- Coverage: {percentage if available}

### Key Decisions
- {decision 1 and why}
- {decision 2 and why}

### Deferred Work
- {anything not completed and why}
- {follow-up tasks suggested}

### Suggested Commit Message

{emoji} {type}: {subject}

{body with summary of changes}

Status Transitions

Board-Level Status

intake --> decomposing --> discovering --> planning --> executing --> verifying --> converged --> completed
                                                                                      |
                                                                                      +--> abandoned

Task-Level Status

pending --> researching --> planned --> in-progress --> verifying --> done
                                          |                |
                                          +-- blocked      +-- failed

Valid Transitions

Resuming a Board Across Sessions

When starting a new session and a .super-human/board.md exists:

1. Read the board - parse the frontmatter and current state
2. Identify the current phase from the board status
3. Find incomplete tasks - any task not in done or failed status
4. Resume from the current phase:
   • If executing: continue with the next unfinished wave
   • If verifying: re-run verification on unverified tasks
   • If discovering or planning: continue research/planning for remaining tasks
5. Update the board with a "Resumed at {timestamp}" entry in the execution log

Resume Detection

At the start of any Super-Human invocation:

1. Check if .super-human/board.md exists
2. If yes, ask the user: "Found an existing Super-Human board. Resume it or start fresh?"
3. If resuming, load the board and continue from where it left off
4. If starting fresh, archive the old board as board-{timestamp}.md

Example: Complete Board

---
id: sh-1710432000
title: "Add user authentication to Next.js app"
status: executing
created: "2026-03-14T10:00:00Z"
updated: "2026-03-14T11:30:00Z"
git_tracked: false
total_tasks: 8
completed_tasks: 3
failed_tasks: 0
current_wave: 2
total_waves: 4
---

## Intake Summary

- **Task**: Add email/password + Google OAuth authentication
- **Type**: feature
- **Complexity**: complex
- **Problem**: App has no auth - need login, register, protected routes
- **Success Criteria**: Users can register, login (email + Google), access protected routes
- **Constraints**: Use NextAuth.js v5, existing Prisma + PostgreSQL
- **Dependencies**: Google OAuth credentials needed
- **Edge Cases**: Session expiry, multiple tabs, password reset
- **Testing Strategy**: E2e for auth flows, unit for middleware
- **Board Persistence**: gitignored

## Task Graph

### Sub-tasks

| ID | Title | Type | Size | Dependencies | Wave | Status |
|----|-------|------|------|-------------|------|--------|
| SH-001 | NextAuth config + providers | config | S | - | 1 | done |
| SH-002 | User + Account Prisma models | config | S | - | 1 | done |
| SH-003 | Auth API route handler | code | M | SH-001, SH-002 | 2 | in-progress |
| SH-004 | Auth middleware for protected routes | code | M | SH-001 | 2 | in-progress |
| SH-005 | Login page component | code | M | SH-003 | 3 | pending |
| SH-006 | Register page component | code | M | SH-003 | 3 | pending |
| SH-007 | Auth e2e tests | test | M | SH-005, SH-006 | 4 | pending |
| SH-008 | Auth API documentation | docs | S | SH-003 | 4 | pending |

### Wave Assignments

- **Wave 1** (2 tasks): SH-001, SH-002 [parallel] - COMPLETED
- **Wave 2** (2 tasks): SH-003, SH-004 [parallel] - IN PROGRESS
- **Wave 3** (2 tasks): SH-005, SH-006 [parallel] - PENDING
- **Wave 4** (2 tasks): SH-007, SH-008 [parallel] - PENDING

## Tasks

### SH-001: NextAuth config + providers
- **Type**: config
- **Size**: S
- **Dependencies**: none
- **Wave**: 1
- **Status**: done

#### Research Notes
- NextAuth v5 uses `auth.ts` at project root
- Existing env pattern: `.env.local` with `DATABASE_URL`
- Need: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `NEXTAUTH_SECRET`

#### Execution Plan
- Files to create: `auth.ts`, `app/api/auth/[...nextauth]/route.ts`
- Test files: none (config, verified by build)
- Approach: Configure NextAuth with Credentials + Google provider

#### Verification
- Status: PASS
- Tests: N/A (config)
- Build: pass
- Notes: Auth config loads, providers registered

## Execution Log

### Wave 1 - 2026-03-14T10:15:00Z
- Started: 2026-03-14T10:15:00Z
- Tasks: SH-001, SH-002
- Agents: 2 parallel
- Completed: 2026-03-14T10:25:00Z
- Result: all passed

### Wave 2 - 2026-03-14T10:26:00Z
- Started: 2026-03-14T10:26:00Z
- Tasks: SH-003, SH-004
- Agents: 2 parallel
- Status: in-progress

Dependency Graph Patterns

This reference covers how to decompose tasks into dependency graphs, common patterns, the ASCII rendering format, and the wave assignment algorithm.

Identifying Dependencies

A task B depends on task A if:

• B needs code/files that A creates
• B extends or modifies A's output
• B tests functionality that A implements
• B documents behavior that A defines
• B configures infrastructure that A requires

A task B does NOT depend on A if:

• They modify different files with no shared interfaces
• They implement independent features
• They can be tested in isolation

Dependency Checklist

For each pair of tasks, ask:

1. Does task B need any file that task A creates? -> dependency
2. Does task B import or use any function/type that task A defines? -> dependency
3. Does task B test code that task A writes? -> dependency
4. Can task B's tests pass without task A being complete? -> if yes, no dependency

Common DAG Patterns

Linear Chain

One task after another. No parallelism possible.

SH-001 --> SH-002 --> SH-003 --> SH-004

When it occurs: Sequential migrations, step-by-step setup Waves: Each task is its own wave (worst case for parallelism)

Fan-Out

One task fans out to many independent tasks.

            +---> SH-002
            |
SH-001 ----+---> SH-003
            |
            +---> SH-004

When it occurs: After initial setup, multiple independent features branch off Waves: Wave 1 = SH-001, Wave 2 = SH-002 + SH-003 + SH-004

Fan-In

Many independent tasks converge to one.

SH-001 ---+
           |
SH-002 ---+---> SH-004
           |
SH-003 ---+

When it occurs: Integration testing after parallel implementation Waves: Wave 1 = SH-001 + SH-002 + SH-003, Wave 2 = SH-004

Diamond

Fan-out followed by fan-in.

            +---> SH-002 ---+
            |                |
SH-001 ----+                +---> SH-005
            |                |
            +---> SH-003 ---+
            |                |
            +---> SH-004 ---+

When it occurs: Setup -> parallel features -> integration Waves: Wave 1 = SH-001, Wave 2 = SH-002 + SH-003 + SH-004, Wave 3 = SH-005

Independent Clusters

Multiple disconnected sub-graphs that can run entirely in parallel.

Cluster A:  SH-001 --> SH-002
Cluster B:  SH-003 --> SH-004 --> SH-005
Cluster C:  SH-006

When it occurs: Unrelated features being built simultaneously Waves: Wave 1 = SH-001 + SH-003 + SH-006, Wave 2 = SH-002 + SH-004, Wave 3 = SH-005

Layered Architecture

Tasks organized by architectural layers.

Layer 1 (infra):    SH-001, SH-002
Layer 2 (data):     SH-003, SH-004    (depend on Layer 1)
Layer 3 (logic):    SH-005, SH-006    (depend on Layer 2)
Layer 4 (UI):       SH-007, SH-008    (depend on Layer 3)
Layer 5 (tests):    SH-009, SH-010    (depend on Layer 4)

When it occurs: Full-stack feature development Waves: One wave per layer

Wave Assignment Algorithm

Algorithm (Topological Sort + Depth Grouping)

function assignWaves(tasks):
  // Calculate depth for each task
  for each task in tasks:
    if task has no dependencies:
      task.depth = 0
    else:
      task.depth = max(dependency.depth for dependency in task.dependencies) + 1

  // Group by depth
  waves = group tasks by task.depth

  // Wave 1 = depth 0, Wave 2 = depth 1, etc.
  return waves

Rules

1. Tasks with no dependencies are always Wave 1
2. A task's wave = max(wave of its dependencies) + 1
3. All tasks in the same wave can execute in parallel
4. Waves execute in strict sequential order
5. If a wave has only 1 task, it still counts as a wave (serial execution)

Optimization

• If two tasks are in the same wave but modify the same file, move one to a later wave to prevent conflicts
• If a wave has more tasks than available parallel agents, split it into sub-waves

ASCII Graph Rendering Format

Conventions

• --> for dependency edges (A --> B means "B depends on A")
• + for branch points
• | for vertical connections
• Indent child tasks under their parents
• Include task type and title in brackets

Standard Format

Task Graph:
  SH-001 [type: title]
    |
    +---> SH-002 [type: title]
    |       |
    |       +---> SH-004 [type: title]
    |
    +---> SH-003 [type: title]

With Wave Annotations

Task Graph:
  [W1] SH-001 [config: Init project structure]
         |
         +---> [W2] SH-002 [code: Database schema]
         |            |
         |            +---> [W3] SH-004 [code: User model]
         |
         +---> [W2] SH-003 [code: API router setup]

Wave Summary:
  Wave 1 (1 task):  SH-001
  Wave 2 (2 tasks): SH-002, SH-003  [parallel]
  Wave 3 (1 task):  SH-004

Example: Full-Stack Feature Decomposition

Task: "Add a commenting system to blog posts"

Sub-tasks identified:

• SH-001: Create Comment database model and migration (config, S)
• SH-002: Create Comment API endpoints - CRUD (code, M)
• SH-003: Create CommentList UI component (code, M)
• SH-004: Create CommentForm UI component (code, S)
• SH-005: Wire API to UI with data fetching (code, M)
• SH-006: Add comment notification system (code, M)
• SH-007: Write API integration tests (test, M)
• SH-008: Write UI component tests (test, S)
• SH-009: Update API documentation (docs, S)

Dependencies:

• SH-002 depends on SH-001 (needs the model)
• SH-003 depends on nothing (can use mock data)
• SH-004 depends on nothing (can use mock data)
• SH-005 depends on SH-002, SH-003, SH-004 (wires them together)
• SH-006 depends on SH-002 (needs API to trigger notifications)
• SH-007 depends on SH-002 (tests the API)
• SH-008 depends on SH-003, SH-004 (tests the components)
• SH-009 depends on SH-002 (documents the API)

Graph:

  SH-001 [config: Comment model + migration]
    |
    +---> SH-002 [code: Comment CRUD API]
    |       |
    |       +---> SH-005 [code: Wire API to UI] (also depends on SH-003, SH-004)
    |       +---> SH-006 [code: Notification system]
    |       +---> SH-007 [test: API integration tests]
    |       +---> SH-009 [docs: API documentation]
    |
    (independent)
    SH-003 [code: CommentList component]
    |       |
    |       +---> SH-005 (see above)
    |       +---> SH-008 [test: UI component tests] (also depends on SH-004)
    |
    SH-004 [code: CommentForm component]

Wave Assignment:

  Wave 1 (3 tasks): SH-001, SH-003, SH-004    [parallel]
  Wave 2 (1 task):  SH-002                      [serial - needs SH-001]
  Wave 3 (4 tasks): SH-005, SH-006, SH-007, SH-008, SH-009  [parallel]

Note: SH-005 depends on SH-002 (Wave 2) AND SH-003, SH-004 (Wave 1), so it goes in Wave 3. SH-008 depends on SH-003, SH-004 (Wave 1), so it could be Wave 2, but since it also tests the components, waiting for Wave 2 to complete is cleaner.

Execution Patterns and Anti-Patterns

Scope Creep Guard

During EXECUTE, agents may discover additional work needed ("oh, this also needs X"). Handle scope creep strictly:

1. Blocking discovery (can't complete the current task without it): Add a new task to the DAG, assign it to the current or next wave, and flag the change to the user on the board. Continue with other tasks in the wave.
2. Non-blocking discovery (nice-to-have, related improvement, cleanup): Do NOT absorb it. Add it to a ## Deferred Work section on the board. Mention it in the CONVERGE summary. The user decides whether to start a new Super-Human session for it.
3. Never silently expand scope - every addition to the DAG must be visible on the board and flagged in the next progress report.

Handling Blocked Tasks

If a task cannot proceed:

1. Mark it as blocked on the board with a reason
2. Continue with non-blocked tasks in the same wave
3. After the wave completes, reassess blocked tasks
4. If the blocker is resolved, add the task to the next wave

Handling Failures

If an agent fails to complete a task:

1. Capture the error/failure reason on the board
2. Attempt one retry with adjusted approach
3. If retry fails, mark as failed and flag for user attention with the rollback point hash
4. Continue with other tasks - don't let one failure block the wave

See references/wave-execution.md for detailed agent orchestration patterns.

Mandatory Tail Tasks

Every Super-Human task graph must include these three tasks as the final tasks, in this order:

Third-to-last task: Self Code Review

• Type: review
• Title: "Self code review of all changes"
• Description: Run a structured code review of all changes made across every completed sub-task using the code-review-mastery methodology. Get the full diff of all changes since the rollback point. Execute the review pyramid bottom-up: Security > Correctness > Performance > Design > Readability > Convention > Testing. Classify each finding as [MAJOR] or [MINOR]. Fix all [MAJOR] findings immediately and address reasonable [MINOR] findings. Re-run the review after fixes to confirm no new issues were introduced. Only proceed when no [MAJOR] findings remain.
• Dependencies: All other implementation/test/docs tasks
• Acceptance Criteria: Zero [MAJOR] findings remaining after fixes. All [MINOR] findings documented on the board (fixed or explicitly deferred).

Second-to-last task: Requirements Validation

• Type: verify
• Title: "Validate changes against original requirements"
• Description: Review all changes made across every completed sub-task and compare them against the original user prompt and intake summary. Verify that every requirement, success criterion, and constraint from INTAKE is satisfied. If any requirement is unmet or the implementation deviates from what was asked, flag the gaps and loop back to EXECUTE to address them. Do NOT proceed to the final task until all requirements are confirmed met.
• Dependencies: The self code review task above
• Acceptance Criteria: Every success criterion from INTAKE is demonstrably satisfied. If gaps are found, reiterate until they are resolved.

Last task: Full Project Verification

• Type: verify
• Title: "Run full project verification suite"
• Description: Run all available verification checks in the repo, in order. Use the project's package manager scripts (check package.json, Makefile, pyproject.toml, etc.) - never invoke tools directly. Skip any that are not configured in the project - only run what exists:
  1. Tests - Run the test script (npm test, yarn test, pnpm test, make test, pytest, etc.)
  2. Lint - Run the lint script (npm run lint, yarn lint, pnpm lint, make lint, etc.)
  3. Typecheck - Run the typecheck script (npm run typecheck, yarn typecheck, pnpm typecheck, make typecheck, etc.)
  4. Build - Run the build script (npm run build, yarn build, pnpm build, make build, etc.)
• Dependencies: The requirements validation task above
• Acceptance Criteria: All available checks pass. If any check fails, fix the issues and re-run until green. Do not mark the board as complete until every available check passes.

Agent Context Handoff Format

Each parallel agent receives a standardized prompt with these sections:

## Task: {SH-XXX} - {Title}

### Context
{Description from the board}

### Project Conventions
{Detected conventions from Codebase Convention Detection - package manager, test runner, linter, directory patterns}

### Research Notes
{Findings from DISCOVER phase for this task}

### Execution Plan
- Files to create/modify: {list}
- Test files: {list}
- Approach: {from PLAN phase}

### Acceptance Criteria
{Specific, verifiable conditions from PLAN phase}

### Rules
1. Follow TDD: write tests first, then implement
2. Use the project's existing patterns and conventions
3. Do NOT modify files outside your task scope
4. If you encounter a blocker, stop and report it - do not work around it
5. Update the board with your status when done

Wave Boundary Checks

After all tasks in a wave complete, before proceeding to the next wave:

1. Conflict Resolution

• Check if any two agents in the wave modified the same file
• If conflicts exist: review both changes, merge them intelligently (prefer the change that better satisfies its task's acceptance criteria), and verify the merged result
• If conflicts cannot be auto-resolved: flag to the user with both versions and let them decide
• Run a quick build/test check after any merge to catch integration issues early

2. Progress Report Print a compact status table after each wave:

Wave 2 Complete (3/6 waves done)
-----------------------------------------
| Task   | Status | Notes               |
|--------|--------|----------------------|
| SH-001 | done   |                      |
| SH-002 | done   |                      |
| SH-003 | done   |                      |
| SH-004 | done   | wave 2               |
| SH-005 | done   | wave 2               |
| SH-006 | next   | wave 3               |
| SH-007 | next   | wave 3               |
| SH-008 | queued | wave 4               |
-----------------------------------------

Anti-Patterns and Common Mistakes

Intake Playbook

The intake phase is the foundation of every Super-Human execution. A thorough intake prevents rework, missed requirements, and scope creep. This playbook provides the full question bank, scaling rules, and example sessions.

Question Bank by Task Type

Feature Development

Bug Fix

Refactor

Greenfield Project

Migration

Scaling Rules

When to Ask 3 Questions (Simple)

• Task touches 1-2 files
• Clear, well-defined scope ("add a button that does X")
• No external dependencies
• Existing patterns to follow
• Always ask: Problem statement, Success criteria, Constraints

When to Ask 5 Questions (Medium)

• Task touches 3-5 files or 2+ components
• Some ambiguity in requirements
• May involve external APIs
• Add: Existing code context, Dependencies

When to Ask 8-10 Questions (Complex)

• Task touches 5+ files or is cross-cutting
• Greenfield project or major refactor
• External services, migrations, or rollout concerns
• Add: Edge cases, Testing strategy, Documentation, Rollout, Priority

Complexity Detection Heuristic

Ask yourself:

1. How many files/components will this touch? (1-2: simple, 3-5: medium, 5+: complex)
2. Are there external dependencies? (no: simpler, yes: more complex)
3. Is the scope well-defined? (yes: simpler, no: more complex)
4. Does this involve data migration or backwards compatibility? (yes: complex)

Extracting Implicit Requirements

Users often omit critical requirements. Watch for these patterns:

When you detect implicit requirements, surface them as follow-up questions rather than assuming.

Example Intake Session

Task: "Add user authentication to our Next.js app"

Detected complexity: Complex (cross-cutting, external dependencies, security-sensitive)

Questions asked:

1. Problem: "What authentication method do you need? Email/password, OAuth providers (Google, GitHub), magic links, or a combination?"
2. Success criteria: "What does 'authenticated' look like? Protected routes, user profile page, session persistence across browser restarts?"
3. Constraints: "Are there existing auth patterns in the codebase, or is this the first auth implementation? Any preferred libraries (NextAuth, Clerk, custom)?"
4. Existing code: "Is there already a user model or database schema? Any existing API routes we should integrate with?"
5. Dependencies: "Which OAuth providers need to be supported? Do we need a database for sessions/users?"
6. Edge cases: "How should we handle: expired sessions, multiple tabs, password reset, account lockout?"
7. Testing: "What auth flows need e2e tests? Is there an existing test setup?"
8. Docs: "Do we need API documentation for auth endpoints?"
9. Rollout: "Is this for new users only, or do existing users need migration?"
10. Board persistence: "Should the .super-human/ board be git-tracked or gitignored?"

Intake Summary (written to board):

## Intake Summary
- Task: Add email/password + Google OAuth authentication to Next.js app
- Library: NextAuth.js v5
- Database: Existing Prisma + PostgreSQL setup
- Protected routes: /dashboard, /settings, /api/*
- Success: User can register, login, logout, and access protected routes
- Edge cases: Session expiry shows login prompt, password reset via email
- Testing: E2e tests for login, register, OAuth flow, protected route redirect
- Board: gitignored (local working state)

Verification Framework

Every Superhuman sub-task must prove it works before closing. This reference covers the TDD workflow, verification signals, integration testing, and the verification report format.

TDD Workflow Per Sub-task

The Red-Green-Refactor Cycle

RED:      Write tests that describe the desired behavior -> tests FAIL
GREEN:    Write the minimum code to make tests pass -> tests PASS
REFACTOR: Clean up the code while keeping tests green -> tests PASS

Step-by-Step

1. Read the acceptance criteria from the task's execution plan
2. Write test file(s) that encode each acceptance criterion as a test case
3. Run tests - confirm they FAIL (red phase proves tests are meaningful)
4. Implement the code to make each test pass, one at a time
5. Run tests - confirm they PASS (green phase)
6. Refactor if needed - rename, extract, simplify - while keeping tests green
7. Final run - all tests pass, lint clean, types check

Test Categories Per Sub-task

Test Naming Convention

Follow the project's existing convention. If none exists, use:

describe("{ComponentOrFunction}", () => {
  it("should {expected behavior} when {condition}", () => {
    // ...
  });
});

Verification Signals

Every completed sub-task must pass ALL applicable signals before closing.

Signal Matrix

Signal Priority

If time-constrained, verify in this order:

1. Tests (non-negotiable)
2. Build (catch compile/bundling errors)
3. Type check (catch type mismatches)
4. Lint (catch style/convention issues)
5. Format (lowest priority, auto-fixable)

Detecting Project Commands

Before running verification, detect what's available:

1. Check package.json scripts for test, lint, build, typecheck
2. Check for Makefile, pyproject.toml, Cargo.toml for project-specific commands
3. Check for CI config (.github/workflows/, .gitlab-ci.yml) to see what CI runs
4. If nothing is configured, at minimum run the test file directly

Integration Verification

When to Run Integration Checks

After each wave completes, run integration verification if:

• Tasks in the wave have shared dependencies
• Tasks in the wave create interfaces consumed by the next wave
• The wave includes both implementation and test tasks

Integration Check Protocol

1. Import Resolution

   • Verify all cross-file imports resolve
   • Check that types exported by one task match types expected by another
   • Run tsc --noEmit or equivalent to catch import issues

2. Combined Test Run

   • Run the full test suite (not just new tests)
   • If full suite is too slow, run tests for all files modified in this wave

3. Build Verification

   • Run the project build to catch bundling/compilation issues
   • Check for circular dependency warnings

4. Runtime Smoke Test (if applicable)

   • Start the application/server
   • Hit the key endpoints or render the key pages
   • Verify no runtime errors in console

Cross-Wave Integration

After the final wave, before CONVERGE:

• Run the FULL test suite
• Run the FULL build
• Verify no regressions in existing functionality

Failure Handling

Failure Categories and Responses

Retry Budget

• Each sub-task gets a maximum of 2 retry attempts
• Each retry includes the previous failure context in the agent prompt
• If all retries are exhausted, the task is marked failed

Escalation Protocol

When a task is marked failed:

1. Write a failure summary to the board including:
   • What was attempted
   • What failed and why
   • All error outputs from each attempt
2. Flag the task for user attention
3. Continue with non-dependent tasks
4. Do NOT attempt workarounds that bypass tests or checks

What NOT to Do on Failure

• Do NOT suppress or skip failing tests
• Do NOT add @ts-ignore, // eslint-disable, or # type: ignore to pass checks
• Do NOT reduce test coverage to make the suite pass
• Do NOT modify existing passing tests to accommodate bugs
• Do NOT mark a task as "done" if any verification signal fails

Verification Report Format

Each sub-task's verification results are recorded on the board in this format:

### Verification: SH-{id}
- Status: PASS | FAIL
- Tests: {passed}/{total} passing ({new_tests} new tests added)
- Lint: clean | {N} issues
- Type Check: pass | {N} errors
- Build: pass | fail
- Retries Used: {N}/2
- Notes: {any relevant context}

Example - Passing Task

### Verification: SH-003
- Status: PASS
- Tests: 24/24 passing (8 new tests added)
- Lint: clean
- Type Check: pass
- Build: pass
- Retries Used: 0/2
- Notes: All acceptance criteria verified

Example - Failed Task

### Verification: SH-006
- Status: FAIL
- Tests: 18/21 passing (3 failures in notification delivery tests)
- Lint: clean
- Type Check: pass
- Build: pass
- Retries Used: 2/2
- Notes: Email service mock not matching production API response format.
  Needs user input on correct response schema. See error log below.
  Error: Expected {status: "sent"} but received {status: "queued", id: "..."}

Wave Execution Model

This reference covers how to orchestrate parallel execution of sub-tasks in waves, including agent management, prompt templates, blocked task handling, and error recovery.

Execution Overview

for each wave in [Wave 1, Wave 2, ..., Wave N]:
  1. Gather all tasks in this wave
  2. For each task, prepare the agent prompt from the board
  3. Launch parallel agents (one per task)
  4. Wait for all agents to complete
  5. Update board with results
  6. Run cross-task verification for this wave
  7. Resolve any conflicts between parallel outputs
  8. Proceed to next wave

Agent Orchestration

Claude Code (Primary Platform)

Parallel Agents via Agent Tool: Launch multiple Agent tool calls in a single message. Each agent runs independently with its own context.

Agent 1: Execute SH-002 (Database schema)
Agent 2: Execute SH-003 (API router setup)
Agent 3: Execute SH-004 (Config files)

Worktree Isolation (for file-conflict-prone tasks): Use isolation: "worktree" when tasks in the same wave might touch overlapping files. Each agent gets an isolated copy of the repo. Changes are merged back after the wave completes.

When to use worktrees:

• Two tasks in the same wave modify the same directory
• Tasks create files with potential naming conflicts
• Complex refactors where intermediate states might conflict

When NOT to use worktrees:

• Tasks touch completely different directories
• Simple additions with no overlap
• The overhead of merging isn't worth the isolation

Other Platforms (Adaptable)

The wave model works with any agent system that supports:

• Spawning multiple independent execution contexts
• Waiting for all contexts to complete
• Collecting results from each context

Agent Prompt Template

Each agent receives a structured prompt derived from the board. Use this template:

## Task: {task.id} - {task.title}

### Context
{task.description}

### Research Notes
{task.research_notes from DISCOVER phase}

### Execution Plan
- Files to create/modify: {task.plan.files}
- Test files: {task.plan.test_files}
- Approach: {task.plan.approach}

### Acceptance Criteria
{task.plan.acceptance_criteria}

### Instructions
1. Write tests FIRST based on the acceptance criteria
2. Run the tests - they should FAIL (red phase)
3. Implement the code to make the tests pass (green phase)
4. Refactor if needed, ensuring tests still pass (refactor phase)
5. Run lint and type-check on all modified files
6. Report: files changed, tests written, tests passing, any issues

### Constraints
- Follow existing project conventions found in research notes
- Reuse existing utilities identified in research: {task.research.reusable_code}
- Do NOT modify files outside the planned scope
- If blocked, report the blocker instead of working around it

Template Customization by Task Type

For code tasks: Use the full TDD template above.

For test tasks: Skip the "write tests first" step - the task IS writing tests.

### Instructions
1. Write comprehensive tests for: {what_is_being_tested}
2. Include: happy path, edge cases, error scenarios
3. Run the tests to verify they pass against the existing implementation
4. Report: test count, coverage if available, any gaps identified

For docs tasks: No TDD, focus on accuracy.

### Instructions
1. Review the code/API that needs documentation
2. Write documentation following the project's existing doc style
3. Verify all code examples are syntactically correct
4. Report: files created/modified, sections covered

For config/infra tasks: Verify by running the tool/build.

### Instructions
1. Create/modify configuration files as planned
2. Verify the configuration works by running the relevant tool
3. Report: files changed, verification output

Handling Blocked Tasks

What Causes Blocks

• A dependency task failed and its output isn't available
• An external service is unavailable during DISCOVER
• The planned approach turns out to be infeasible during EXECUTE
• A file conflict is detected between parallel tasks

Block Resolution Protocol

When a task is blocked:
  1. Mark task status as "blocked" on the board
  2. Record the blocker reason: {why it's blocked}
  3. Record the blocking task ID (if applicable): {SH-XXX}
  4. Continue executing non-blocked tasks in the current wave
  5. After wave completes, reassess blocked tasks:
     a. If blocker is resolved -> add task to next wave
     b. If blocker persists -> flag for user attention
     c. If task can be approached differently -> revise plan and retry

Dynamic Re-Waving

If blocked tasks need to be rescheduled:

1. Remove the blocked task from its current wave
2. Recalculate its earliest possible wave based on resolved dependencies
3. Insert it into the appropriate wave
4. Update the board with the revised wave plan

Error Recovery

Failure Categories

Retry Protocol

When a task fails:
  1. Capture the error output
  2. Determine the failure category
  3. If retries remaining:
     a. Append error context to the agent prompt
     b. Re-run the agent with: "Previous attempt failed because: {error}. Fix and retry."
     c. Decrement retry counter
  4. If no retries remaining:
     a. Mark task as "failed" on the board
     b. Record the failure reason and all attempt logs
     c. Flag for user attention with a clear summary
     d. Continue with other tasks - don't block the wave

Cascade Failure Prevention

If a Wave N task fails and Wave N+1 tasks depend on it:

1. Mark dependent tasks as "blocked" (not "failed")
2. Execute non-dependent tasks in Wave N+1 normally
3. If the failed task is eventually fixed (via retry or user intervention), unblock and execute dependents

Cross-Task Verification (Post-Wave)

After all tasks in a wave complete:

1. File Conflict Check: Verify no two agents modified the same file in conflicting ways
2. Interface Compatibility: If tasks defined shared interfaces, verify they match
3. Import Resolution: Verify all cross-task imports resolve correctly
4. Combined Build: Run the build with all wave outputs combined
5. Combined Tests: Run the test suite for all tasks in the wave

If conflicts are detected:

1. Identify which tasks conflict
2. Determine priority (earlier task ID wins by default)
3. Resolve the conflict
4. Re-verify the resolution

Performance Guidelines

Optimal Wave Size

• 1-3 tasks per wave: Efficient, low coordination overhead
• 4-6 tasks per wave: Good parallelism, manageable verification
• 7+ tasks per wave: Consider splitting into sub-waves to reduce blast radius of failures

Agent Resource Management

• Each parallel agent consumes context window and compute
• For resource-constrained environments, limit concurrent agents to 3-4
• Use run_in_background: true for independent tasks that don't block your next action

When to Skip Parallelism

• Wave has only 1 task (obvious)
• All tasks in the wave modify the same file (serialize to prevent conflicts)
• Tasks have implicit dependencies not captured in the DAG (rare, indicates decomposition issue)