solo-scaffold

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/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.

从PRD+技术栈模板生成完整项目，创建目录结构、配置文件、CLAUDE.md、Git仓库并推送到GitHub。通过SoloGraph学习现有项目的一致模式，使用Context7获取最新库版本。

Steps

步骤

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.
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
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.
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.
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:
```
<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
Create project directory:
bash
```
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:

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

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

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:

bash

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:

bash

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

解析参数：从
```
$ARGUMENTS
```
中提取
```
<project-name>
```
和
```
<stack-name>
```
。
- 如果参数未提供或不完整，使用AskUserQuestion询问缺失的值。
- 展示
```
templates/stacks/*.yaml
```
  中的可用技术栈（权威来源）。如果有MCP
```
project_info
```
  可用，同时展示从活跃项目中检测到的技术栈。列出每个YAML文件
```
description
```
  字段中的技术栈名称及单行描述。
- 项目名称需使用kebab-case格式。
加载组织默认配置：从
```
~/.solo-factory/defaults.yaml
```
读取：
- ```
org_domain
```
  （例如
```
com.mycompany
```
  ）、
```
apple_dev_team
```
  、
```
github_org
```
  、
```
projects_dir
```
- 如果文件不存在，通过AskUserQuestion询问：
  - “你的Bundle ID反向域名前缀是什么？”（例如
```
com.mycompany
```
    ）
  - “Apple开发者团队ID？”（可选，若不涉及iOS则留空）
- 创建
```
~/.solo-factory/defaults.yaml
```
  保存答案，供后续使用
- 替换所有生成文件中的
```
<org_domain>
```
  、
```
<apple_dev_team>
```
  、
```
<github_org>
```
  占位符
加载技术栈+PRD+开发原则：
- 查找技术栈YAML文件：通过
```
kb_search
```
  或Glob在插件模板中搜索
```
stacks/<stack>.yaml
```
  。
- 如果未找到技术栈YAML文件，使用内置的技术栈知识（包、结构、部署方式）。
- 检查PRD是否存在：查找
```
docs/prd.md
```
  或在当前目录搜索
```
prd.md
```
  - 如果不存在：生成基础PRD模板
- 查找开发原则：搜索
```
dev-principles.md
```
  或使用内置的SOLID/DRY/KISS/TDD原则。
通过SoloGraph学习现有项目（从自有代码库中学习——批判性地）：

在生成代码前，学习使用相同技术栈的活跃项目。不要盲目复制——现有项目可能存在遗留模式或错误。评估哪些内容真正有用。
a. 查找同类项目——使用
```
project_info()
```
列出活跃项目，筛选出技术栈匹配的项目。示例：对于
```
ios-swift
```
，查找所有使用该技术栈的现有项目。
b. 架构概览——对每个同类项目执行
```
codegraph_explain(project="<sibling>")
```
。获取：目录层级、关键模式（基类、协议、CRUD）、核心依赖、枢纽文件。
c. 搜索可复用模式——执行
```
project_code_search(query="<pattern>", project="<sibling>")
```
：
- 搜索技术栈特定模式：“MVVM ViewModel”、“SwiftData model”、“AVFoundation recording”
- 搜索共享基础设施：“Makefile”、“project.yml”、“.swiftlint.yml”
- 搜索服务：“Service protocol”、“actor service”
d. 检查共享包——执行
```
codegraph_query("MATCH (p:Project)-[:DEPENDS_ON]->(pkg:Package) WHERE p.name = '<sibling>' RETURN pkg.name")
```
。收集包版本作为参考（但需通过Context7验证是否为最新版本）。
e. 批判性评估采纳与舍弃的内容：
- 采纳：一致的目录结构、Makefile目标、配置模式（.swiftlint.yml、project.yml）
- 采纳：经过验证的基础设施模式（actor服务、基于协议的依赖反转）
- 舍弃（若过时）：旧API模式（ObservableObject → @Observable）、已弃用的依赖
- 舍弃（若过于复杂）：不必要的抽象、不符合新项目需求的模式
- 优先选择：当Context7的最新最佳实践与旧项目模式冲突时，优先使用前者
目标：生成的代码应与你的项目组合保持一致，但使用可用的最佳模式，而非仅仅沿用旧模式。限制为2-3个同类项目，保持研究聚焦。
Context7研究（最新库版本和最佳实践）：
- 对于技术栈中的每个核心包：
  - ```
  mcp__context7__resolve-library-id
```
  ——查找Context7库ID
- ```
mcp__context7__query-docs
```
    ——查询“最新版本、项目设置、推荐文件结构、最佳实践”
- 收集：当前版本、推荐目录结构、配置模式、设置命令
- 限制为3-4个最重要的包，保持研究聚焦
展示计划并获取确认：通过AskUserQuestion：
- 项目路径：
```
<projects_dir>/<name>
```
  （来自
```
defaults.yaml
```
  或当前目录）
- 技术栈名称及来自Context7的核心包版本
- 拟议的目录结构
- 在创建文件前确认或调整
创建项目目录：
bash
```
mkdir -p <projects_dir>/<name>
```

创建文件结构：基于技术栈。**SGR优先：始终先创建领域模型/架构，再添加任何逻辑或视图。**每个项目都会包含以下通用文件：

<projects_dir>/<name>/
├── CLAUDE.md          # AI友好型项目文档（是地图而非手册——参考Harness Engineering）
├── Makefile           # 通用命令（运行、测试、构建、 lint、部署、集成）
├── README.md          # 面向人类的项目文档
├── docs/
│   ├── prd.md         # PRD副本
│   ├── QUALITY_SCORE.md  # 领域质量等级（Harness：垃圾回收）
│   └── ARCHITECTURE.md   # 模块边界和依赖规则
├── cli/               # CLI工具——镜像核心业务逻辑（CLI优先测试原则）
│   └── main.ts|py     # 确定性流水线入口点（无需LLM）
├── .claude/
│   └── skills/        # 产品特定工作流技能
│       └── dev/
│           └── SKILL.md  # 开发工作流技能（运行、测试、部署）
└── .gitignore         # 技术栈特定忽略规则

CLI优先测试：生成

cli/

目录及存根文件，从

lib/

（或等效目录）导入核心业务逻辑。CLI应能确定性地运行主流水线，无需LLM、网络或UI。这支持

make integration

进行流水线验证。详见

dev-principles.md

→“CLI-First Testing”。

.claude/skills/dev/SKILL.md

——产品开发工作流技能

生成一个技能文档，指导Claude如何处理该特定项目。结构如下：

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

正文应包含：

技术栈：核心包、版本、配置文件位置
命令：
```
make dev
```
、
```
make test
```
、
```
make build
```
、
```
make deploy
```
（来自Makefile）
架构：目录结构、命名规范、关键模式
测试：如何运行测试、测试文件位置、测试规范
常见任务：添加新页面/屏幕、添加API端点、添加模型

这使得每个通过脚手架生成的项目立即对Claude友好——新会话可通过该技能获取项目上下文。

MCP服务器（可选）：如果PRD表明是数据/AI/开发者产品，同时生成MCP服务器存根。详见

templates/mcp-skills-bundle.md

中的完整“MCP + Skills bundle”模式及生成MCP的规则。

然后添加技术栈特定文件。详见

references/stack-structures.md

中的各技术栈文件列表（8种技术栈：nextjs、ios、kotlin、cloudflare、astro-static、astro-hybrid、python-api、python-ml）。

生成Makefile：适配技术栈，包含：
```
help
```
、
```
dev
```
、
```
test
```
、
```
lint
```
、
```
format
```
、
```
build
```
、
```
clean
```
、
```
deploy
```
目标。
- 如果项目有CLI或确定性流水线，添加
```
integration
```
  目标（若未实现则添加存根注释）
- ios-swift还必须包含：
```
generate
```
  （xcodegen）、
```
archive
```
  （xcodebuild archive）、
```
open
```
  （打开.xcarchive用于分发）
- Makefile是标准命令接口——
```
/build
```
  和
```
/review
```
  使用
```
make
```
  目标而非原始命令
为新项目生成CLAUDE.md：

项目概述（来自PRD的问题/解决方案）
技术栈（来自Context7的包+版本）
技能部分：列出可用的
```
.claude/skills/
```
及描述
目录结构
通用命令（参考
```
make help
```
）
SGR / 领域优先部分
架构原则（来自开发原则）
Harness Engineering部分（来自
```
templates/principles/harness-engineering.md
```
）：
- CLAUDE.md理念：“本文件是地图而非手册——保持约100行，指向docs/目录”
- Harness健康检查表（与该项目相关的子集）
- 架构约束：模块边界、边界处的数据验证
- Agent可读性：lint错误必须包含修复说明
- 反模式：不要在Slack/文档中存储知识，不要微观管理实现
应做/不应做部分
MCP集成部分（可选，如果有MCP工具）：列出可用的MCP工具：
```
project_code_search
```
、
```
kb_search
```
、
```
session_search
```
、
```
codegraph_query
```
、
```
project_info
```
、
```
web_search
```

生成README.md：项目名称、描述、前置条件、设置、运行/测试/部署。
生成.gitignore：技术栈特定的忽略模式。
复制PRD到docs/目录：从知识库复制或就地生成。

Git初始化+首次提交：

bash

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

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

创建GitHub私有仓库并推送：

bash

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

注册项目并索引代码（可选，如果有MCP工具）：
- 如果
```
project_code_reindex
```
  MCP工具可用，为新项目建立索引以便代码搜索：
```
mcp__solograph__project_code_reindex(project="<name>")
```

输出摘要：

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

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

在报告“project scaffolded”之前：

验证所有生成的文件是否存在（列出目录树）。
运行安装命令（
```
pnpm install
```
、
```
uv sync
```
等）——必须成功。
运行开发/构建命令（如果适用）——不得报错。
验证Git初始化+首次提交是否成功（
```
git log --oneline -1
```
）。
验证GitHub仓库是否创建成功（
```
gh repo view
```
或检查URL）。

在未运行安装命令并验证其成功的情况下，绝不要说“scaffold complete”。

Common Issues

常见问题

Stack YAML not found

技术栈YAML文件未找到

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.

原因：

templates/stacks/

中缺少技术栈模板或未创建符号链接。 解决方法：如果未找到模板，技能将使用内置知识。要修复该问题：确保

solo-factory/templates/stacks/<stack>.yaml

存在。

GitHub repo creation fails

GitHub仓库创建失败

Cause:

gh

CLI not authenticated or repo name already taken. Fix: Run

gh auth login

first. If name taken, choose a different project name.

原因：

gh

CLI未认证或仓库名称已被占用。 解决方法：先运行

gh auth login

。如果名称已被占用，选择其他项目名称。

Context7 queries fail

Context7查询失败

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

原因：MCP服务器未运行或Context7达到速率限制。 解决方法：技能将使用技术栈YAML文件中的版本作为备选。Context7是增强功能，并非必需。

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.

原因：未创建

~/.solo-factory/defaults.yaml

。 解决方法：先运行

/init

进行一次性设置，或技能将交互式询问Bundle ID和团队ID。

solo-scaffold

Original

Translation

/scaffold

/scaffold

Steps

步骤

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

`.claude/skills/dev/SKILL.md`
——产品开发工作流技能

Verification

验证

Common Issues

常见问题

Stack YAML not found

技术栈YAML文件未找到

GitHub repo creation fails

GitHub仓库创建失败

Context7 queries fail

Context7查询失败

org defaults missing

组织默认配置缺失

solo-scaffold

Original

Translation

/scaffold

/scaffold

Steps

步骤

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

.claude/skills/dev/SKILL.md——产品开发工作流技能

Verification

验证

Common Issues

常见问题

Stack YAML not found

技术栈YAML文件未找到

GitHub repo creation fails

GitHub仓库创建失败

Context7 queries fail

Context7查询失败

org defaults missing

组织默认配置缺失

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

`.claude/skills/dev/SKILL.md`
——产品开发工作流技能