Build Feature Loop

Autonomous task execution loop that implements tasks one by one until complete.

Task Sizing

Each task must be completable in ONE iteration (~one context window).

Each iteration spawns a fresh subagent with no memory of previous work. If a task is too big, the agent runs out of context before finishing.

Right-sized tasks:

Add a database column + migration
Create a single UI component
Implement one server action
Add a filter to an existing list
Write tests for one module

Too big (split these):

"Build the entire dashboard" → Split into: schema, queries, components, filters
"Add authentication" → Split into: schema, middleware, login UI, session handling
"Refactor the API" → Split into one task per endpoint

Rule of thumb: If you can't describe the change in 2-3 sentences, it's too big.

Workflow

0. Initialize or load progress.txt

Check if scripts/build-feature-loop/progress.txt exists:

If it doesn't exist or user is starting a new feature:

Ask the user to describe the feature and its tasks (or reference a PRD)
Create the progress file with the task list:

# Build Progress Log
Started: [today's date]
Feature: [feature name]

## Codebase Patterns
(Patterns discovered during this feature build)

---

## Tasks

- [ ] Task 1 title
  Description: What to do
  Files: path/to/file.ts
  Depends: none

- [ ] Task 2 title
  Description: What to do
  Depends: Task 1

- [ ] Task 3 title
  Description: What to do
  Depends: Task 1

- [ ] Task 4 title
  Description: What to do
  Depends: Task 2, Task 3

---

## Completed Work
(Entries added as tasks complete)

If it exists: Read it to understand current state.

1. Sync TodoWrite with progress.txt

Parse the tasks from progress.txt and update TodoWrite so the user can see progress:

[ ] tasks → pending
[x] tasks → completed
Currently executing → in_progress

2. Find the next ready task

A task is ready when:

Status is [ ] (not completed)
All tasks listed in Depends: are completed [x]

Pick the next task:

Prefer tasks related to what was just completed (same module/area)
If no prior context, pick the first ready task

3. If no ready tasks

Check if all tasks are completed:

If ALL tasks are [x]:

Archive progress.txt:

DATE=$(date +%Y-%m-%d)
FEATURE="feature-name-here"
mkdir -p scripts/build-feature-loop/archive/$DATE-$FEATURE
mv scripts/build-feature-loop/progress.txt scripts/build-feature-loop/archive/$DATE-$FEATURE/

Commit: git add scripts/build-feature-loop && git commit -m "chore: archive progress for [feature-name]"
Stop and report "Build complete - all tasks finished!"

If some tasks are blocked (dependencies not met): Report which tasks are blocked and why

4. Execute the task

Use the Task tool to spawn a subagent with this prompt:

Implement and verify: [task-title]

[task-description]

**Files:** [files from task]

FIRST: Read scripts/build-feature-loop/progress.txt - check the "Codebase Patterns" section for important context from previous iterations.

When complete:

1. Run quality checks: `npm run typecheck` and `npm test`
   - If either fails, FIX THE ISSUES and re-run until both pass
   - Do NOT proceed until quality checks pass

2. Update AGENTS.md files if you learned something important:
   - Check for AGENTS.md in directories where you edited files
   - Add learnings that future developers/agents should know (patterns, gotchas, dependencies)
   - This is LONG-TERM memory - things anyone editing this code should know

3. Update progress.txt:
   a. Mark this task complete: change `- [ ] [task-title]` to `- [x] [task-title]`
   b. Add entry to "## Completed Work" section:
      ```
      ## [Date] - [Task Title]
      - What was implemented
      - Files changed
      - **Learnings for future iterations:**
        - Patterns discovered
        - Gotchas encountered
      ---
      ```
   c. If you discovered a reusable pattern, add it to "## Codebase Patterns" at the top

4. Commit all changes with message: `feat: [Task Title]`

5. After subagent returns

Read the updated progress.txt
Update TodoWrite to reflect completed task
Check for more ready tasks → go to step 2
If all done or blocked → report status

Progress File Location

The progress file should be at scripts/build-feature-loop/progress.txt.

Task Format in progress.txt

- [ ] Short task title
  Description: Detailed description of what to do
  Files: path/to/file1.ts, path/to/file2.ts
  Depends: none

- [ ] Another task
  Description: What to implement
  Files: src/components/Thing.tsx
  Depends: Short task title

- [x] Completed task
  Description: What was done
  Files: src/lib/util.ts
  Depends: none

Dependency rules:

Depends: none - Can start immediately
Depends: Task A - Blocked until Task A is [x]
Depends: Task A, Task B - Blocked until both are [x]

Task Discovery

While working, liberally add new tasks to progress.txt when you discover:

Failing tests or test gaps
Code that needs refactoring
Missing error handling
Documentation gaps
TODOs or FIXMEs in the code
Build/lint warnings
Performance issues

Add them to the ## Tasks section with appropriate Depends: relationships.

Task Description Guidelines

Write descriptions that a future iteration can pick up without context:

- [ ] Add priority field to tasks table
  Description: Add 'priority' column with values 'high'|'medium'|'low', default 'medium'. Create migration.
  Files: prisma/schema.prisma, prisma/migrations/
  Depends: none
  Acceptance: npm run typecheck passes, migration runs successfully

Dependency ordering (typical):

Schema/database changes (migrations)
Server actions / backend logic
UI components that use the backend
Integration / E2E tests

Browser Verification

For UI tasks, specify the right verification method in the task description:

Functional testing (checking behavior, not appearance):

Use browser_snapshot tool to read page content as accessibility tree
Use for: button exists, text appears, form works

Visual testing (checking appearance):

Use browser_take_screenshot tool to capture visual appearance
Use for: layout, colors, styling, animations

Quality Requirements

Before marking any task complete:

npm run typecheck must pass
npm test must pass
Changes must be committed
Progress must be logged

Stop Condition

When no ready tasks remain AND all tasks are completed:

Output: "Build complete - all tasks finished!"
Summarize what was accomplished

Important Notes

Each Task subagent runs with fresh context
progress.txt is the memory between iterations - keep it updated
Prefer tasks in the same area as just-completed work for better context continuity
The Task prompt MUST include instructions to update progress.txt and commit

Pre-Flight Checklist

Before starting the loop, verify:

progress.txt exists with tasks defined
At least one task has Depends: none (can start)
Each task is small enough for one iteration
Each task has clear acceptance criteria
UI tasks specify snapshot vs screenshot verification
Task descriptions have enough detail to implement without context