/build

You are executing a Fantasia build operation. Your job is to orchestrate specialist agents to implement an approved plan.

Determine Fantasia Directory

All Fantasia outputs go to ~/.claude/fantasia/<project>/ by default, but this can be overridden with the FANTASIA_DIR environment variable.

# Use environment variable if set, otherwise calculate default
if [ -z "$FANTASIA_DIR" ]; then
  REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
  PROJECT_SLUG=$(basename "$REPO_ROOT" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
  FANTASIA_DIR="$HOME/.claude/fantasia/$PROJECT_SLUG"
fi

echo "FANTASIA_DIR=$FANTASIA_DIR"

Determine Which Plan

1. Check if $ARGUMENTS contains --task:

   • If yes, extract the task name and look for $FANTASIA_DIR/plans/<task-name>/PLAN.md
   • If no, find the most recent plan:

     ls -t $FANTASIA_DIR/plans/*/PLAN.md 2>/dev/null | head -1
     

2. If no plan found, offer to run prerequisites: "No plan found. Would you like me to help you create one? Run /fantasia:plan "

Prerequisites Check

1. Verify $FANTASIA_DIR/codebase/ exists (maps are required)

   • If missing: "Codebase maps not found. Would you like me to run /fantasia:map first?"

2. Verify plan file exists and read it

3. Confirm with user: "Ready to build:

   This will execute the plan in $FANTASIA_DIR/plans/<task>/PLAN.md

   Proceed? (y/n)"

Pre-Build Validation (Anti-Hallucination)

CRITICAL: Validate the plan before spawning any agents.

File Path Validation

Before proceeding, verify ALL file paths in the plan exist:

# Extract file paths from PLAN.md and verify they exist or their parent directories exist
grep -oE '\b(src|lib|app|packages)/[a-zA-Z0-9/_.-]+\.(ts|js|py|go|rs)' $FANTASIA_DIR/plans/<task>/PLAN.md | while read path; do
  dir=$(dirname "$path")
  if [ ! -d "$dir" ]; then
    echo "⚠️ INVALID PATH: $path (directory $dir does not exist)"
  fi
done

If ANY paths are invalid, STOP and report:

⚠️ PRE-BUILD VALIDATION FAILED

Invalid file paths in plan:
- <path> → directory does not exist

Options:
1. Fix the plan with correct paths
2. Create the missing directories first
3. Abort build

Map Freshness Check

# Check map age
MAP_DATE=$(stat -f %m $FANTASIA_DIR/codebase/ARCHITECTURE.md 2>/dev/null || stat -c %Y $FANTASIA_DIR/codebase/ARCHITECTURE.md 2>/dev/null)
NOW=$(date +%s)
AGE_DAYS=$(( (NOW - MAP_DATE) / 86400 ))

if [ $AGE_DAYS -gt 7 ]; then
  echo "⚠️ Maps are $AGE_DAYS days old"
fi

If maps are >7 days old, warn:

⚠️ STALE MAPS WARNING

Codebase maps are $AGE_DAYS days old. The codebase may have changed.

Options:
1. Continue anyway (risk of outdated patterns)
2. Run /fantasia:map --force first (recommended)

Scope Definition

Before spawning agents, extract and communicate clear scope boundaries:

Scope for this build:
- Files to CREATE: [list from plan]
- Files to MODIFY: [list from plan]
- Files OUT OF SCOPE: everything else

Agents will be instructed to STOP if they need to touch files outside this scope.

Load Configuration

Check for project-specific configuration:

CONFIG_FILE="$FANTASIA_DIR/fantasia-config.md"
[ -f "$CONFIG_FILE" ] && echo "CONFIG_EXISTS=true"

If config exists, extract model overrides for builder agents:

• architect: default opus
• implementer: default sonnet
• integrator: default sonnet

Also check for default-model and any project notes to include as context.

Load Organization Context

Check for organization-wide context:

ORG_CONTEXT_FILE="$HOME/.claude/fantasia/org-context.md"
if [ -f "$ORG_CONTEXT_FILE" ]; then
  echo "ORG_CONTEXT_EXISTS=true"
fi

If org context exists:

1. Read and parse the YAML frontmatter
2. Match repository patterns against current repo (using detection markers)
3. Extract matched pattern's:
   • commands (test/lint/typecheck/format) for verification
   • precommit configuration
   • environment requirements
   • coding_standards for code quality

Build an ORG_CONTEXT_BLOCK to inject into agent prompts:

ORGANIZATION CONTEXT:
- Build system: <build_system>
- Required commands: test, lint, typecheck, format
- Pre-commit: <enabled/disabled>
- Environment: <activation command if any>
- Coding standards: <list>

Ensure code follows these standards and will pass required checks.

Read Context

Read these files to provide context to agents:

• The PLAN.md file (required)
• Relevant codebase maps based on what the plan touches:
  • CONVENTIONS.md (always - for coding standards)
  • ARCHITECTURE.md (if creating new components)
  • STACK.md (if using specific technologies)
• Project notes from $FANTASIA_DIR/fantasia-config.md (if any)

TOKEN EFFICIENCY: Extract and pass only relevant sections to agents. Do NOT pass entire map files - extract the 10-20 most relevant lines for each agent's task.

Execute Plan

Execution Strategy

Based on the plan's "Execution Order" section, spawn agents appropriately:

• Sequential phases: Wait for one to complete before starting next
• Parallel phases: Spawn multiple agents simultaneously

Agent Spawning

For each phase in the plan, spawn the appropriate agent using the Task tool.

MODEL SELECTION: When spawning each agent, set the model parameter based on:

1. Config-specified model for this agent (if set in $FANTASIA_DIR/fantasia-config.md)
2. Config default-model (if set)
3. Built-in defaults:
   • architect: opus
   • implementer: sonnet
   • integrator: sonnet

CRITICAL FOR TOKEN EFFICIENCY:

• Pass only the relevant portion of the plan to each agent
• Pass only the relevant codebase map sections
• Agents write code directly to files
• Agents return ONLY a brief confirmation of what was done

Architect Agent Prompt Template

You are the architect for this task. Your job is to make design decisions and create contracts/interfaces.

## Task Context
<Paste relevant plan section>

## Codebase Patterns to Follow
<Paste relevant sections from CONVENTIONS.md and ARCHITECTURE.md>

## Your Deliverables
<List from plan>

## Instructions
1. Create the specified interfaces/contracts
2. Write directly to the files specified
3. Follow existing patterns exactly
4. Add comments explaining design decisions

When done, respond with ONLY: "✓ Architect done"

Implementer Agent Prompt Template

You are the implementer for this task. Your job is to write the core logic.

## Task Context
<Paste relevant plan section>

## Codebase Patterns to Follow
<Paste relevant sections from CONVENTIONS.md>

## Contracts/Interfaces to Implement
<If architect created contracts, reference them>

## Your Deliverables
<List from plan>

## Instructions
1. Implement the specified functionality
2. Write directly to the files specified
3. Follow existing patterns exactly
4. Match the code style of surrounding code
5. Add appropriate error handling
6. Include inline comments only where logic is complex

When done, respond with ONLY: "✓ Implementer done"

Integrator Agent Prompt Template

You are the integrator for this task. Your job is to connect components and handle boundaries.

## Task Context
<Paste relevant plan section>

## Codebase Patterns to Follow
<Paste relevant sections from CONVENTIONS.md and INTEGRATIONS.md>

## Components to Integrate
<Reference what architect/implementer created>

## Your Deliverables
<List from plan>

## Instructions
1. Wire up the components as specified
2. Handle API boundaries and data transformation
3. Add appropriate validation at boundaries
4. Write directly to the files specified
5. Follow existing integration patterns

When done, respond with ONLY: "✓ Integrator done"

Progress Tracking

After each agent completes, update the user:

Phase 1/3 complete: Architect ✓
Starting Phase 2: Implementer...

Completion

After all phases complete, use git to summarize changes:

# Get files changed during build
git status --porcelain | wc -l  # Count
git status --porcelain  # List files

✅ Build complete: <task-name>

## Summary
- Files created: X (from git status - new files)
- Files modified: Y (from git status - modified files)

## Changes Made
<List from git status, NOT from agent responses>

## Next Steps
Ready for review? Run /fantasia:review

Or if you want to test manually first, the changes are ready in your working directory.

Error Handling

If an agent encounters an error:

1. Report the error clearly
2. Ask user how to proceed:
   • Retry the phase
   • Skip and continue
   • Abort the build
3. Do NOT automatically retry without user input

Save Checkpoint

After build completes (or after each phase for long builds), save state:

TASK_SLUG="<the-task-slug>"

# Preserve mode from previous state if it exists (handles Mode: and **Mode**:)
CURRENT_MODE=$(sed -n -E 's/^[[:space:]]*([*][*])?Mode([*][*])?:[[:space:]]*//p' $FANTASIA_DIR/fantasia-state.md 2>/dev/null | head -1)
if [ -z "$CURRENT_MODE" ]; then
  CURRENT_MODE="interactive"
fi

cat > $FANTASIA_DIR/fantasia-state.md << EOF
# Fantasia Checkpoint

**Saved**: $(date -Iseconds)
**Phase**: idle
**Last Action**: build complete
**Plan**: $TASK_SLUG
**Mode**: $CURRENT_MODE

## Context
- Maps: available in $FANTASIA_DIR/codebase/
- Plan: $FANTASIA_DIR/plans/$TASK_SLUG/PLAN.md
- Build: complete
- Review: not started

## Changes Made
<Summary of files created/modified>

## Next Step
Run \`/fantasia:review\` to review the changes.

## To Resume
Run \`/fantasia:resume\` to restore context and continue.
EOF

Mid-Build Checkpoints

For long builds, also save checkpoint after each agent phase completes:

• Update Phase to building
• Note which phases are complete
• This allows resuming if the session is interrupted