AI Dev Workflow — 通用 AI 开发流程框架

本仓库是通用 AI 开发流程框架仓。AI 读到本文件后按"AI 执行说明"顺序执行各 Step，自动完成项目空间初始化。

⚠️ 本文件是 Windows (PowerShell) 版本。Linux 用户请使用 README_Linux.md。

AI 在开始执行前，根据运行环境的操作系统自动选择：

• Windows → 继续本文件
• Linux → 切换到 README_Linux.md

目标

让"创建项目空间目录 → clone ai-dev-workflow + specs → AI 读取本 README"这一条路径，一键产出可用的项目级 AI 工程能力：

• 部署项目级 AGENTS.md（工作区 system prompt + 强制开发工作流）
• 部署项目级 skill 目录 .agents/skills/（含全部 gitcode-* 和 superpowers）
• 安装并配置 GitCode CLI
• 验证

初始化完成后日常开发不再需要读本仓。

仓库定位

本仓库是通用能力，不包含任何特定业务逻辑。它提供：

• 通用的 AI 开发工作流（Phase 0-5、闸门、模式判定）
• 通用的 Skill 套件（gitcode-* + superpowers）
• 通用的初始化 Playbook
• 通用的交付规范

业务特定的约束（技术栈、质量门禁命令、代码风格等）由业务仓的 AGENTS.md 填充。

AI 执行说明（必读）

AI 顺序执行下面的 Step 0 → Step 6。每一步：

1. 先输出"目标 + 当前要执行的命令"给用户。
2. 涉及外部远端写操作（如 token 配置、远端 clone 到本地）前，先获得用户确认。
3. 命令执行后做"验证"小节里的检查；失败立即停止并报告原因，不要继续往下走。
4. 全部完成后，输出最终验证报告。

工作目录始终是项目空间根目录（包含本启动仓的父目录）。AI 自行用 Resolve-Path / cd 确保当前位置正确。下文出现的 <workspace> 指代项目空间根目录的绝对路径。

---

Step 0：环境前置检查

目标：确认运行环境满足前提。

检查项	命令	期望
Python	python --version	3.x 任意版本
Git	git --version	任意 2.x
当前目录是项目空间根目录	Get-Location	路径以项目名结尾
ai-dev-workflow/ 存在	Test-Path .\ai-dev-workflow	True
specs/ 存在	Test-Path .\specs	True

任意一项失败，提示用户环境版本不匹配，并且自动安装/拉取，然后重试。

本工作流默认 Windows + PowerShell + Trae（或其他支持 AGENTS.md / .agents/skills/ 的 AI 开发环境）。 Windows PowerShell 中 gc 是 Get-Content 的内置别名；调用 GitCode CLI 一律用 gitcode，不要用 gc。

---

Step 1：部署项目级 AGENTS.md

目标：把启动仓里的 AGENTS.md 复制到工作区根目录，使其作为项目级 system prompt 始终生效。

Copy-Item -Force .\ai-dev-workflow\AGENTS.md .\AGENTS.md

验证：

Test-Path .\AGENTS.md                              # True
(Get-Item .\AGENTS.md).Length -gt 1000             # True

如果工作区根目录已存在 AGENTS.md 且内容不同 → 先与用户确认是否覆盖（备份原文件到 AGENTS.md.bak）。

---

Step 2：部署 gitcode-* skills 到项目级 .agents/skills/

目标：把启动仓内的全部 gitcode-*/ skill 目录拷贝到工作区项目级 skill 目录 ./.agents/skills/。

$skillsDir = ".\.agents\skills"
New-Item -ItemType Directory -Force -Path $skillsDir | Out-Null
Copy-Item -Recurse -Force .\ai-dev-workflow\gitcode-* $skillsDir

验证：

Get-ChildItem $skillsDir -Directory |
    Where-Object { $_.Name -like 'gitcode-*' } |
    Select-Object -ExpandProperty Name

期望至少列出：

gitcode-dev-quality
gitcode-dev-workflow
gitcode-issue-create
gitcode-issue-review
gitcode-issue-triage
gitcode-pipeline-analyzer
gitcode-pr-create
gitcode-pr-review
gitcode-release-helper
gitcode-repo-onboarding
gitcode-security-check

---

Step 3：部署 superpowers skills 到项目级 .agents/skills/

目标：从 GitCode 官方镜像下载 superpowers 套件，展开拷贝到 ./.agents/skills/。

superpowers 上游源：github.com/obra/superpowers，GitCode 官方镜像：GitHub_Trending/su/superpowers。 使用 git clone --depth 1 即可获取，无需访问 GitHub。

部署时必须展开拷贝——把 superpowers/skills/ 下的 skill 子目录平铺到 .agents/skills/ 根，跟 gitcode-* 同级。不允许保留 superpowers/ 这层（Trae 等 AI 开发环境只识别 .agents/skills/<skill-name>/ 一级目录）。

# 浅克隆到临时目录
$tempDir = "$env:TEMP\superpowers"
if (Test-Path $tempDir) { Remove-Item -Recurse -Force $tempDir }
git clone --depth 1 https://gitcode.com/GitHub_Trending/su/superpowers.git $tempDir

# 展开拷贝 skills 子目录到 .agents/skills/
$skillsDir = ".\.agents\skills"
New-Item -ItemType Directory -Force -Path $skillsDir | Out-Null
Copy-Item -Recurse -Force "$tempDir\skills\*" $skillsDir

# 清理临时目录
Remove-Item -Recurse -Force $tempDir

更新：如需更新 superpowers 到最新版本，重复上述命令即可。--depth 1 始终拉取最新快照，不会累积历史。

部署后路径结构（与 gitcode-* 平级）：

.agents/skills/
├── brainstorming/                    ← superpowers
├── writing-plans/                    ← superpowers
├── test-driven-development/          ← superpowers
├── subagent-driven-development/      ← superpowers
├── ... (共 14+ 个 superpowers skill)
├── gitcode-dev-quality/              ← gitcode (Step 2 部署)
├── gitcode-dev-workflow/             ← gitcode
└── ... (共 11 个 gitcode skill)

验证：

Get-ChildItem .\.agents\skills -Directory |
    Where-Object { $_.Name -in @(
        'brainstorming','writing-plans','test-driven-development',
        'subagent-driven-development','requesting-code-review',
        'finishing-a-development-branch','using-superpowers'
    ) } |
    Select-Object -ExpandProperty Name

至少应看到：brainstorming、writing-plans、test-driven-development、subagent-driven-development、requesting-code-review、finishing-a-development-branch、using-superpowers。 缺失任一项 → 停止并向用户报告，不要继续。

---

Step 4：安装 GitCode CLI

目标：让 gitcode 命令在终端可用。

$latestTag = (git ls-remote --refs --tags https://gitcode.com/gitcode-cli/cli.git 2>$null |
    ForEach-Object { if ($_ -match 'v(\d+\.\d+\.\d+)') { $Matches[1] } } |
    Sort-Object { [version]$_ } -Descending |
    Select-Object -First 1)
$wheelUrl = "https://gitcode.com/gitcode-cli/cli/releases/download/v${latestTag}/gitcode_cli-${latestTag}-py3-none-any.whl"
Write-Host "Installing GitCode CLI v${latestTag} ..."
python -m pip install $wheelUrl

如果安装后 gitcode 仍不可用，把用户级 Python Scripts 目录加入 PATH：

$scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts', scheme='nt_user'))"
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
if (($userPath -split ';') -notcontains $scripts) {
    [Environment]::SetEnvironmentVariable('Path', ($userPath.TrimEnd(';') + ';' + $scripts), 'User')
}
New-Item -ItemType Directory -Force -Path (Split-Path -Parent $PROFILE) | Out-Null
if (!(Test-Path $PROFILE) -or ((Get-Content -Raw $PROFILE) -notmatch [regex]::Escape($scripts))) {
    Add-Content -Path $PROFILE -Value "`n`$gitcodeScripts = `"$scripts`"`nif ((Test-Path `$gitcodeScripts) -and ((`$env:Path -split ';') -notcontains `$gitcodeScripts)) {`n    `$env:Path = `"`$env:Path;`$gitcodeScripts`"`n}`n"
}
. $PROFILE

验证：

gitcode version

期望输出类似 gitcode version x.y.z（版本号应与刚安装的一致）。

---

Step 5：配置 GitCode 访问令牌（永久环境变量 GC_TOKEN）

目标：把访问令牌写入 Windows 用户级永久环境变量 GC_TOKEN，避免每次重新登录。

AI 必须先向用户索要 token，不要试图猜测、读取磁盘上其他位置的 token、或跳过此步。

token 获取路径（请用户在浏览器中操作）：

1. 登录 GitCode
2. 点击右上角头像 → 个人设置
3. 左侧 安全设置 → 访问令牌 → 新建访问令牌
4. 勾选权限：至少 Issue / PR / Repository 的读写权限
5. 创建后复制 token（只展示一次），把 token 提供给 AI

拿到 token 后写入环境变量：

[Environment]::SetEnvironmentVariable('GC_TOKEN', '<token>', 'User')
$env:GC_TOKEN = '<token>'

验证：

gitcode auth status

期望输出类似 Logged in as <username>。如果报未登录 → 停止，请用户确认 token 是否正确。

---

Step 6：最终验证

目标：确认所有组件就绪。

Write-Host "=== AI Dev Workflow 初始化验证 ==="
Write-Host "1. AGENTS.md: $(Test-Path .\AGENTS.md)"
Write-Host "2. Skills 目录: $(Test-Path .\.agents\skills)"
Write-Host "3. gitcode-* skills: $((Get-ChildItem .\.agents\skills -Directory | Where-Object { $_.Name -like 'gitcode-*' }).Count) 个"
Write-Host "4. superpowers skills: $((Get-ChildItem .\.agents\skills -Directory | Where-Object { $_.Name -in @('brainstorming','writing-plans','test-driven-development') }).Count) 个"
Write-Host "5. GitCode CLI: $(gitcode version)"
Write-Host "6. GitCode 认证: $(gitcode auth status)"
Write-Host "7. specs 仓: $(Test-Path .\specs)"
Write-Host "=== 验证完成 ==="

全部通过后，输出：

✅ AI Dev Workflow 初始化完成！
- 项目级 AGENTS.md 已部署
- 25+ 个 Skills 已部署
- GitCode CLI 已安装并认证
- specs 文档仓已就绪

下一步：
1. 将业务代码仓 clone 到项目空间根目录
2. 在业务仓创建仓级 AGENTS.md（填充质量门禁等定制项）
3. 开始开发时，AI 会自动读取 AGENTS.md 并按工作流执行