/scaffold

Scaffold a complete project from PRD + stack template. Creates directory structure, configs, CLAUDE.md, git repo, and pushes to GitHub. Studies existing projects via SoloGraph for consistent patterns, uses Context7 for latest library versions.

Steps

• Parse arguments from $ARGUMENTS — extract and .
• If not provided or incomplete, use AskUserQuestion to ask for missing values.
• Show available stacks from templates/stacks/*.yaml (source of truth).

• Project name should be kebab-case.
• Load org defaults from ~/.solo-factory/defaults.yaml:
• Read org_domain (e.g. com.mycompany), apple_dev_team, github_org, projects_dir
• If file doesn't exist, ask via AskUserQuestion:
• "What is your reverse-domain prefix for bundle IDs?" (e.g. com.mycompany)
• "Apple Developer Team ID?" (optional, leave empty if no iOS)
• Create ~/.solo-factory/defaults.yaml with answers for future runs
• Replace , , placeholders in all generated files
• Load stack + PRD + principles:
• Look for stack YAML: search for stacks/.yaml in plugin templates (via kb_search or Glob).
• If stack YAML not found, use built-in knowledge of the stack (packages, structure, deploy).
• Check if PRD exists: docs/prd.md or search current directory for prd.md
• If not: generate a basic PRD template
• Look for dev principles: search for dev-principles.md or use built-in SOLID/DRY/KISS/TDD principles.
• Study existing projects via SoloGraph (learn from your own codebase — critically):

a. Find sibling projects — use project_info() to list active projects, filter by matching stack. Example: for ios-swift, find existing projects with matching stack.

b. Architecture overview — codegraph_explain(project="") for each sibling. Gives: directory layers, key patterns (base classes, protocols, CRUD), top dependencies, hub files.

c. Search for reusable patterns — project_code_search(query="", project=""):

• Search for stack-specific patterns: "MVVM ViewModel", "SwiftData model", "AVFoundation recording"
• Search for shared infrastructure: "Makefile", "project.yml", ".swiftlint.yml"
• Search for services: "Service protocol", "actor service"

e. Critically evaluate what to adopt vs skip:

• Adopt: consistent directory structure, Makefile targets, config patterns (.swiftlint.yml, project.yml)
• Adopt: proven infrastructure patterns (actor services, protocol-based DIP)
• Skip if outdated: old API patterns (ObservableObject → @Observable), deprecated deps
• Skip if overcomplicated: unnecessary abstractions, patterns that don't fit the new project's needs
• Always prefer: Context7 latest best practices over old project patterns when they conflict

• Context7 research (latest library versions and best practices):
• For each key package from the stack:
• mcp__context7__resolve-library-id — find the Context7 library ID
• mcp__context7__query-docs — query "latest version, project setup, recommended file structure, best practices"
• Collect: current versions, recommended directory structure, configuration patterns, setup commands
• Limit to the 3-4 most important packages to keep research focused
• Show plan + get confirmation via AskUserQuestion:
• Project path: / (from defaults.yaml or current directory)
• Stack name and key packages with versions from Context7
• Proposed directory structure
• Confirm or adjust before creating files
• Create project directory:

mkdir -p <projects_dir>/<name>

• Create file structure based on the stack. SGR-first: always start with domain schemas/models before any logic or views. Every project gets these common files:

<projects_dir>/<name>/
   ├── CLAUDE.md          # AI-friendly project docs (map, not manual — see Harness Engineering)
   ├── Makefile           # Common commands (run, test, build, lint, deploy, integration)
   ├── README.md          # Human-friendly project docs
   ├── docs/
   │   ├── prd.md         # Copy of PRD
   │   ├── QUALITY_SCORE.md  # Domain quality grades (harness: garbage collection)
   │   └── ARCHITECTURE.md   # Module boundaries and dependency rules
   ├── cli/               # CLI utility — mirrors core business logic (CLI-First Testing principle)
   │   └── main.ts|py     # Deterministic pipeline entry point (no LLM required)
   ├── .claude/
   │   └── skills/        # Product-specific workflow skills
   │       └── dev/
   │           └── SKILL.md  # Dev workflow skill (run, test, deploy)
   └── .gitignore         # Stack-specific ignores

CLI-First Testing: generate a cli/ directory with a stub that imports core business logic from lib/ (or equivalent). The CLI should run the main pipeline deterministically without requiring LLM, network, or UI. This enables make integration for pipeline verification. See dev-principles.md → "CLI-First Testing".

### .claude/skills/dev/SKILL.md — product dev workflow skill

Generate a skill that teaches Claude how to work with THIS specific project. Structure:

---
   name: <name>-dev
   description: Dev workflow for <Name> — run, test, build, deploy. Use when working on <Name> features, fixing bugs, or deploying changes. Do NOT use for other projects.
   license: MIT
   metadata:
     author: <github_org>
     version: "1.0.0"
   allowed-tools: Read, Grep, Glob, Bash, Write, Edit
   ---

Body should include:

• Stack: key packages, versions, where configs live
• Commands: make dev, make test, make build, make deploy (from Makefile)
• Architecture: directory structure, naming conventions, key patterns
• Testing: how to run tests, where test files live, testing conventions
• Common tasks: add a new page/screen, add an API endpoint, add a model

MCP server (optional): If PRD indicates a data/AI/developer product, also generate MCP server stub. See templates/mcp-skills-bundle.md for the full "MCP + Skills bundle" pattern and rules for when to generate MCP.

Then add stack-specific files. See references/stack-structures.md for per-stack file listings (8 stacks: nextjs, ios, kotlin, cloudflare, astro-static, astro-hybrid, python-api, python-ml).

• Generate Makefile — stack-adapted with: help, dev, test, lint, format, build, clean, deploy targets.
• Add integration target if the project has a CLI or deterministic pipeline (stub with a comment if not yet implemented)
• ios-swift must also include: generate (xcodegen), archive (xcodebuild archive), open (open .xcarchive for Distribute)
• The Makefile is the canonical command interface — /build and /review use make targets instead of raw commands
• Generate CLAUDE.md for the new project:
• Project overview (problem/solution from PRD)
• Tech stack (packages + versions from Context7)
• Skills section: list available .claude/skills/ with descriptions
• Directory structure
• Common commands (reference make help)
• SGR / Domain-First section
• Architecture principles (from dev-principles)
• Harness Engineering section (from templates/principles/harness-engineering.md):
• CLAUDE.md philosophy: "this file is a map, not a manual — keep ~100 lines, point to docs/"
• Harness health checklist (subset relevant to this project)
• Architectural constraints: module boundaries, data validation at boundaries
• Agent legibility: lint errors must include remediation instructions
• Anti-patterns: don't put knowledge in Slack/Docs, don't micromanage implementation
• Do/Don't sections
• MCP Integration section (optional, if MCP tools available):

• Generate README.md — project name, description, prerequisites, setup, run/test/deploy.
• Generate .gitignore — stack-specific patterns.
• Copy PRD to docs/: Copy from knowledge base or generate in place.
• Git init + first commit:

cd <projects_dir>/<name>
    git init && git add . && git commit -m "Initial project scaffold

    Stack: <stack-name>
    Generated by /scaffold"

• Create GitHub private repo + push:

cd <projects_dir>/<name>
    gh repo create <name> --private --source=. --push

• Register project + index code (optional, if MCP tools available):
• If project_code_reindex MCP tool is available, index the new project for code search:

mcp__solograph__project_code_reindex(project="<name>")

• Output summary:

Project scaffolded!

      Path:   <projects_dir>/<name>
      GitHub: https://github.com/<user>/<name>
      Stack:  <stack-name>
      PRD:    docs/prd.md
      CLAUDE: configured
      Skills: .claude/skills/dev/ (project workflow)

    Next steps:
      cd <projects_dir>/<name>
      <install command>    # pnpm install / uv sync / etc.
      <run command>        # pnpm dev / uv run ... / etc.

    Then: /setup → /plan "First feature" → /build

Verification

Before reporting "project scaffolded":

• Verify all generated files exist (ls the directory tree).
• Run the install command (pnpm install, uv sync, etc.) — must succeed.
• Run the dev/build command if applicable — must not error.
• Verify git init + first commit succeeded (git log --oneline -1).
• Verify GitHub repo creation (gh repo view or check URL).

Common Issues

Stack YAML not found

GitHub repo creation fails

Context7 queries fail

org defaults missing