Build

---
name: build
description: Build a feature, page, or integration end-to-end with a GO/NO-GO gate. Triggers "build a feature", "implement feature", "add feature", "build integration". Components go to /component, hooks to /hook.
context: fork
---

# Feature Build Workflow

## Standalone Codex

Use Context7 only when the user configured that
MCP. Otherwise consult official library documentation through native browsing
or inspect the pinned local package, and state which fallback supplied the API
contract. This package does not auto-run unpinned registry MCP packages.

## Phase 1: Research (GO/NO-GO Gate)

Before any implementation, complete this research phase:

1. **Detect stack** — read `package.json`. `next` dep → satus / Next.js; `react-router` dep → novus / React Router. Note any starter signal (`name` field, `darkroom.starter` marker).
2. **Understand requirements** — parse what the user actually needs.
3. **Explore codebase** — find existing patterns, similar implementations. Fetch the team-knowledge index and read any note whose title matches the libraries and integrations this feature touches; the fetch command is in docs/knowledge-system.md (fail-open — skip if `gh` is unavailable).
4. **Fetch docs** — use Context7 in Claude or when configured in Codex; otherwise use the standalone fallback above. Never code from memory.
5. **Check versions** — run `bun info <package>` for the latest version.
6. **Assess feasibility** — can this be done cleanly within existing architecture?

**GO/ASK/NO-GO Verdict**: After research, state one of:
- **GO** — requirements are clear, approach is viable, proceed to implementation.
- **ASK** — requirements have more than one plausible reading. Run clarifying rounds (AskUserQuestion in Claude, Plan mode `request_user_input` in Codex; up to 4 questions each, recommendation first) until no fork is left, then re-issue the verdict.
- **NO-GO** — approach has blockers or scope is too large. Report findings and stop.

Do not proceed past this gate without an explicit GO verdict.

## Phase 2: Plan

Create a brief implementation plan, opening with a `## Functional DAG` (recipe-table brace
diagram — inputs left, operations merging rightward, one terminal verification node; spec:
`docs/functional-dag.md`), then:
- Files to create/modify (with stack-correct paths — `lib/hooks/` for satus, `hooks/` for novus, etc.)
- Key decisions and rationale
- Dependency order — read off the DAG's columns, not restated by hand

## Phase 3: Implement

Follow standard Maestro workflow: scaffold → implement → test → review.

Use the right primitives for the stack:

| Concern | satus (Next.js) | novus (React Router) |
|---|---|---|
| Page | `app/<path>/page.tsx` | `app/routes/<path>.tsx` |
| Layout | `app/<path>/layout.tsx` | `app/root.tsx` or nested route |
| Data fetching | Server Component `async function` | `loader()` route export |
| Mutations | Server Actions (`'use server'`) | `action()` route export |
| Routing | File-based `app/` | File-based `app/routes/` |
| Image | `next/image` | `<img>` (or Vite plugin) |
| Link | `@/components/link` (project wrapper) | `react-router` `Link` |

## Output

Return a concise summary:
- **Stack detected**: satus / novus / other (with evidence — e.g. `next ^16.0.0`)
- **What was built**: feature description
- **Files created**: list of new files
- **Files modified**: list of changed files
- **How to use**: quick usage guide
- **Tests added**: what's covered

## Rationalization Counters

If you catch yourself thinking any of the following, STOP — you are skipping the research gate:

| Rationalization | Why It's Wrong |
|---|---|
| "I already know how to do this" | The codebase may have existing patterns, wrappers, or conventions you'd miss |
| "The requirements are obvious" | Obvious requirements have hidden edge cases; the GO/NO-GO gate catches them |
| "Research would take too long" | Building the wrong thing takes longer than 5 minutes of research |
| "I'll figure it out as I go" | This leads to mid-implementation pivots that waste context and leave dead code |
| "It's just a small feature" | Small features in the wrong place create architectural debt |
| "The user seems impatient" | Shipping broken code is worse than a brief research pause |
| "Both starters are similar enough" | They diverge on routing, data fetching, mutations, and asset handling. The wrong shape compiles but doesn't fit |

## Remember

- Detect stack before scaffolding — wrong shape = rewrite later.
- Use the starter's conventions (CSS modules as `s`, path alias `@/` for satus / `~/` for novus).
- Server-side data fetching where the framework supports it (RSC for satus, loaders for novus).
- Store useful patterns as learnings.