{
  "markdown": "# Stackpilot\n\n[![CI](https://github.com/9aoyang/stackpilot/actions/workflows/ci.yml/badge.svg)](https://github.com/9aoyang/stackpilot/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![GitHub release](https://img.shields.io/github/v/release/9aoyang/stackpilot)](https://github.com/9aoyang/stackpilot/releases)\n[![Agent Skills](https://img.shields.io/badge/Agent_Skills-compatible-blue)](https://agentskills.io)\n\n**English** | [中文](#中文文档)\n\nGeneral methodology for coding agents. Turn a request into verified software\nthrough design, spec, plan, execution, review, and finish — across models and\nhosts, with the Claude Code adapter currently the most complete implementation.\n\n```\n Feature request → Design → Spec → Plan → sp-architect → sp-dev → sp-qa → Delivery\n```\n\n## One StackPilot Entry\n\nUsers should start with **StackPilot**, not a menu of skills. In Claude Code the\nentry is `/stackpilot` or a natural-language request routed by the plugin\nbootstrap. In other hosts, StackPilot should still feel like one product entry;\nthe portable skill files are adapter primitives for hosts that require discrete\nAgent Skills, not commands users are expected to memorize.\n\n**Default gates behind StackPilot** — these run automatically or on demand when\nthe route needs them:\n\n| Internal route | When StackPilot uses it |\n|----------------|-------------------------|\n| `brainstorming` | Creative work (features/components) enters the explore → ask clarifying questions → propose approaches → design doc flow |\n| `stackpilot-methodology` | Feature work enters the host-neutral explore → design → spec/criteria → plan → execute → review → finish flow |\n| `stackpilot-planning` | Approved spec/design/clear requirement needs exact implementation tasks |\n| `stackpilot-workspace` | Non-trivial implementation needs isolated setup and clean baseline verification |\n| `stackpilot-plan-execution` | Existing plans need task-by-task execution with controller verification |\n| `stackpilot-parallel-agents` | Independent tasks, failures, research domains, or review domains can safely run concurrently |\n| `stackpilot-review-response` | Human or external review feedback needs technical verification before fixes |\n| `stackpilot-completion-verification` | Completion, merge, PR, or success claims need fresh evidence |\n| `tdd-development` | Production code changes need RED/GREEN/REFACTOR discipline |\n| `qa-12-dimensions` | QA or review work needs scenario coverage and adversarial review |\n| `architecture-review` | Shared structures or multi-file designs need a grounded architecture decision |\n| `systematic-debugging` | Bugs, failing tests, and broken integrations need root-cause investigation |\n\n**Host adapters** implement the same method with host-native tools. The Claude\nCode adapter is currently the full autonomous sprint adapter:\n\n| Entry | What it does |\n|-------|-------------|\n| `/stackpilot` | Primary user entry in Claude Code: tidy → resume → design → spec → plan → autonomous coding → QA → ship. Dispatches `sp-*` subagents via Claude Code's native `Agent` tool. |\n| `/stackpilot-research` | Expert on-demand mode for deep research reports using cross-longitudinal analysis (横纵分析法) |\n| `/stackpilot-sync` | Maintainer-only mode for tracking and syncing external skill references |\n| `stackpilot-skill-authoring` | Maintainer-only internal gate for changing StackPilot skills |\n\n## Automatic Routing\n\nWhen installed as a Claude Code plugin, Stackpilot uses a session bootstrap hook\nto make StackPilot the default route for non-trivial coding work. Natural\nfeature requests are routed into the internal `stackpilot-methodology` gate\nbefore implementation; in Claude Code, that gate can hand execution to the\n`/stackpilot` host adapter for autonomous sprints. Bugs route to\n`systematic-debugging`, production code routes through `tdd-development`, and\ncompletion claims require fresh verification evidence. Explicit user and project instructions still win;\nsaying to skip planning or verify manually disables the corresponding route for\nthat request.\n\nDuring exploration and design, StackPilot asks one question at a time, includes\nits recommended answer, and reads code before asking about anything the repo can\nalready answer. Terminal design decisions default to one recommended approach;\nbrowser design options remain reserved for visual or interactive comparisons.\n\n## Demo\n\n```\n> /stackpilot\n\n━━━━━━━━━━━━━━━━━━━━━━━━━\n  Stackpilot Sprint Status\n━━━━━━━━━━━━━━━━━━━━━━━━━\n  No active sprint.\n━━━━━━━━━━━━━━━━━━━━━━━━━\n\nWhat feature would you like to build?\n\n> Add user search with fuzzy matching\n\nNode 1: Exploring codebase...\nNode 2: Design proposal ready in terminal. Browser view skipped: text is clearer here.\nNode 3: Writing spec → .stackpilot/specs/2026-04-05-user-search-design.md ✓\n        Writing criteria → .stackpilot/specs/2026-04-05-user-search-criteria.md ✓\n        Review in terminal: approve / changes: <text> / reverify\nNode 4: Writing plan → .stackpilot/plans/2026-04-05-user-search-plan.md ✓\n        Live dashboard skipped: single straightforward wave\n\nPlan is ready. Proceed with coding? (Y/n)\n\n  ✅ TASK-001  design search API       arch → dev → QA passed   (1/3)\n  ✅ TASK-002  implement endpoint      dev → QA passed           (2/3)\n  ✅ TASK-003  integration tests       dev → QA passed           (3/3)\n\nSprint complete. All tests passing.\nSprint evals written: .stackpilot/runs/2026-04-05-user-search-plan/sprint-evals.md\nFeedback inbox: no unresolved HIGH/CRITICAL items\nDev server running at: http://localhost:3000\n\nA. Merge into main  B. Push and create PR  C. Leave as-is  D. Discard\n```\n\n## Install\n\nStackPilot installs as one package with two internal layers:\n\n- **Methodology gates** — portable Agent Skills used by the StackPilot route in\n  hosts that support the Agent Skills standard.\n- **Host adapters** — host-native implementations of the same gates. Claude\n  Code is currently the full autonomous sprint adapter.\n\n| Host | Current support |\n|------|-----------------|\n| Claude Code | Full adapter + SessionStart auto-routing via `.claude-plugin/` |\n| Cursor | StackPilot routing bootstrap + portable internal gates via `.cursor-plugin/` |\n| OpenAI Codex | StackPilot package metadata + portable internal gates via `.codex-plugin/` |\n| Gemini CLI | StackPilot routing context + portable internal gates via `gemini-extension.json` / `GEMINI.md` |\n\nClaude Code one-line install:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/9aoyang/stackpilot/main/install.sh | bash\n```\n\nOr manually:\n\n```bash\ngit clone https://github.com/9aoyang/stackpilot.git ~/Documents/github/stackpilot\nbash ~/Documents/github/stackpilot/scripts/restore.sh\n```\n\nThe full autonomous sprint adapter requires git and Claude Code. The methodology\ngates are portable to Agent Skills-compatible hosts; additional host adapters\nshould expose one StackPilot entry and reuse the same core gates instead of\nforking the method. If you use skillshare, make it the single synchronization\nsource for shared skills.\n\nSkills auto-update: `/stackpilot` checks for upstream updates once per day and pulls new skills automatically.\n\n## Config\n\n`stackpilot.config.yml` is **auto-generated** when you first run `/stackpilot`. It detects your test framework automatically.\n\n```yaml\n# stackpilot.config.yml (auto-generated)\nqa:\n  coverage_threshold: 80\n  test_command: npm test    # auto-detected from project files\n```\n\nAuto-detection supports: Node.js, Python, Go, Rust, Ruby, Java/Kotlin, Elixir, PHP, .NET.\n\n## Architecture\n\nSee [docs/architecture.md](docs/architecture.md) for the full system design.\nSee [docs/superpowers-gap-audit.md](docs/superpowers-gap-audit.md) for the\nSuperpowers workflow coverage audit. It is a gap audit, not a goal to mirror the\nnumber or shape of Superpowers skills.\n\nKey design decisions:\n- **One StackPilot entry** — users start with StackPilot; internal gates route automatically or on demand\n- **Methodology core first** — StackPilot is a general methodology, not a single-host script\n- **Host adapters** — Claude Code adapter uses Agent tool with `isolation: \"worktree\"` for parallel development\n- **Agent Skills standard** — core methodology skills work across 30+ agent products\n- **Progressive disclosure** — SKILL.md stays lean (<500 lines), heavy content in `references/`\n- **Plan/handoff as persistence** — TaskCreate for runtime; plan, handoff, state, and event files for cross-session recovery\n- **Data-layer handoff** — `handoff.json` records phase/status/next action for reliable resume\n- **Sprint evals** — `sprint-evals.md` summarizes retries, plateau/stuck signals, criteria state, and recommendation\n- **Feedback inbox** — `.stackpilot/feedback/open|resolved` keeps external audit feedback visible through Finish\n\n## [Contributing](CONTRIBUTING.md) | [License](LICENSE)\n\n---\n\n<a id=\"中文文档\"></a>\n\n# 中文文档\n\n[![CI](https://github.com/9aoyang/stackpilot/actions/workflows/ci.yml/badge.svg)](https://github.com/9aoyang/stackpilot/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![GitHub release](https://img.shields.io/github/v/release/9aoyang/stackpilot)](https://github.com/9aoyang/stackpilot/releases)\n[![Agent Skills](https://img.shields.io/badge/Agent_Skills-compatible-blue)](https://agentskills.io)\n\n**[English](#stackpilot)** | 中文\n\n面向 coding agents 的通用方法论。把需求推进为经过验证的软件：设计、spec、\nplan、执行、审查、收尾都纳入同一套流程；Claude Code adapter 目前是最完整实现。\n\n```\n 功能需求 → 设计讨论 → Spec → Plan → sp-architect → sp-dev → sp-qa → 交付\n```\n\n## 一个 StackPilot 入口\n\n用户应该从 **StackPilot** 开始，而不是记一串 skills。在 Claude Code 里入口是\n`/stackpilot`，或者由 plugin bootstrap 自动路由的自然语言需求。在其他宿主里，\nStackPilot 也应该表现为一个产品入口；portable skill 文件只是那些需要离散 Agent\nSkills 的宿主所用的 adapter primitives，不是要求用户记住的命令菜单。\n\n**StackPilot 背后的默认门禁** — 这些能力由 StackPilot 自动触发或按需触发：\n\n| 内部 route | StackPilot 何时使用 |\n|------------|---------------------|\n| `stackpilot-methodology` | 功能需求进入宿主无关的探索 → 设计 → spec/criteria → plan → 执行 → 审查 → 收尾流程 |\n| `stackpilot-planning` | 已批准 spec/design/明确需求需要精确 implementation tasks |\n| `stackpilot-workspace` | 非平凡实现需要隔离环境、setup、clean baseline verification |\n| `stackpilot-plan-execution` | 既有 plan 需要逐 task 执行并由主控验证 |\n| `stackpilot-parallel-agents` | 独立任务、失败域、调研域或 review domain 可安全并行 |\n| `stackpilot-review-response` | 人类或外部 review feedback 需要先技术验证再修复 |\n| `stackpilot-completion-verification` | 完成、merge、PR 或成功声明前需要新鲜证据 |\n| `tdd-development` | 生产代码改动需要 RED/GREEN/REFACTOR 纪律 |\n| `qa-12-dimensions` | QA 或 review 需要场景覆盖和对抗式审查 |\n| `architecture-review` | 共享结构或多文件设计需要基于代码库的架构决策 |\n| `systematic-debugging` | bug、失败测试、集成异常需要根因调查 |\n\n**宿主适配器** 用不同 host 的原生工具实现同一套方法论。Claude Code adapter\n目前是完整自主 sprint adapter：\n\n| 入口 | 功能 |\n|------|------|\n| `/stackpilot` | Claude Code 的主要用户入口：tidy→resume→设计→spec→plan→自主编码→QA→上线。通过 Claude Code 原生 `Agent` 工具调度 `sp-*` subagents。 |\n| `/stackpilot-research` | 专家按需模式：横纵分析法深度研报 |\n| `/stackpilot-sync` | 维护者模式：追踪和同步外部 skill references |\n| `stackpilot-skill-authoring` | 维护者内部 gate：修改 StackPilot skills 时使用 |\n\n## 自动路由\n\n以 Claude Code plugin 安装时，Stackpilot 会通过 session bootstrap hook 让\nStackPilot 成为非平凡 coding work 的默认 route。自然语言功能需求会在实现前进入\n内部 `stackpilot-methodology` gate；在 Claude Code 中，这个 gate 可以把执行交给\n`/stackpilot` 宿主适配器。bug 会走 `systematic-debugging`，生产代码改动会走\n`tdd-development`，完成声明前必须有新鲜验证证据。`PreToolUse` gate 会机械阻断\n未激活 StackPilot process 就先读文件、执行命令或创建任务的 feature、bug、\nproduction-code 工具调用。用户和项目显式指令仍然优先；如果用户要求跳过规划或自己验证，就按用户指令执行。\n\n探索和设计阶段会一次只问一个问题，并附上 StackPilot 的推荐答案；仓库能回答的问题会先读代码而不是问用户。终端设计决策默认给一个推荐方案；浏览器设计选项只用于视觉或交互比较。\n\n## 演示\n\n```\n> /stackpilot\n\n━━━━━━━━━━━━━━━━━━━━━━━━━\n  Stackpilot Sprint Status\n━━━━━━━━━━━━━━━━━━━━━━━━━\n  无活跃 sprint\n━━━━━━━━━━━━━━━━━━━━━━━━━\n\n你想构建什么功能？\n\n> 增加用户搜索，支持模糊匹配\n\nNode 1: 探索代码库...\nNode 2: 设计方案已在终端列出。跳过浏览器视图：这里文字更清楚。\nNode 3: 写入 spec → .stackpilot/specs/2026-04-05-user-search-design.md ✓\n        写入 criteria → .stackpilot/specs/2026-04-05-user-search-criteria.md ✓\n        终端评审：approve / changes: <text> / reverify\nNode 4: 写入 plan → .stackpilot/plans/2026-04-05-user-search-plan.md ✓\n        跳过实时 Dashboard：单个直接 wave\n\n计划就绪，开始编码？(Y/n)\n\n  ✅ TASK-001  设计搜索 API       架构审查 → 开发 → QA 通过  (1/3)\n  ✅ TASK-002  实现搜索接口       开发 → QA 通过              (2/3)\n  ✅ TASK-003  集成测试           开发 → QA 通过              (3/3)\n\nSprint 完成，所有测试通过。\nSprint evals 已写入：.stackpilot/runs/2026-04-05-user-search-plan/sprint-evals.md\nFeedback inbox：没有未解决的 HIGH/CRITICAL 项\nDev server 运行中：http://localhost:3000\n\nA. 合并到 main  B. 推送并创建 PR  C. 暂时保留  D. 丢弃\n```\n\n## 安装\n\nStackPilot 作为一个包安装，内部有两层：\n\n- **方法论门禁** — StackPilot route 使用的 portable Agent Skills，可在支持\n  Agent Skills 标准的宿主中复用。\n- **宿主适配器** — 用宿主原生工具实现同一套门禁；Claude Code 目前是完整自主\n  sprint adapter。\n\n| 宿主 | 当前支持 |\n|------|----------|\n| Claude Code | 完整 adapter + `.claude-plugin/` SessionStart 自动路由 |\n| Cursor | StackPilot routing bootstrap + `.cursor-plugin/` portable internal gates |\n| OpenAI Codex | StackPilot package metadata + `.codex-plugin/` portable internal gates |\n| Gemini CLI | StackPilot routing context + `gemini-extension.json` / `GEMINI.md` portable internal gates |\n\nClaude Code 一键安装：\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/9aoyang/stackpilot/main/install.sh | bash\n```\n\n或手动安装：\n\n```bash\ngit clone https://github.com/9aoyang/stackpilot.git ~/Documents/github/stackpilot\nbash ~/Documents/github/stackpilot/scripts/restore.sh\n```\n\n完整自主 sprint adapter 需要 git 和 Claude Code。方法论门禁可在 Agent Skills\n兼容宿主中使用；新增宿主适配器应该暴露一个 StackPilot 入口，并复用同一套 core\ngates，而不是 fork 一套流程。如果你使用 skillshare，应让 skillshare 成为共享\nskills 的唯一同步源。\n\nSkills 自动更新：`/stackpilot` 每天自动检查上游更新并拉取新 skills。\n\n## 配置\n\n`stackpilot.config.yml` 在首次运行 `/stackpilot` 时**自动生成**，会自动探测测试框架。\n\n```yaml\n# stackpilot.config.yml（自动生成）\nqa:\n  coverage_threshold: 80\n  test_command: npm test    # 根据项目文件自动探测\n```\n\n自动探测支持：Node.js、Python、Go、Rust、Ruby、Java/Kotlin、Elixir、PHP、.NET。\n\n## 架构文档\n\n完整系统设计见 [docs/architecture.zh.md](docs/architecture.zh.md)。\nSuperpowers workflow 覆盖审计见 [docs/superpowers-gap-audit.md](docs/superpowers-gap-audit.md)；\n它是 gap audit，不是要求 StackPilot 镜像 Superpowers 的 skill 数量或形态。\n\n核心设计：\n- **一个 StackPilot 入口** — 用户从 StackPilot 开始；内部门禁自动触发或按需触发\n- **方法论核心优先** — StackPilot 是通用方法论，不是单一宿主脚本\n- **宿主适配器** — Claude Code adapter 用 Agent tool + `isolation: \"worktree\"` 实现并行开发\n- **Agent Skills 标准** — core methodology skills 可在 30+ agent 产品中使用\n- **渐进式展开** — SKILL.md 精简（<500 行），重内容放 `references/`\n- **Plan/handoff 即持久层** — 运行时用 TaskCreate，跨会话用 plan、handoff、state、event 文件恢复\n- **数据层 handoff** — `handoff.json` 记录 phase/status/next action，保证恢复可靠\n- **Sprint evals** — `sprint-evals.md` 汇总 retry、plateau/stuck 信号、criteria 状态和建议\n- **Feedback inbox** — `.stackpilot/feedback/open|resolved` 让外部 audit feedback 贯穿 Finish\n\n## [贡献指南](CONTRIBUTING.md) | [许可证](LICENSE)\n",
  "bytes": 14722,
  "sha": "aad84859ab25475a3e83a06c47e6ef0669c17eb2641b83e8fd491b499b5e82e7",
  "repo_slug": "9aoyang/stackpilot",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_9aoyang_stackpilot_stackpilot_44249da4/readme"
}