build

Feature Build Workflow

Before starting work, create a marker: mkdir -p ~/.claude/tmp && echo "build" > ~/.claude/tmp/heavy-skill-active && date -u +"%Y-%m-%dT%H:%M:%SZ" >> ~/.claude/tmp/heavy-skill-active

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.
4. Fetch docs — run /docs <library> for any external library. 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/NO-GO Verdict: After research, state one of:

• GO — requirements are clear, approach is viable, proceed to implementation.
• NO-GO — requirements are ambiguous, 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:

• Files to create/modify (with stack-correct paths — lib/hooks/ for satus, hooks/ for novus, etc.)
• Key decisions and rationale
• Dependency order

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.