From hoyeon
Scaffolds greenfield project architecture, test infrastructure, guard rails, and AI agent harness via interview-driven layers to requirements.md. Use for /scaffold, new projects, or setup.
npx claudepluginhub team-attention/hoyeon --plugin hoyeonThis skill is limited to using the following tools:
Generate a scaffold requirements.md through an architecture-focused derivation chain.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Generate a scaffold requirements.md through an architecture-focused derivation chain. Produces a complete development foundation that AI agents can extend consistently.
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 |
hoyeon-cli req init to create the spec directory and stub requirements.md. Then Write/Edit requirements.md directly.spec validate or spec guide commands.| 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.
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"
Output: Goal, Non-Goals, Confirmed Goal sections in requirements.md
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."
Use the Edit tool to write the Goal, Non-Goals, and Confirmed Goal sections into ${SPEC_DIR}/requirements.md.
User confirms mirror → advance to L1.
Output: Research section in requirements.md
Unlike specify's L1 (which scans existing code), scaffold's L1 scans the environment:
| 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 |
Use the Edit tool to add a Research/Context section to ${SPEC_DIR}/requirements.md with the environment scan findings.
Auto-advance to L2 (no user approval needed).
Output: Decisions, Constraints, Known Gaps sections in requirements.md
This is scaffold's core. The interview determines the entire project architecture.
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 |
| # | Dimension | Weight | Example Checkpoints |
|---|---|---|---|
| 1 | Tech Stack | 25% | Language/runtime, framework, package manager |
| 2 | Communication | 20% | Client-server protocol, API style, type safety strategy |
| 3 | Data & State | 20% | Database choice, ORM/query builder, migration strategy, caching |
| 4 | Testing | 15% | Test framework, test patterns, coverage strategy |
| 5 | DevOps & Environment | 20% | Containerization, CI/CD, env config, deployment target |
L1 Auto-Resolve: Check each checkpoint against environment scan. Node installed → resolve "runtime" checkpoint. Docker available → partially resolve containerization.
Same mechanics as specify's L2 but with architecture-specific question framing.
Each round:
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:
Record as decision with assumed: true.
When making or recommending decisions, bias toward the 4 quality criteria:
| Criteria | Bias |
|---|---|
| Agent extensibility | Prefer convention-over-config, clear naming, predictable patterns |
| Testability | Prefer dependency injection, pure functions, mockable boundaries |
| Drift resistance | Prefer strict linting, type checking, boundary enforcement |
| Type-safe communication | Prefer code-gen over manual types, schema-first over code-first |
During the interview, detect which conditional extensions to activate:
| Signal from Interview | Extension Activated |
|---|---|
| Client-server boundary detected | Type Contracts (OpenAPI/tRPC/GraphQL schema) |
| Database mentioned or implied | Data Layer (migrations, connection, seed) |
| Docker available + multi-service | Docker/Infra (compose, Dockerfile) |
| Long-running server process | Runtime Patterns (health check, graceful shutdown) |
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"
Composite score uses weighted average across dimensions (weights from the table above). Terminate when: composite >= 0.80, every dimension >= 0.60, unknowns == 0.
Two architecture-specific questions:
If the probe reveals a critical issue (e.g., contradictory decisions, missing dimension coverage):
known_gap via --appendPresent 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.
""")
Use Edit tool to write all decisions, constraints, and known gaps into the Decisions section of ${SPEC_DIR}/requirements.md.
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.
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).
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).
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]"
Scan L2 decisions for recurring task patterns and suggest project-specific skills:
| L2 Decision Signal | Auto-Suggested Skill | Description |
|---|---|---|
| DB + ORM (Prisma, Drizzle, SQLAlchemy) | /migrate | Run migration + regenerate types |
| DB detected | /seed-data | Generate development seed data |
| Docker / docker-compose | /deploy | Build, push, run with health check |
| API server (REST, GraphQL, tRPC) | /api-test | Test endpoint with curl/httpie |
| Async workers (Celery, BullMQ) | /worker-test | Dispatch test task + verify result |
| CLI binary (Rust, Go) | /release | Version bump + build + tag + publish |
| Frontend framework | /new-component | Scaffold component + test + story |
| Payment integration (Stripe, etc.) | /test-webhook | Forward + trigger webhook locally |
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 outcomedisable-model-invocation: true (all domain skills have side effects)Auto-detect hooks from L2 tech stack decisions:
| L2 Decision | Auto-Detected Hook | Type |
|---|---|---|
| TypeScript (tsconfig.json) | tsc --noEmit on Edit/Write to .ts | PostToolUse |
| Prettier configured | prettier --write on Edit/Write | PostToolUse |
| ESLint configured | eslint --fix on Edit/Write | PostToolUse |
| Ruff / Black (Python) | ruff format on Edit/Write | PostToolUse |
| rustfmt (Rust) | rustfmt on Edit/Write | PostToolUse |
| gofmt (Go) | gofmt -w on Edit/Write | PostToolUse |
| .env files will exist | Block Edit/Write to .env* | PreToolUse |
| Lock files will exist | Block Edit/Write to lock files | PreToolUse |
Present the hook list:
AskUserQuestion(
question: "These hooks will be added to .claude/settings.json for automatic enforcement. Approve?",
options: [
{ label: "Approve all", description: "Add all detected hooks" },
{ label: "Let me pick", description: "Choose which hooks to enable" },
{ label: "Skip hooks", description: "Don't set up any hooks" }
]
)
Record as decision: D_H5: "Hooks: [list of hooks to configure]"
Use Edit tool to append all harness decisions to the Decisions section in ${SPEC_DIR}/requirements.md:
Only include D_H1/D_H2 if user provided content. Omit if "None yet" or "Solo project".
Present harness summary → AskUserQuestion (Approve/Revise/Abort).
Output: Requirements section (with GWT sub-requirements) written to requirements.md
L4 does NOT produce tasks. Task breakdown is the job of /execute (via /blueprint or inline planning), which writes a sibling plan.json. L4's job is to finalize the what (requirements + harness intent) so /execute has a complete requirements.md to derive tasks from.
Requirements come from both L2 (architecture) and L3 (harness). Every sub-requirement MUST have given / when / then (GWT is mandatory).
Construct requirements from L2 decisions + L3 harness decisions, then write them into the Requirements section of ${SPEC_DIR}/requirements.md using the Edit tool.
Every sub-requirement must include given, when, then — behavior alone is not enough.
Code Requirements (from L2):
R1: "Code Structure — Project directories, base configs, and a complete vertical slice exemplar"
R1.1: "Directory structure follows [framework] conventions with clear layer separation"
R1.2: "Vertical slice exemplar implements one complete flow (route → service → data → test) with importable utilities (logger, config, errors)"
R1.3: "All exemplar utilities are importable modules, not inline code"
R2: "Test Infrastructure — Framework setup with patterns matching the exemplar"
R2.1: "[Test framework] configured with [runner] and example test matching exemplar flow"
R2.2: "Test directory structure mirrors source structure"
R3: "Guard Rails — CLAUDE.md + enforcement mechanisms for drift resistance"
R3.1: "CLAUDE.md with architectural rules, domain context, team conventions, dependency direction, file placement conventions, available project skills summary, and active hooks summary"
R3.2: "Linter + formatter configured with project-specific rules"
R3.3: "CI pipeline running lint + typecheck + test"
R3.4: ".env.example with all required environment variables documented"
Conditional Code Extensions (from L2):
R4: "Type Contracts — Schema-driven type safety across client-server boundary" (if D_EXT1)
R4.1: "API schema or router defines all endpoints with typed request/response"
R4.2: "Client-side type bindings generated or inferred from the schema (no manual type duplication)"
R5: "Data Layer — Database connection, schema management, and seed data" (if D_EXT2)
R5.1: "ORM/query builder configured with typed models matching the domain"
R5.2: "Initial migration generated and seed script produces development data"
R5.3: "Database connection uses environment variable (DATABASE_URL or equivalent)"
R6: "Docker/Infra — Containerized local development environment" (if D_EXT3)
R6.1: "docker-compose.yml with required services (DB, cache, etc.) and persistent volumes"
R6.2: "README or CLAUDE.md documents how to start/stop the local environment"
R7: "Runtime Patterns — Production-readiness baseline for long-running server" (if D_EXT4)
R7.1: "Health check endpoint returns server status and dependency connectivity"
R7.2: "Graceful shutdown handler closes DB connections and in-flight requests"
Harness Requirements (from L3):
R8: "Project Rules — Constraints converted to .claude/rules/ for automatic enforcement" (if D_H3)
R8.1: "Each selected constraint has a corresponding .claude/rules/{name}.md file"
R8.2: "Rule files contain clear, actionable directives (not vague guidelines)"
R9: "Domain Skills — Project-specific repeatable task recipes" (if D_H4)
R9.1: "Each skill has SKILL.md with project-specific commands (not generic placeholders)"
R9.2: "Skills with checkable outcomes include scripts/validate.sh"
R10: "Project Hooks — Automated code quality enforcement" (if D_H5)
R10.1: ".claude/settings.json with PostToolUse hooks for detected formatter/linter"
R10.2: "PreToolUse protection hooks for .env and lock files (if applicable)"
Behavior Quality: Same rules as specify — trigger + observable outcome.
Note on fulfills[]: Use parent requirement IDs only (R1, R2, R3), NOT sub-requirement IDs (R1.1, R3.4).
Task derivation is handled by /execute (via /blueprint or inline planning). /execute reads requirements.md and writes plan.json next to it.
Ensure the requirements written in Step 1 carry enough harness detail that /execute can derive the right tasks:
/execute/execute will read requirements.md and derive plan.json tasks. The scaffold-specific shape it is expected to produce (documented here so reviewers know what "good" looks like):
T1 Project initialization → fulfills R1T2 Guard Rails + CLAUDE.md + rules → fulfills R3 (+ R8 when present), depends on T1T4 Test infrastructure → fulfills R2, depends on T1T3 Vertical slice exemplar (highest-value task) → fulfills R1, depends on T2, T4Keep this as guidance; the actual task records are /execute's responsibility.
The exemplar is the scaffold's highest-value output. Its GWT sub-requirement must demand:
lib/logger.ts, lib/config.ts, lib/errors.ts (not inline)The exemplar answers: "If an agent reads only this one feature, can it build the next feature correctly?"
Each generated skill must reference actual tools/commands from L2 decisions:
disable-model-invocation: true for all domain skills (they have side effects)scripts/validate.sh when the task has a checkable outcomerequirements.md ready! .hoyeon/specs/{name}/requirements.md
Goal
----------------------------------------
{confirmed_goal}
Architecture Decisions ({n} total)
----------------------------------------
D1: {tech stack decision}
D2: {communication decision}
...
Activated Extensions
----------------------------------------
[x] Type Contracts (OpenAPI + Orval)
[x] Data Layer (PostgreSQL + Prisma)
[ ] Docker/Infra (not needed)
[ ] Runtime Patterns (not needed)
Harness
----------------------------------------
CLAUDE.md: architecture + domain context + team conventions
Rules: {n} constraints → .claude/rules/
Skills: {list of skills}
Hooks: {list of hooks}
Task Derivation
----------------------------------------
(none in requirements.md — /execute will derive tasks into plan.json
next to requirements.md: project init, guard rails + rules, test infra, vertical slice exemplar,
conditional extensions, domain skills, project hooks, and a final scaffold verification.)
Quality Criteria
----------------------------------------
- Agent extensibility: vertical slice exemplar (T3)
- Testability: test infrastructure + exemplar tests (T4)
- Drift resistance: CLAUDE.md + rules + lint + CI (T2)
- Type safety: [type contract strategy from D_]
- Cross-session continuity: CLAUDE.md with domain/team context (T2)
- Task automation: domain skills (T_SKILL)
- Code quality enforcement: project hooks (T_HOOK)
AskUserQuestion(
question: "Review the scaffold plan above.",
options: [
{ label: "/execute", description: "Start scaffolding" },
{ label: "Revise architecture (L2)", description: "Change architecture decisions" },
{ label: "Revise harness (L3)", description: "Change harness setup" },
{ label: "Revise plan (L4)", description: "Adjust requirements or harness decisions" },
{ label: "Abort", description: "Stop" }
]
)
On approval, run /execute.
Three approval gates (L2, L3, L4). L2: architecture, L3: harness, L4: unified plan. Same pattern as specify:
AskUserQuestion(
question: "Review the {items} above. Ready to proceed?",
options: [
{ label: "Approve", description: "Looks good — proceed to next layer" },
{ label: "Revise", description: "I want to change something" },
{ label: "Abort", description: "Stop specification" }
]
)
.hoyeon/specs/{name}/requirements.mdgiven, when, then (mandatory)