solo-scaffold

从 PRD + 堆栈模板生成完整的项目 — 目录结构、配置、CLAUDE.md、git 存储库和 GitHub 推送。当用户说“脚手架项目”、“创建新项目”、“启动新应用程序”、“引导项目”或“从 PRD 设置”时使用。使用 SoloGraph 作为模式，使用 Context7 作为最新版本。请勿用于规划功能（使用/计划）或 PRD 生成（使用/验证）。

## 概述（中文）

从 PRD + 堆栈模板生成完整的项目 — 目录结构、配置、CLAUDE.md、git 存储库和 GitHub 推送。当用户说“脚手架项目”、“创建新项目”、“启动新应用程序”、“引导项目”或“从 PRD 设置”时使用。使用 SoloGraph 作为模式，使用 Context7 作为最新版本。请勿用于规划功能（使用/计划）或 PRD 生成（使用/验证）。

## 原文

# /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 `ios-swift`, find existing projects with matching stack.

   b. **Architecture overview** — `codegraph_explain(project="<sibling>")` 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="<pattern>", project="<sibling>")`:
      - 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"

   d. **Check shared packages** — `codegraph_query("MATCH (p:Project)-[:DEPENDS_ON]->(pkg:Package) WHERE p.name = '<sibling>' RETURN pkg.name")`.
      Collect package versions for reference (but verify with Context7 for latest).

   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

   **Goal:** Generated code should feel consistent with your portfolio but use the **best available** patterns, not just the same old ones.
   Limit to 2-3 sibling projects to keep research focused.

5. **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

6. **Show plan + get confirmation** via AskUserQuestion:
   - Project path: `<projects_dir>/<name>` (from `defaults.yaml` or current directory)
   - Stack name and key packages with versions from Context7
   - Proposed directory structure
   - Confirm or adjust before creating files

7. **Create project directory:**
   ```bash
   mkdir -p <projects_dir>/<name>
   ```

8. **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:

   ```yaml
   ---
   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

   This makes every scaffolded project immediately Claude-friendly — new sessions get project context via the skill.

   **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).

9. **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 archi