build

name	build
description	Build a requirement with full task details and optional instructions

Fetch a requirement's complete implementation plan and start building it with additional context.

Use BrainGrid CLI Skill: If the bg-cli skill is available, invoke it for detailed workflow guidance and best practices. The skill provides comprehensive context about BrainGrid commands, auto-detection features, and recommended workflows.

About This Command: Use this command to fetch a requirement's complete implementation plan using braingrid requirement show. This retrieves the requirement details along with all task prompts in markdown format (perfect for AI coding tools). You can optionally provide additional instructions or context to guide the implementation.

IMPORTANT INSTRUCTIONS:

1. Run commands directly - assume CLI is installed and user is authenticated
2. Handle errors reactively when they occur
3. Accept requirement ID from $ARGUMENTS or auto-detect from git branch
4. Parse remaining $ARGUMENTS as additional instructions for implementation
5. Use --format markdown for AI-ready output
6. If additional instructions provided, use them to guide implementation

Parse Arguments:

1. Get Requirement ID (first argument):

   • If $ARGUMENTS starts with REQ-, req-, or a number, use as requirement ID
   • Accept flexible formats:
     • REQ-123 (canonical)
     • req-123 (lowercase)
     • 123 (number only)
     • Full UUID
   • If no ID in arguments, auto-detect from git branch name
   • If auto-detection fails, ask user for requirement ID

2. Get Additional Instructions (remaining arguments):

   • Everything after the requirement ID is additional instructions
   • Example: /build REQ-123 focus on security and add comprehensive tests
   • These instructions provide context for implementation
   • If no additional instructions, just show the build plan

Activate Build Sentinel:

Before running any build commands or creating tasks, create the sentinel file that activates build-specific hooks:

mkdir -p .braingrid/temp

Then write the requirement ID to the sentinel file:

echo "REQ-{id}" > .braingrid/temp/build-active.local

If the requirement ID is not yet known (auto-detection), create the sentinel after the build command resolves the ID. The sentinel MUST exist before any TaskCreate calls so hooks are active.

Run Build Command:

1. Execute Build Command:

   braingrid requirement show [REQ-ID] --format markdown
   

   • Include requirement ID if provided in $ARGUMENTS
   • If $ARGUMENTS has no ID, omit the ID to use auto-detection from git branch
   • Use --format markdown for AI-ready output (default)
   • Display the full output showing:
     • Requirement details (ID, name, status, description)
     • All tasks with full prompts
     • Complete implementation plan
   • Capture requirement ID and task count from output
   • Extract requirement UUID for URL construction

2. Save requirement to temp file: Write the full markdown build output to .braingrid/temp/REQ-{id}-requirement.md using the Write tool. This persists the requirement so the agent can re-read it if context is compressed.

3. Handle Errors Reactively:

   • If command fails, show clear error message and provide guidance
   • Common issues and how to handle them:

     • CLI not installed (command not found):

       • Guide user to install: npm install -g @braingrid/cli
       • Verify installation: braingrid --version
       • Retry the build command

     • Not authenticated:

       • Guide user through braingrid login
       • This opens an OAuth2 flow in the browser
       • Verify with braingrid whoami
       • Retry the build command

     • No project initialized (error mentions project not found):

       • Guide user to run braingrid init
       • This creates .braingrid/project.json to track the active project
       • Retry the build command

     • Requirement not found:

       • Suggest running braingrid requirement list to see available requirements
       • Or suggest creating one with /specify

     • No git branch/ID: Ask user to provide requirement ID or create git branch

     • Network/API errors: Show full error message and suggest retry

Branch Setup:

Check the current branch before doing anything else:

git rev-parse --abbrev-ref HEAD

Skip branch creation if any of these are true — go straight to Task Creation:

• Branch contains REQ-{id} (e.g., tyler/REQ-12-some-feature, feature/REQ-12-foo)
• Branch matches CONV-* pattern (Conductor conversation branch — already has an isolated workspace)

Otherwise, create a BrainGrid branch:

Use braingrid requirement create-branch — not git checkout -b. The CLI creates the branch on GitHub AND registers it with BrainGrid for tracking.

braingrid requirement create-branch REQ-{id}

Then checkout using the branch name from the output:

git fetch origin && git checkout {branch-name}

Fallback — only if create-branch fails (not found, network error, GitHub not configured):

git checkout -b feature/REQ-{id}-{slug}

Warn: "⚠️ Branch created locally only. Not tracked in BrainGrid. Run braingrid requirement create-branch REQ-{id} later to register it."

---

Extract Acceptance Criteria:

After fetching the build plan, extract the acceptance criteria into a checklist file for tracking during implementation.

1. Parse acceptance criteria from the build output:

   • Find everything after the ## Acceptance Criteria heading in the requirement content
   • The section may contain ### sub-headings that group related criteria — ignore all headings
   • Each criterion starts with - Given or - **Given** (bullet-prefixed)
   • A criterion may span multiple lines (continuation lines not starting with - )
   • Collect all criteria into a flat list, stripping any heading structure

2. Write checklist file using the Write tool:

   File path: .braingrid/temp/REQ-{id}-acceptance-criteria.md

   Format — ## Acceptance Criteria heading followed by - [] lines, no subheadings, no blank lines between items:

   ## Acceptance Criteria
   - [] Given a user visits the root URL, When the page loads, Then the hero section displays the tagline and CTA.
   - [] Given a valid JWT and allowed model, When POST to messages endpoint, Then request is forwarded to Anthropic and response returned.
   - [] Given stream: true in request body, When request succeeds, Then SSE response is piped through to client.
   

   Rules:

   • Start file with ## Acceptance Criteria heading
   • Each criterion prefixed with - [] (dash, space, brackets, space)
   • Strip markdown bold formatting (**Given** → Given)
   • Join multi-line criteria into a single line (collapse line breaks within one criterion)
   • Preserve the full text of each clause
   • No blank lines between items
   • No subheadings — just the ## Acceptance Criteria heading and - [] lines
   • If no ## Acceptance Criteria section exists in the requirement, skip this step silently

3. Confirm: "📋 Extracted {count} acceptance criteria to .braingrid/temp/REQ-{id}-acceptance-criteria.md"

Create Verification State File:

After extracting acceptance criteria (only if criteria count > 0), create the verification state file that enables the Stop hook to enforce acceptance criteria verification after all tasks complete.

Write .braingrid/temp/REQ-{id}-build-verification.local.md using the Write tool:

---
active: true
iteration: 0
max_iterations: 15
requirement_id: REQ-{id}
criteria_file: .braingrid/temp/REQ-{id}-acceptance-criteria.md
started_at: "{ISO timestamp}"
---

Continue verifying acceptance criteria for REQ-{id}.

Read the acceptance criteria at `.braingrid/temp/REQ-{id}-acceptance-criteria.md`.

If you need to re-read the full requirement, it is saved at `.braingrid/temp/REQ-{id}-requirement.md`.

For each unchecked criterion (line starting with `- []`):
1. Examine the implementation code to verify the criterion is satisfied
2. Run relevant tests or check behavior if applicable
3. Change `- []` to `- [x]`
4. Add a `Proof:` line immediately below explaining HOW it's satisfied

Keep going until ALL criteria show `[x]` with proof.

Replace {id} with the actual requirement ID and {ISO timestamp} with the current ISO 8601 timestamp.

Important: Only create this file if acceptance criteria were extracted. If no ## Acceptance Criteria section was found (step was skipped), do NOT create the verification state file.

---

Task Discovery & Mode Selection (After Branch Setup):

After ensuring you're on the correct branch, discover tasks and choose implementation mode BEFORE creating Claude Code tasks:

1. Fetch requirement with JSON format (to check for tasks):

   braingrid requirement show [REQ-ID] --format json
   

   Parse the JSON response to check if tasks array exists and has items.

2. Determine task list:

   • If tasks EXIST in the BrainGrid response, use them directly
   • If NO tasks exist, analyze the requirement content (description, acceptance criteria) and determine the logical tasks needed — but do NOT call TaskCreate yet

3. Count tasks and choose implementation mode:

   a. Check for agent teams: Run echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS in Bash. b. If output is 1 (or any non-empty value) AND there are 3+ tasks: use Parallel Mode. c. Otherwise: use Sequential Mode.

Use Additional Instructions:

If additional instructions were provided in $ARGUMENTS:

• Acknowledge Instructions: Show what additional context was provided
  • Example: "I'll focus on security and add comprehensive tests as requested"
  • This acknowledgment applies to both sequential and parallel modes

---

Task Creation (After Mode Selection):

Now create the Claude Code tasks. If parallel mode was selected, create the team FIRST so tasks land in the team's task list.

If Parallel Mode: Call TeamCreate with name build-REQ-{id} (e.g., build-REQ-123) BEFORE creating any tasks.

If Sequential Mode: Skip team creation; tasks go into the default session list.

IMPORTANT — Create tasks ONE AT A TIME (sequentially, not in parallel). Hook scripts run on each TaskCreate and TaskUpdate call. Issuing multiple task tool calls in a single parallel batch causes hook runner errors. Create each task, wait for the response, then create the next. Same for TaskUpdate calls (e.g., setting blockedBy) — issue them one at a time after all tasks exist.

Then create the tasks:

1. If tasks EXIST in BrainGrid:

   For each task in the BrainGrid response:

   a. Create local Claude Code task with TaskCreate:

   TaskCreate:
     subject: "TASK {N}: {type}: {description}"
     description: [Task content/prompt from BrainGrid]
     activeForm: "{type}: {description}"
   

   Where:

   • {N} = sequential number (1, 2, 3...)
   • {type} = conventional commit type inferred from the task (feat/fix/test/refactor/docs/chore/style/perf)
   • {description} = lowercase imperative derived from the BrainGrid task title

   b. Capture the Claude Code task ID from TaskCreate response (e.g., "1", "2", etc.)

   c. Update the BrainGrid task with external_id to link it to the Claude Code task:

   braingrid task update TASK-X -r REQ-Y --external-id "[Claude task ID]"
   

   This links the BrainGrid task to the local Claude Code task via external_id. The status sync hook will use this to automatically sync status updates.

2. If NO tasks exist in BrainGrid (Claude creates them):

   For EACH task identified during the discovery phase:

   a. Create local Claude Code task FIRST with TaskCreate:

   TaskCreate:
     subject: "TASK {N}: {type}: {description}"
     description: [Detailed implementation instructions]
     activeForm: "{type}: {description}"
   

   Where {N}, {type}, {description} follow the same convention as above.

   b. Capture the task ID from TaskCreate response (e.g., "1", "2", etc.)

   c. Create in BrainGrid with external_id:

   braingrid task create -r [REQ-ID] --title "Task Title" --content "Detailed implementation instructions..." --external-id "[Claude task ID]"
   

   This links the BrainGrid task to the local Claude Code task via external_id. The status sync hook will use this to automatically sync status updates.

3. Show task list:

   After creating tasks, call TaskList to show the user their work queue.

4. Update requirement status to IN_PROGRESS:

   braingrid requirement update REQ-{id} --status IN_PROGRESS
   

   Since building a requirement means work is starting, automatically update the status.

Task Creation Guidelines (when no tasks exist):

• Create one task per acceptance criterion (or logical grouping)
• Each task should be independently completable
• Task content should include clear implementation instructions
• Consider dependencies between tasks (use TaskUpdate with blockedBy if needed)
• Aim for 3-7 tasks per requirement (not too granular, not too broad)
• Subject format: TASK N: type: description (lowercase imperative description)
• Valid types: feat, fix, docs, style, refactor, perf, test, chore
• Optional scope: TASK N: type(scope): description
• If task has blockedBy deps, append (blocked by N,N,...) to subject
• activeForm = the type: description portion (shown as spinner text)
• Commit hash added later on completion: TASK N (hash): type: description

Status Mapping (for synchronization):

Claude Code Status	BrainGrid Status
pending	PLANNED
in_progress	IN_PROGRESS
completed	COMPLETED

How status sync works: When you update a local task status using TaskUpdate, a PostToolUse hook automatically:

1. Reads the task ID from the update
2. Extracts the requirement ID from the git branch (e.g., feature/REQ-4-description)
3. Queries BrainGrid for a task with matching external_id (the Claude task ID)
4. Syncs the status to BrainGrid via CLI

Important:

• Tasks must be created with --external-id for status sync to work
• You must be on a feature branch with REQ-X in the name (e.g., feature/REQ-4-auth)
• Status sync won't run on main or branches without a requirement ID

---

Parallel Mode (Agent Teams):

Use this mode when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set and there are 3+ tasks. The team was already created in the Task Creation step above.

1. Determine teammate count: min(independent_task_count, 3) — cap at 3 teammates to avoid merge conflicts and resource exhaustion.

2. Spawn teammates: Use the Task tool with team_name and name params (braingrid-builder-1, braingrid-builder-2, braingrid-builder-3). Each teammate's spawn prompt MUST include:

   • Requirement ID, name, and branch name
   • Self-claim workflow: call TaskList → claim an unowned/unblocked task with TaskUpdate (set owner to your name) → implement → mark completed → call TaskList again → repeat until no tasks remain
   • Full requirement saved at .braingrid/temp/REQ-{id}-requirement.md — re-read if you need context
   • Reminder that PreToolUse hooks enforce commit-before-complete and naming conventions
   • git pull --rebase before starting each new task (to pick up other teammates' commits)
   • Additional instructions from $ARGUMENTS if provided

3. Lead coordinates (do NOT implement): The lead monitors TaskList, resolves blockers, and nudges idle teammates. The lead MUST NOT implement tasks itself — this avoids merge conflicts with teammates working in the same repo.

4. Verify completion: When all tasks show completed in TaskList, run the test suite once more to catch integration issues from parallel work.

5. Shutdown & cleanup: Send shutdown_request via SendMessage to each teammate, then call TeamDelete to clean up the team.

6. Acceptance criteria verification: The lead proceeds to the existing "Acceptance Criteria Verification Phase" below. The Stop hook continues to work as-is since it only fires for the lead's session.

---

Sequential Mode (Default):

Use this mode when agent teams are NOT enabled, or when there are fewer than 3 tasks.

If additional instructions were provided in $ARGUMENTS:

1. Apply to Implementation:

   • Review the tasks with the additional context in mind
   • Highlight relevant tasks or add notes
   • Example: If user said "focus on security", emphasize security-related tasks

2. Start Immediately:

   • Begin implementing the first task right away with that context applied
   • Do NOT ask the user if they want to start — just start

Begin Implementation Immediately:

After successfully fetching the build plan and creating tasks, start implementing immediately. Do NOT wait for user confirmation.

1. Start First Task:

   • Mark TASK 1 as in_progress using TaskUpdate
   • Read the task description and begin implementation

2. Iterate Through ALL Tasks Sequentially:

   • After completing a task, immediately move to the next one
   • Mark each task in_progress before starting, then completed when done
   • Do NOT stop between tasks to ask the user
   • Continue until ALL tasks are completed

3. Only Pause for Genuine Blockers:

   • Stop ONLY if there is a genuine ambiguity that cannot be resolved from the requirement, task descriptions, or codebase
   • Valid: missing credentials, conflicting requirements, unclear acceptance criteria
   • Invalid: "should I continue?", "ready for the next task?", "shall I proceed?"

Workflow Context:

The typical workflow with /build:

1. Create requirement (if not done): /specify
2. ➡️ Fetch build plan: /build REQ-X (this command)
3. Review tasks and plan approach
4. Start implementing tasks
5. Update statuses as you progress

Example Interactions:

Basic: Fetch build plan

User runs: /build REQ-123
(User is on main branch)

Claude:
1. Runs: braingrid requirement show REQ-123 --format markdown
2. Shows complete requirement and all task prompts
3. Creates branch via BrainGrid CLI:
   - Runs: braingrid requirement create-branch REQ-123
   - On success: git fetch origin && git checkout tyler/REQ-123-user-authentication-system
   - On error: Last resort fallback to local git checkout -b (warns about missing BrainGrid tracking)
4. Creates local Claude Code tasks using TaskCreate with naming convention:
   - TASK 1: feat: implement user login endpoint
   - TASK 2: feat: add session management
   - TASK 3: test: add authentication tests
   - TASK 4: feat(auth): add OAuth support (blocked by 1,2)
   - TASK 5: docs: add authentication API docs
5. Creates BrainGrid tasks with --external-id linking to Claude task IDs
6. Reports: "REQ-123: User Authentication System (5 tasks)"
7. Ready to start implementing

With additional instructions

User runs: /build REQ-123 focus on security best practices and add extensive error handling

Claude:
1. Runs: braingrid requirement show REQ-123 --format markdown
2. Shows complete build plan
3. Acknowledges: "I'll focus on security best practices and add extensive error handling"
4. Reviews tasks and highlights security-related ones
5. Immediately starts implementing TASK 1 (e.g., "TASK 1: feat: implement login endpoint") with security context applied
6. Iterates through all tasks without stopping

Auto-detect from branch

User runs: /build
(User is on branch: feature/REQ-123-user-auth)

Claude:
1. Runs: braingrid requirement show --format markdown
2. CLI auto-detects REQ-123 from branch name
3. Shows build plan for REQ-123
4. Immediately starts implementing tasks sequentially

With instructions, auto-detect ID

User runs: /build add comprehensive logging and monitoring
(User is on branch: feature/REQ-456-api-integration)

Claude:
1. Detects no requirement ID in arguments
2. Runs: braingrid requirement show --format markdown
3. CLI auto-detects REQ-456 from branch
4. Shows build plan
5. Acknowledges: "I'll add comprehensive logging and monitoring"
6. Immediately starts implementing TASK 1 with logging/monitoring focus
7. Continues through all tasks without stopping

Parallel mode (agent teams enabled)

User runs: /build REQ-789
(CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, requirement has 6 tasks)

Claude:
1. Fetches build plan, creates branch, extracts acceptance criteria
2. Discovers 6 tasks (3 independent, 3 with dependencies)
3. Detects teams enabled + 6 tasks → Parallel Mode
4. Creates team "build-REQ-789" FIRST, then creates 6 tasks with naming convention:
   - TASK 1: feat: implement endpoint handler
   - TASK 2: feat: add data models
   - TASK 3: test: add unit tests (blocked by 1,2)
   - etc.
5. Spawns 3 braingrid-builder teammates
6. Teammates self-claim wave-1 tasks, implement in parallel
7. As blockers complete, wave-2 tasks unlock and get claimed
8. Lead monitors progress, resolves any blockers
9. All tasks completed → lead shuts down teammates, deletes team
10. Acceptance criteria verification phase runs

Error Handling:

If the command fails, handle reactively based on the error:

• CLI not installed (command not found): Guide through installation, then retry
• Not authenticated: Guide through login flow, then retry
• No project: Guide through init process, then retry
• Requirement not found: Suggest listing requirements or creating with /specify
• No branch/ID: Ask for requirement ID or suggest creating branch
• API errors: Show error message and suggest retry

Success Criteria: ✅ BrainGrid CLI is installed and authenticated ✅ Requirement exists and build plan fetched successfully ✅ On feature branch with REQ-{id} pattern (auto-created if needed) ✅ Local Claude Code tasks created ✅ BrainGrid tasks created with external_id linking to Claude tasks ✅ Requirement status updated to IN_PROGRESS ✅ All tasks shown with full prompts ✅ Additional instructions acknowledged and applied (if provided) ✅ Implementation started on first task immediately ✅ All acceptance criteria verified with proof in temp file

If parallel mode used: ✅ Team created and teammates spawned successfully ✅ All teammates claimed and completed their tasks independently ✅ No merge conflicts from parallel file edits ✅ Final test suite passes after all parallel commits ✅ Teammates shut down cleanly, team deleted

Final Output:

After successful build fetch, show:

• ✅ Build plan fetched: REQ-{id}
• 📋 Name: {requirement name}
• 🔄 Status: IN_PROGRESS (updated)
• 🌿 Branch: {branch name} (created or existing)
• 📋 Tasks: {count} tasks ready for implementation
• 🔗 View requirement: https://app.braingrid.ai/requirements/overview?id={requirement-uuid}&tab=requirements
• 🔗 View tasks: https://app.braingrid.ai/requirements/overview?id={requirement-uuid}&tab=tasks
• 🔍 Verification: Acceptance criteria will be verified after all tasks complete

Note: Extract the requirement UUID from the command output to construct the URLs.

If additional instructions provided:

• 📝 Context: {additional instructions}
• Apply instructions as context to all task implementations

Automatic Implementation:

After displaying the final output summary, immediately begin implementing tasks:

1. Mark TASK 1 as in_progress and start working on it
2. Validate, commit, and complete each task (the PreToolUse hook handles commit enforcement)
3. Move to the next task immediately after completing each one
4. Continue until ALL tasks are completed
5. Only pause for genuine clarifying questions that block progress

Do NOT ask "Would you like me to start implementing the first task?" — just start.

Sync Task Statuses to BrainGrid (Fallback):

After ALL tasks are marked completed in Claude Code (and before acceptance criteria verification), run a bulk sync to catch any statuses the PostToolUse hook missed (network errors, teammate shutdown races, sentinel issues):

1. Fetch current BrainGrid task states:

   braingrid task list -r REQ-{id} --format json
   

2. For each BrainGrid task with an external_id:

   • Look up the matching Claude Code task (by ID from TaskList)

   • If the Claude Code task is completed but the BrainGrid task is NOT COMPLETED, sync it:

     braingrid task update TASK-X -r REQ-{id} --status COMPLETED
     

3. Report results:

   • If any tasks were synced: "🔄 Synced {n} task(s) to COMPLETED in BrainGrid"
   • If all tasks were already synced: "✅ All tasks already synced to BrainGrid"

This is a safety net — most statuses should already be synced by the PostToolUse hook. Check /tmp/braingrid-hook-debug.log if any were missed to diagnose root cause.

Acceptance Criteria Verification Phase:

After ALL tasks are marked completed, the Stop hook will prevent you from stopping until every acceptance criterion is verified. This ensures nothing slips through.

1. Read the criteria file: .braingrid/temp/REQ-{id}-acceptance-criteria.md
2. For each criterion starting with - []:
   • Verify the implementation satisfies it (examine code, run tests, check behavior)
   • Update the file: change - [] to - [x]
   • Add Proof: [explanation] on the next line immediately below the criterion
3. Continue until all criteria show [x] with proof
4. The Stop hook will block exit and re-inject the verification prompt until all criteria are verified

If the verification loop needs to be cancelled, the user can run /cancel-build-verification.

Post-Verification: Update Requirement in BrainGrid:

After ALL acceptance criteria show [x] with proof (verification loop complete):

1. Read the verified criteria file: Read .braingrid/temp/REQ-{id}-acceptance-criteria.md

2. Fetch current requirement content:

   braingrid requirement show REQ-{id} --format json
   

   Parse the JSON to get the current content field.

3. Replace the acceptance criteria section:

   • Find ## Acceptance Criteria in the current content
   • Replace everything from that heading to the next ## heading (or end of content) with the verified criteria file contents
   • If no ## Acceptance Criteria heading exists, append it at the end
   • Write the merged content to .braingrid/temp/REQ-{id}-updated-content.md

4. Update the requirement via CLI:

   braingrid requirement update REQ-{id} --content "$(cat .braingrid/temp/REQ-{id}-updated-content.md)"
   

5. Update requirement status to REVIEW:

   braingrid requirement update REQ-{id} --status REVIEW
   

6. Clean up temp files:

   rm -f .braingrid/temp/build-active.local .braingrid/temp/REQ-*.md
   

   Confirm: "🧹 Cleaned up build temp files"

7. Confirm: "✅ Requirement REQ-{id} updated with verified acceptance criteria and moved to REVIEW"

---

Available Output Formats:

While markdown is default and best for AI coding tools, the build command supports:

• markdown - Full content with task prompts (default, best for AI)
• json - Structured data for scripting
• xml - Alternative structured format
• table - Compact view for quick reference

If user wants a different format, they can specify it in additional instructions.