scaffold

scaffold

Purpose

The "zero to production-ready" orchestrator. Takes a project description and autonomously generates a complete, working project — directory structure, code, tests, documentation, git setup, and verification. Orchestrates 8+ skills in sequence to produce output that builds, passes tests, and is ready for development.

Generated projects MUST build and pass tests. A scaffold that produces broken code is WORSE than no scaffold. Phase 9 (VERIFY) is mandatory — if verification fails, fix before presenting to user.

Triggers

• /rune scaffold <description> — Interactive mode (asks questions)
• /rune scaffold express <detailed-description> — Express mode (autonomous)
• Called by team when task is greenfield project creation
• Auto-trigger: when user says "new project", "start from scratch", "bootstrap", "create a new [app/api/lib]"

Calls (outbound)

• ba (L2): Phase 1 — requirement elicitation (always, even in Express mode)
• sentinel-env (L3): Phase 1.5 — environment pre-flight (validate runtime versions, ports, required tools before generating code)
• research (L3): Phase 2 — best practices, starter templates, library comparison
• plan (L2): Phase 3 — architecture and implementation plan
• design (L2): Phase 4 — design system (frontend projects only)
• skill-forge (L2): when scaffolded project includes custom skills or plugin structure
• fix (L2): Phase 5 — code generation (implements the plan)
• team (L1): Phase 5 — parallel implementation when 3+ independent modules
• test (L2): Phase 6 — test suite generation
• docs (L2): Phase 7 — README, API docs, architecture doc
• git (L3): Phase 8 — initial commit with semantic message
• verification (L3): Phase 9 — lint + types + tests + build
• sentinel (L2): Phase 9 — security scan on generated code

Called By (inbound)

• User: /rune scaffold direct invocation
• team (L1): when decomposed task is a new project
• cook (L1): when task is classified as greenfield (rare — cook usually handles features, not projects)

Modes

Interactive Mode (default)

Full phase-gate workflow. User reviews and approves at each major phase:

1. BA asks 5 questions → user answers
2. Plan presented → user approves
3. Design system presented → user approves (if frontend)
4. Implementation proceeds
5. Results presented with full report

Express Mode

Autonomous mode for detailed descriptions. User provides enough context upfront:

1. BA extracts requirements from description (no questions asked)
2. Plan auto-approved (user gave enough detail)
3. Implementation proceeds autonomously
4. User reviews only the final output

Express mode MUST still validate. Auto-approve doesn't mean skip quality checks. BA still extracts requirements — it just doesn't ask questions. Verification (Phase 9) is NEVER skipped in any mode.

Project Templates

Auto-detected from BA output. Template selection informs Phase 3 (Plan) architecture decisions.

Template	Stack	Key Generation Targets
REST API	Node.js/Python + DB + Auth	Routes, models, middleware, migrations, Docker, CI
Web App (Full-stack)	Next.js/SvelteKit + DB	Pages, components, API routes, auth, DB setup
CLI Tool	Node.js/Python/Rust	Commands, arg parsing, config, tests
Library/Package	TypeScript/Python	Src, tests, build config, npm/pypi publish setup
MCP Server	TypeScript/Python	Tools, resources, handlers, tests (delegates to mcp-builder)
Chrome Extension	React/Vanilla	Manifest, popup, content script, background, tests
Mobile App	React Native/Expo	Screens, navigation, auth, API client

Executable Steps

Phase 1 — BA (Requirement Elicitation)

Invoke rune:ba with the user's project description.

Interactive Mode: BA asks 5 questions, discovers hidden requirements, produces Requirements Document.

Express Mode: BA extracts requirements from the detailed description without asking questions. Still produces Requirements Document with scope, user stories, and acceptance criteria.

Output: .rune/features/<project-name>/requirements.md

Gate: In Interactive mode, user must approve requirements before proceeding.

Phase 2 — RESEARCH (Best Practices & Templates)

Invoke rune:research to find:

• Best practices for the detected project type
• Recommended libraries (compare 2-3 options for each concern)
• Starter templates or skeleton projects to reference
• Common pitfalls for this stack

Do NOT clone templates blindly. Use them as REFERENCE for architecture decisions in Phase 3.

Phase 3 — PLAN (Architecture & Implementation)

Invoke rune:plan with the Requirements Document from Phase 1 and research from Phase 2.

Plan must include:

• Directory structure (exact paths)
• File list with purpose of each file
• Implementation order (dependency-aware)
• Technology choices with rationale
• Test strategy (what to test, coverage target)

Gate: In Interactive mode, user must approve plan before proceeding.

Phase 4 — DESIGN (Design System — Frontend Only)

If project has frontend (Web App, Mobile App, Chrome Extension):

• Invoke rune:design to generate design system
• Output: .rune/design-system.md with tokens, components, patterns

If backend-only or CLI → skip this phase.

Phase 5 — IMPLEMENT (Code Generation)

Execute the plan from Phase 3. For each planned file:

1. Create directory structure first
2. Generate shared types/interfaces
3. Generate core modules (models, services, utilities)
4. Generate API layer (routes, controllers, handlers)
5. Generate UI layer (pages, components) if applicable
6. Generate configuration (env, docker, CI)

Parallelization: If plan has 3+ independent modules → invoke rune:team to implement in parallel using worktrees.

Quality during generation:

• Follow project conventions from research
• Include proper error handling
• Use environment variables for config (never hardcode)
• Add TypeScript strict types / Python type hints
• Follow file size limits (< 500 LOC per file)

Phase 6 — TEST (Test Suite Generation)

Invoke rune:test to generate tests based on acceptance criteria from Phase 1:

• Unit tests for each module/function
• Integration tests for API endpoints
• E2E test template for critical flows
• Target: 80%+ coverage on generated code

Each acceptance criterion from BA → at least one test case.

Phase 7 — DOCS (Documentation)

Invoke rune:docs init to generate:

• README.md — Quick Start, Features, Tech Stack, Commands
• ARCHITECTURE.md — if project has 10+ files
• docs/API.md — if project has API endpoints
• .env.example — all required environment variables with descriptions

Phase 8 — GIT (Initial Commit)

Invoke rune:git commit to create initial commit:

• Stage all generated files (except .env, node_modules, pycache)
• Commit message: feat: scaffold <project-name> with <template> template
• Set up .gitignore appropriate for the stack

Phase 9 — VERIFY (Quality Gate)

Invoke rune:verification to run ALL checks:

1. Lint: ESLint/Ruff/Clippy — zero errors
2. Types: tsc --noEmit / mypy — zero errors
3. Tests: npm test / pytest — all pass
4. Build: npm run build / python -m build — succeeds
5. Security: rune:sentinel quick scan — no critical issues

If ANY check fails → fix the issue (invoke rune:fix) and re-verify. Do NOT present broken scaffold to user. Max 3 fix-verify loops. If still failing after 3 → report failures to user with context.

Output Format

## Scaffold Report: [Project Name]
- **Template**: [detected template]
- **Stack**: [framework, language, DB, etc.]
- **Files Generated**: [count]
- **Test Coverage**: [percentage]
- **Phases**: BA → Research → Plan → Design? → Implement → Test → Docs → Git → Verify
- **Verification**: ✅ All checks passed / ⚠️ [issues]

### Generated Structure
[file tree — max 30 lines, group similar files]

### What's Included
- [feature list with key implementation details]

### What's NOT Included (Next Steps)
- [out-of-scope items from BA — things user should build next]

### Commands
- `[start command]` — start development server
- `[test command]` — run tests
- `[build command]` — production build
- `[lint command]` — check code quality

Error Recovery

Phase	Failure	Recovery
Phase 1 (BA)	User refuses to answer questions	Extract what you can, flag assumptions prominently
Phase 2 (Research)	No good references found	Use built-in knowledge, flag as "no external reference"
Phase 3 (Plan)	Plan too complex (10+ phases)	Split into MVP (Phase 1) + Future (Phase 2)
Phase 5 (Implement)	Code generation errors	Invoke fix → retry, max 3 attempts per file
Phase 6 (Test)	Tests fail on generated code	Fix code (not tests) → re-run, max 3 loops
Phase 9 (Verify)	Lint/type/build errors	Fix → re-verify, max 3 loops
Phase 9 (Verify)	Still failing after 3 loops	Report to user with specific failures

Monorepo Mode

When user says "monorepo", "workspace", "turborepo", "nx", or "multi-package", scaffold switches to Monorepo Mode.

Monorepo Detection & Setup

SIGNALS: pnpm-workspace.yaml | turbo.json | nx.json | packages/ directory | "monorepo" in task

Structure Generated

project/
├── packages/
│   ├── core/          ← shared types, utilities
│   ├── api/           ← backend service
│   └── web/           ← frontend app
├── package.json       ← root workspace config (private: true)
├── pnpm-workspace.yaml or turbo.json
├── tsconfig.base.json ← shared TS config
└── .gitignore

Monorepo-Specific Steps (additions to standard scaffold)

1. Workspace config: generate pnpm-workspace.yaml (preferred) or package.json workspaces field
2. Build orchestration: if turborepo → generate turbo.json with build, test, lint pipelines and dependsOn for cross-package deps
3. Shared TS config: tsconfig.base.json at root; each package extends it
4. Internal packages: use workspace:* protocol for cross-package deps (not file: paths)
5. Test isolation: each package has its own npm test script; root runs turbo run test
6. Affected-only CI guidance: include .github/workflows/ci.yml with turbo run test --filter=...[HEAD^1] for affected-only runs

Monorepo Anti-Patterns

• DO NOT generate a single root package.json with all deps — defeats workspace isolation
• DO NOT use file:../core — use workspace:* (pnpm) or * (yarn)
• DO NOT run all tests from root without turborepo/nx orchestration — causes O(n) sequential runs
• DO NOT share mutable state between packages via imports — use events or shared types only

Constraints

1. MUST run BA (Phase 1) before generating any code — even in Express mode
2. MUST generate tests — no project without test suite is "production-ready"
3. MUST generate docs — README at minimum, API docs if applicable
4. MUST pass verification — generated project must build and pass lint/types/tests
5. MUST NOT use --dangerously-skip-permissions or --no-verify — quality gates are mandatory
6. MUST NOT generate hardcoded secrets — use .env.example with placeholder values
7. Express mode MUST still extract and validate requirements — auto-approve ≠ skip analysis
8. MUST generate .gitignore appropriate for the stack
9. MUST respect user's existing project if scaffolding into non-empty directory — warn and ask before overwriting
10. Generated files MUST be < 500 LOC each — split large files

Returns

Artifact	Format	Location
Project directory structure	Directories + files	Project root (per plan)
Source code	Source files	Per plan file list
Test suite	Source files	Co-located or tests/ per framework convention
Documentation	Markdown	README.md, ARCHITECTURE.md, docs/API.md as applicable
Scaffold Report	Markdown (inline)	Emitted at session end

Sharp Edges

Failure Mode	Severity	Mitigation
Generating code without BA → wrong features	CRITICAL	Constraint 1: BA is Phase 1, always runs
Scaffold passes locally but fails on fresh clone	HIGH	Phase 9 catches this — verify build from clean state
Overwriting existing files in non-empty directory	HIGH	Constraint 9: detect existing files, warn user
Express mode skipping quality checks	HIGH	HARD-GATE: Express mode still validates everything
Template mismatch (CLI template for web app)	MEDIUM	Template auto-detected from BA output, confirmed with user
Generated tests are trivial (only smoke tests)	MEDIUM	Phase 6: tests derived from acceptance criteria, not generic
Missing .gitignore → committing node_modules	MEDIUM	Constraint 8: generate stack-appropriate .gitignore

Done When

• Requirements gathered (BA complete, Requirements Document produced)
• Architecture planned (directory structure, tech choices, implementation order)
• Design system generated (if frontend project)
• All code generated (following plan, < 500 LOC per file)
• Test suite generated (80%+ coverage target, acceptance criteria covered)
• Documentation generated (README + ARCHITECTURE + API docs as applicable)
• Initial git commit created
• All verification checks passed (lint + types + tests + build + security)
• Scaffold Report presented to user

Cost Profile

~10000-20000 tokens total (across all sub-skill invocations). Sonnet for orchestration — sub-skills use their own model selection (ba uses opus, git uses haiku, etc.). Most expensive L1 skill due to 9-phase pipeline, but runs rarely (project creation is infrequent).