Scaffold

/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.

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

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

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:

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

Architecture Dimensions

L1 Auto-Resolve: Check each checkpoint against environment scan. Node installed → resolve "runtime" checkpoint. Docker available → partially resolve containerization.

Interview Loop (score-driven)

Same mechanics as specify's L2 but with architecture-specific question framing.

Each round:

1. Score — coverage per dimension
2. Target — lowest-scoring dimension(s)
3. Ask — 2 scenario questions targeting those checkpoints
4. Resolve — mark covered, merge decisions
5. Scan — detect cross-decision tensions
6. Display — scoreboard

Question format — RIGHT (concrete scenario):

AskUserQuestion(
  question: "Your API needs to serve both a React frontend and a future mobile app. How should client-server communication work?",
  options: [
    { label: "REST + OpenAPI + code-gen", description: "OpenAPI spec → Orval/openapi-typescript. Type-safe, well-tooled." },
    { label: "tRPC", description: "End-to-end type safety, no code-gen. TypeScript only." },
    { label: "GraphQL", description: "Flexible queries, schema-first. Higher complexity." },
    { label: "Agent decides", description: "Let scaffold choose based on project context" }
  ]
)

Question format — WRONG (abstract):

AskUserQuestion(question: "What API style do you prefer?", ...)

"Agent decides" handling: When user selects this, scaffold makes an opinionated choice based on:

1. L1 environment capabilities
2. Decisions already made (consistency)
3. Project complexity (simpler for simple projects)
4. Agent productivity criteria (prefer type-safe, convention-over-config)

Record as decision with assumed: true.

Agent Productivity Bias

When making or recommending decisions, bias toward the 4 quality criteria:

Conditional Extension Detection

During the interview, detect which conditional extensions to activate:

Record activated extensions as decisions:

D_EXT1: "Type Contracts extension activated — OpenAPI + Orval code-gen for client-server type safety"
D_EXT2: "Data Layer extension activated — PostgreSQL + Prisma migrations"

Termination

Composite score uses weighted average across dimensions (weights from the table above). Terminate when: composite >= 0.80, every dimension >= 0.60, unknowns == 0.

Inversion Probe

Two architecture-specific questions:

1. Inversion: "Given these architecture decisions, what scenario would cause a complete restructure even if every component works individually?"
2. Implication: "You chose [most impactful decision]. Does that also mean [architectural consequence]?"

If the probe reveals a critical issue (e.g., contradictory decisions, missing dimension coverage):

• Merge the issue as a known_gap via --append
• Re-enter the interview loop targeting the affected dimension(s)
• Continue until termination criteria are met again

L2 Approval

Present all decisions + constraints + activated extensions. Spawn L2-reviewer:

Task(subagent_type="general-purpose", prompt="""
You are an L2 architecture reviewer for a scaffold spec. Given:
- All architecture decisions
- Activated conditional extensions
- The 4 quality criteria (agent extensibility, testability, drift resistance, type safety)

Check:
1. Do decisions form a coherent stack? (no contradictions)
2. Are the 4 quality criteria addressed?
3. Any activated extension missing its supporting decisions?
4. Any decision that agents will struggle to follow consistently?

Return: PASS or NEEDS_FIX with specific issues.
""")

L2 Gate

Use Edit tool to write all decisions, constraints, and known gaps into the Decisions section of ${SPEC_DIR}/requirements.md.

L3: Harness Setup

Output: Harness decisions added to Decisions section in requirements.md

L3 determines the AI work environment for this project. While L2 decides how the code is structured, L3 decides how Claude will work with that code across sessions.

3-1. Domain Context (interactive)

AskUserQuestion(
  question: "Does this project have domain-specific terms or business rules? For example, 'tenant = company-level customer' or 'credit balance must never go negative'.",
  options: [
    { label: "Yes, I'll describe them", description: "You'll provide domain terms and key business rules" },
    { label: "None yet", description: "Skip — can add later to CLAUDE.md" },
    { label: "Agent decides", description: "Infer from project goal if possible" }
  ]
)

If user provides domain terms → record as decision: D_H1: "Domain context: [terms and rules]" These will be written into CLAUDE.md by the Guard Rails task (derived by /execute).

3-2. Team Context (interactive)

AskUserQuestion(
  question: "Are there team conventions for commits, PRs, branching, or code review?",
  options: [
    { label: "Conventional Commits + GitHub Flow", description: "feat/fix/chore prefixes, feature branches, squash merge" },
    { label: "Trunk-based development", description: "Short-lived branches, no long-running feature branches" },
    { label: "Custom — I'll describe", description: "You'll specify your team's rules" },
    { label: "Solo project, no conventions", description: "Skip team context" }
  ]
)

If user provides team conventions → record as decision: D_H2: "Team conventions: [rules]" These will be written into CLAUDE.md by the Guard Rails task (derived by /execute).

3-3. Constraints → Rules (auto + confirm)

Scan L2 constraints[] and propose converting them to .claude/rules/ files:

L2 produced these constraints:
  C1: "pnpm workspace — always use pnpm, never npm/yarn"
  C3: "Dependency direction: shared → client/server only"

These can become auto-enforced rules in .claude/rules/.

AskUserQuestion(
  question: "Convert these constraints to .claude/rules/ for automatic enforcement?",
  options: [
    { label: "Yes, all of them", description: "All constraints become rules files" },
    { label: "Let me pick", description: "Choose which constraints to enforce" },
    { label: "Skip", description: "Keep constraints in requirements.md only" }
  ]
)

Record as decision: D_H3: "Rules: [list of constraints to convert]"

3-4. Skills Detection (auto-suggest + ask)

Scan L2 decisions for recurring task patterns and suggest project-specific skills:

Present auto-suggestions, then ask:

AskUserQuestion(
  question: "These skills will be scaffolded based on your tech stack. Any other tasks you'll repeat frequently?",
  options: [
    { label: "These are enough", description: "Proceed with auto-suggested skills only" },
    { label: "Add more", description: "I'll describe additional recurring tasks" },
    { label: "Skip all skills", description: "Don't generate any project skills" }
  ]
)

Record as decision: D_H4: "Skills: [list of skills to generate]"

Each generated skill will have:

• SKILL.md with project-specific steps (using actual commands from L2 decisions)
• scripts/validate.sh when the task has a checkable outcome
• disable-model-invocation: true (all domain skills have side effects)