solo-scaffold

name	solo-scaffold
description	Generate complete project from PRD + stack template — directory structure, configs, CLAUDE.md, git repo, and GitHub push. Use when user says "scaffold project", "create new project", "start new app", "bootstrap project", or "set up from PRD". Uses SoloGraph for patterns and Context7 for latest versions. Do NOT use for planning features (use /plan) or PRD generation (use /validate).
license	MIT
metadata	{"author":"fortunto2","version":"1.5.1","openclaw":{"emoji":"🏗️"}}
allowed-tools	Read, Grep, Bash, Glob, Write, Edit, AskUserQuestion, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__solograph__kb_search, mcp__solograph__project_info, mcp__solograph__project_code_search, mcp__solograph__codegraph_query, mcp__solograph__codegraph_explain, mcp__solograph__project_code_reindex
argument-hint	[project-name] [stack-name]

/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

1. Parse arguments from $ARGUMENTS — extract <project-name> and <stack-name>.

   • If not provided or incomplete, use AskUserQuestion to ask for missing values.
   • Show available stacks from templates/stacks/*.yaml (source of truth). If MCP project_info available, also show detected stacks from active projects. List stack names with one-line descriptions from each YAML's description field.
   • Project name should be kebab-case.

2. 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 <org_domain>, <apple_dev_team>, <github_org> placeholders in all generated files

3. Load stack + PRD + principles:

   • Look for stack YAML: search for stacks/<stack>.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.

4. Study existing projects via SoloGraph (learn from your own codebase — critically):

   Before generating code, study active projects with the same stack. Don't blindly copy — existing projects may have legacy patterns or mistakes. Evaluate what's actually useful.

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

• 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): Lists available MCP tools: project_code_search, kb_search, session_search, codegraph_query, project_info, web_search

11. Generate README.md — project name, description, prerequisites, setup, run/test/deploy.

12. Generate .gitignore — stack-specific patterns.

13. Copy PRD to docs/: Copy from knowledge base or generate in place.

14. Git init + first commit:

    cd <projects_dir>/<name>
    git init && git add . && git commit -m "Initial project scaffold
    
    Stack: <stack-name>
    Generated by /scaffold"
    

15. Create GitHub private repo + push:

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

16. 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>")
      

17. 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":

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

Never say "scaffold complete" without running the install and verifying it works.

Common Issues

Stack YAML not found

Cause: Stack template missing from templates/stacks/ or not symlinked. Fix: Skill uses built-in knowledge if template not found. To fix: ensure solo-factory/templates/stacks/<stack>.yaml exists.

GitHub repo creation fails

Cause: gh CLI not authenticated or repo name already taken. Fix: Run gh auth login first. If name taken, choose a different project name.

Context7 queries fail

Cause: MCP server not running or Context7 rate limited. Fix: Skill proceeds with stack YAML versions as fallback. Context7 enhances but is not required.

org defaults missing

Cause: ~/.solo-factory/defaults.yaml not created. Fix: Run /init first for one-time setup, or skill will ask for bundle ID and team ID interactively.