joris887/exosuit

---

build

Build a project from a natural-language description. Orchestrates setup, planning, and implementation automatically.

All user-facing output MUST use plain English. No jargon: no "TDD", "sprint", "PR", "squash merge", "CI/CD", "ORM", "middleware". If a technical term is unavoidable, explain it in parentheses.

Arguments

$ARGUMENTS — a plain-English description of what to build (e.g., "a task management app with user accounts and due dates").

Phase 0: Check Setup

Read the current profile from CLAUDE.md. If not lean, note the profile but proceed — /build always uses lean-style execution internally regardless of project profile.

Phase 1: Decompose

Show: "Planning what needs to be built..."

Internally decompose the description into ordered stories using /ideate logic:

1. Identify the core entities and features described
2. Break into dependency-ordered implementation steps
3. Classify each as feature, infrastructure, or testing
4. Size each step (aim for steps that touch ≤5 files)

Do NOT surface any of this to the user. No story types, no SPIDR, no priority labels, no methodology terminology. Keep the decomposition internal.

Create a simple internal plan (not shown to user):

steps:
  - summary: "Set up the database tables"
    type: infrastructure
    files: [...]
  - summary: "Build the API endpoints"
    type: feature
    files: [...]
  - summary: "Add user authentication"
    type: feature
    files: [...]
  - summary: "Write tests"
    type: testing
    files: [...]

Discovery Capture (Retroactive)

Silently capture discovery context for future phase reviews — the user does NOT see this:

1. Infer archetype from description (classify against the 10 archetypes in .claude/skills/discover/references/scale-guide.md)
2. Set scale to Quick Build
3. Auto-generate a minimal docs/reference/DECISION_LOG.md (copy template from .claude/skills/discover/assets/decision-log.md), logging all technical decisions with confidence: ASSUMED
4. Include Phase Transition Stories (E0N-REVIEW: 3-story quick variant — E0N-001, E0N-004, E0N-006) as the last internal step
5. Save classification to vision/classification.md

This ensures /build users get the review cycle without upfront friction.

Phase 2: Execute

For each step in dependency order:

1. Show progress in plain English:

   • "Setting up the database..." / "Building the API..." / "Adding user login..." / "Writing tests to make sure everything works..."
   • Use language the user would understand. Never: "Executing story E01-003 (type: feature, size: STANDARD)"

2. Execute using story-cycle Lean behavior:

   • Plan (lightweight — no confidence scoring)
   • Build with TDD where non-trivial (run tests, don't explain TDD methodology)
   • Verify tests pass
   • Commit with conventional format (don't explain commit conventions)

3. Make all technical decisions silently:

   • Framework/library choices: pick the best fit, document in a final summary
   • Architecture: follow standard patterns for the detected stack
   • File structure: follow existing project conventions or detected stack defaults
   • Only stop for genuine product ambiguity: "The design could go two ways: [A] or [B]. Which do you prefer?"
   • Never stop for: database choice, API style, file naming, test framework, folder structure

4. Handle failures gracefully:

   • If a step fails after 2 attempts, skip it with a note: "I couldn't get [X] working automatically. Here's what needs to be done manually: [description]"
   • Continue with remaining steps — don't block the entire build

Phase 3: Complete

3A. Launch & Verify (if applicable)

Check CLAUDE.md Commands for a dev: command. If one is configured:

1. Show: "Starting your project..."
2. Run the dev command in background using Bash with run_in_background: true
3. Wait a few seconds. Read any output — look for URLs, ports, file paths, or status messages.
4. Show whatever the command produces. If it outputs a URL, highlight it. If it's a CLI, show the help output. If it starts a server, show the address.
5. Ask: "Take a look and tell me what you think!"
6. Wait for feedback. Positive → proceed to completion report. Issues → fix and re-run.

If no dev command is configured (libraries, packages, pipelines, etc.) → skip this step. Tests already verified the build.

Do NOT assume localhost or any specific URL. Read the actual command output. Different projects produce different results.

3B. Completion Report

Show a completion report in plain English:

## All Done!

### What Was Built
- [Feature 1]: [plain-English description of what it does]
- [Feature 2]: [description]
- ...

### Files Created/Modified
- `src/models/user.ts` — User data model
- `src/api/auth.ts` — Login and registration endpoints
- ...

### Tests
- [N] tests written, all passing

### Technical Decisions Made
- **Database:** PostgreSQL (reliable, free, works well with [framework])
- **Auth:** [chosen approach] — [one-line reason]
- ...

### Try It
[If dev command ran: "Your project is running — see above"]
[If dev command exists but didn't launch: "Run `[dev command]` to start"]
[If no dev command: omit this section]

### Next Steps
- [Suggestion 1, e.g., "Add a payment system with /build 'Stripe payment integration'"]
- [Suggestion 2]

Rules

• Plain English only — every user-facing message must be understandable by someone who has never coded
• Silent technical decisions — pick good defaults, document them in the completion report, never ask
• Stop only for product questions — "Should users be able to delete their account?" is valid. "REST or GraphQL?" is not.
• Safety hooks still run — secrets detection, git protection, and test execution happen invisibly
• Lean execution — no quality agent dispatch, no sprint specs, no retrospectives, no documentation generation beyond what's needed to work
• Skip gracefully — failed steps are noted, not fatal. The build continues.
• One session — the first version of /build completes in a single session. Multi-session builds are future work.