/scaffold

name: scaffold
description: |
  Greenfield project architecture + harness scaffolding for AI Agent productivity.
  Interview-driven decisions → requirements.md → execute.
  Produces: Code Structure (vertical slice exemplar), Test Infrastructure, Guard Rails,
  conditional extensions, AND Harness (CLAUDE.md with domain/team context, rules, skills, hooks).
  L2: architecture decisions, L3: harness setup, L4: requirements + harness decisions (tasks generated later by /execute into plan.json).
  Use when: "/scaffold", "scaffold", "new project", "set up project", "프로젝트 세팅", "초기 구조"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Task
  - Bash
  - Write
  - AskUserQuestion

/scaffold — Greenfield Architecture Scaffolding

Generate a scaffold requirements.md through an architecture-focused derivation chain. Produces a complete development foundation that AI agents can extend consistently.

---

Core Identity

scaffold is specify's **architecture variant**. Same requirements.md format, different weight center.

| | specify | scaffold | |---|---------|----------| | Focus | What to build (features) | How to structure (architecture + harness) | | L2 weight | Moderate (feature decisions) | **Heavy** (tech stack, patterns, infra) | | L3 | Requirements (behavioral) | **Harness** (domain, team, skills, hooks, rules) | | L4 | Verification journeys | **Requirements + Harness Decisions** (no tasks — /execute writes plan.json) | | Tasks | Feature implementation | Project initialization + exemplar + harness | | Output | Code changes | Complete development environment + AI harness | | When | Feature on existing codebase | Greenfield or major restructure |

---

Core Rules

1. **CLI creates the spec dir** — `hoyeon-cli req init` to create the spec directory and stub requirements.md. Then Write/Edit requirements.md directly. 2. **Direct markdown editing** — Write requirements.md content using Write or Edit tools. No JSON merge protocol needed. 3. **No schema validation** — requirements.md is freeform markdown. No `spec validate` or `spec guide` commands. 4. **Revision Protocol** — When user selects "Revise" at an approval gate:

• Use Edit tool to modify, add, or remove sections in requirements.md directly.
• No merge flags needed — just edit the markdown.

---

Layer Flow

| Layer | What | Gate | |-------|------|------| | L0 | Mirror → confirmed_goal, non_goals | User confirms mirror | | L1 | Environment scan (greenfield detection) | Auto-advance | | L2 | **Architecture interview** → decisions + constraints (HEAVY) | User approval | | L3 | **Harness setup** → domain, team, rules, skills, hooks | User approval | | L4 | **Requirements + Harness Decisions** → requirements (with GWT sub-reqs) + harness decisions | User approval |

scaffold produces requirements.md only (no tasks). Task breakdown is handled later by `/execute` (via `/blueprint` or inline planning), which writes a sibling `plan.json` next to requirements.md.

Session Init (before L0)

SPEC_DIR=".hoyeon/specs/{name}"
hoyeon-cli req init $SPEC_DIR --type greenfield --goal "{goal}"

This creates `${SPEC_DIR}/requirements.md` with a stub template.

SESSION_ID="[from UserPromptSubmit hook]"
hoyeon-cli session set --sid $SESSION_ID --key spec_dir --value "$SPEC_DIR"

---

L0: Goal

**Output**: Goal, Non-Goals, Confirmed Goal sections in requirements.md

Mirror Protocol

Mirror the user's goal with scaffold-specific framing:

"I understand you want to build [product/system].
 Architecture scope: [what the scaffold will set up].
 NOT in scaffold scope: [features, business logic — those come later via /specify].
 Done when: [agent can extend the codebase consistently].
 Does this match?"

**Key distinction**: scaffold's goal is the **foundation**, not the product. If user says "I want to build a todo app", the scaffold goal is "Set up a web application foundation (server + client + DB) that an agent can extend to build features like a todo app."

Write to requirements.md

Use the Edit tool to write the Goal, Non-Goals, and Confirmed Goal sections into `${SPEC_DIR}/requirements.md`.

Gate

User confirms mirror → advance to L1.

---

L1: Environment Scan

**Output**: Research section in requirements.md

Unlike specify's L1 (which scans existing code), scaffold's L1 scans the **environment**:

Scan Targets

| Target | How | Why | |--------|-----|-----| | Working directory | `ls -la`, check for existing files | Greenfield confirmation | | Package managers | `which npm`, `which yarn`, `which pnpm`, `which bun` | Available tooling | | Runtime versions | `node -v`, `python3 --version`, `go version`, etc. | Compatibility constraints | | Docker | `docker --version`, `docker compose version` | Infra capability | | Git | `git status` | Repo state | | OS/platform | `uname -a` | Platform constraints |

Write to requirements.md

Use the Edit tool to add a Research/Context section to `${SPEC_DIR}/requirements.md` with the environment scan findings.

Gate

Auto-advance to L2 (no user approval needed).

---

L2: Architecture Decisions (HEAVY)

**Output**: Decisions, Constraints, Known Gaps sections in requirements.md

This is scaffold's core. The interview determines the entire project architecture.

Step 0: Checkpoint Generation

Read L1 environment scan + confirmed_goal, then generate checkpoints per **architecture dimension**.

**Complexity classification** — based on confirmed goal:

| Signal | Examples | |--------|----------| | Client-server boundary | web app, mobile + API, microservices | | Multiple data stores | DB + cache + queue | | Real-time communication | WebSocket, SSE, polling | | External service integration | payment, auth provider, AI API | | Multi-environment deployment | dev/staging/prod, Docker | | Background processing | workers, cron, queues |

• **Simple** (0-1 signals) → 2-3 per dimension
• **Medium** (2-3 signals) → 4-5 per dimension
• **Complex** (4+ sig