@geminix/gxpm 0.1.0

package/skills/gxpm-linear/SKILL.md.tmpl

@@ -0,0 +1,86 @@
+---
+name: gxpm-linear
+description: Linear CLI integration for gxpm issue lifecycle management. Use when creating, updating, or querying Linear issues, syncing gxpm issues to Linear, or managing issue lifecycle via command line.
+status: stable
+---
+
+# gxpm-linear
+
+Linear 协作前门，通过 CLI 与 issue tracker 交互。**不使用 MCP** — 所有操作走 `linear` 命令。
+
+## 入口条件
+
+- 需要创建/更新/查询 Linear issue
+- gxpm issue 需要同步到 Linear（`maybeSyncIssue` 的替代路径）
+- Sprint 规划、backlog 分类、批量操作
+- 需要读取 issue 评论获取上下文
+
+### 前置条件
+
+```bash
+# CLI 已安装在
+/opt/homebrew/bin/linear
+
+# 如不在 PATH
+export PATH="/opt/homebrew/bin:$PATH"
+```
+
+### 认证
+
+```bash
+linear auth login    # 首次使用或 token 过期
+linear config        # 查看默认 team/workspace
+```
+
+> **认证收敛**：gxpm 内置 issue-sync 直接调用 `linear` CLI，**不再单独配置 API key**。
+> 只需确保 `linear auth login` 已完成，gxpm 会自动复用其认证状态。
+> 旧配置 `sync.linearApiKey` 和 `GXPM_LINEAR_API_KEY` 已废弃，可安全移除。
+
+## 可操作流程
+
+{{REFERENCE:commands}}
+
+{{REFERENCE:workflows}}
+
+### 常用全局参数
+
+| Flag | 说明 |
+|------|------|
+| `--json` | 机器可读输出（默认使用） |
+| `--text` | 人类可读输出 |
+| `--dry-run` | 预览不执行 |
+| `--team <KEY>` | 指定 team（如 `GXG`） |
+
+### 操作原则
+
+1. **Issue 是单一真相源** — 所有需求、bug、变更都先落地 Linear issue
+2. **创建前先查重** — `linear issue list --query "keyword"` 避免重复
+3. **写操作需确认** — 批量操作先呈现表格，等用户点头再执行
+4. **状态完整性** — 子 issue 全 Done 才能关父 issue
+
+### Tips
+
+- `--json` 优先于 `--text`，方便脚本解析
+- `issue list` 默认只显示分配给当前用户的，加 `-A` 看全部
+- `issue list` 必须加 `--sort`（`manual` 或 `priority`）
+- GraphQL escape hatch: `linear api '{ issues { nodes { id title } } }'`
+
+## 红旗清单 / 反模式
+
+- **不使用 MCP** — 所有操作走 `linear` 命令，禁止通过 MCP 操作 Linear
+- 禁止绕过查重直接创建 issue
+- 禁止未确认就执行批量写操作
+- 禁止在子 issue 未完成时关闭父 issue
+- 不要混用旧 API key 认证方式（`sync.linearApiKey`、`GXPM_LINEAR_API_KEY` 已废弃）
+
+## 验证清单 / 出口条件
+
+- [ ] issue 创建/更新/查询结果与预期一致
+- [ ] 同步后的 gxpm issue 与 Linear issue 状态一致
+- [ ] 批量操作已获用户确认
+- [ ] `--json` 输出可被脚本正确解析（如需要）
+
+## Read Next
+
+- `docs/governance/development-contract.md`
+- Main `/gxpm` skill for phase gate details

package/skills/gxpm-linear/references/commands.md

@@ -0,0 +1,75 @@
+## CLI Commands
+
+### Issue Commands
+
+| Task | Command |
+|------|---------|
+| List my issues | `linear issue list --team GXG --sort priority --json` |
+| List all issues | `linear issue list --team GXG --all --sort priority --json` |
+| Filter by state | `linear issue list --team GXG --state todo --sort priority -A --json` |
+| Filter by project | `linear issue list --team GXG --project "Name" --sort priority -A --json` |
+| Search by text | `linear issue list --team GXG --query "keyword" --sort priority -A --json` |
+| View issue | `linear issue view GXG-123 --json` |
+| View with children | `linear issue children GXG-123 --json` |
+| Create issue | `linear issue create -t "Title" --team GXG --priority 2 --label feature --json` |
+| Create with parent | `linear issue create -t "Sub-task" --team GXG --parent GXG-123 --json` |
+| Create with desc file | `cat desc.md \| linear issue create -t "Title" --team GXG --json` |
+| Update state | `linear issue update GXG-123 --state "In Progress" --json` |
+| Move (shorthand) | `linear issue move GXG-123 "In Progress"` |
+| Update title | `linear issue update GXG-123 -t "New Title" --json` |
+| Set priority | `linear issue priority GXG-123 2` |
+| Assign | `linear issue assign GXG-123 self` |
+| Set estimate | `linear issue estimate GXG-123 3` |
+| Add comment | `linear issue comment add GXG-123 --body "text" --json` |
+| Batch create | `linear issue create-batch --json < batch.json` |
+| Dry-run preview | `linear issue create -t "Title" --team GXG --dry-run --json` |
+
+### Comment Subcommands
+
+| Task | Command |
+|------|---------|
+| Add comment | `linear issue comment add GXG-123 --body "text" --json` |
+| Update comment | `linear issue comment update <commentId> --body "text"` |
+| List/Delete comments | Use `linear api` GraphQL queries/mutations |
+
+**Note**: `linear issue comment list` and `linear issue comment delete` were **removed** in CLI v3.2.0. Use `linear api` for comment reads and deletes.
+
+### Issue Relations
+
+| Task | Command |
+|------|---------|
+| List relations | `linear issue relation list GXG-123 --json` |
+| Add relation | `linear issue relation add GXG-123 blocked-by GXG-456 --json` |
+| Delete relation | `linear issue relation delete <relationId>` |
+
+### Other Commands
+
+| Task | Command |
+|------|---------|
+| List teams | `linear team list --json` |
+| Team members | `linear user list --json` |
+| Workflow states | `linear workflow-state list --json` |
+| Labels | `linear label list --json` |
+| Current cycle | `linear cycle current --json` |
+| Next cycle | `linear cycle next --json` |
+| List cycles | `linear cycle list --json` |
+| List projects | `linear project list --json` |
+| View project | `linear project view <slug> --json` |
+| Create project | `linear project create --name "Name" --json` |
+| List milestones | `linear milestone list --json` |
+| List initiatives | `linear initiative list --json` |
+| List documents | `linear document list --json` |
+| List users | `linear user list --json` |
+| Notifications | `linear notification list --json` |
+| GraphQL escape hatch | `linear api '{ issues { nodes { id title } } }'` |
+
+### Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| Auth failure | Re-run `linear auth login` |
+| Rate limited | Batch operations, add delays |
+| "No team configured" | Add `--team GXG` or run `linear config` |
+| "Sort must be provided" | Add `--sort priority` to `issue list` |
+| CLI not found | Use full path `/Users/x/.nvm/versions/node/v25.8.0/bin/linear` |
+| Wrong workflow states | Query `linear workflow-state list --json` first |

package/skills/gxpm-linear/references/workflows.md

@@ -0,0 +1,120 @@
+## Workflows
+
+### Full Context = View + Comments
+
+`linear issue view` 只返回标题、描述、状态和元数据。**评论是独立 API 调用。**
+
+**规则**：接手 issue 时必须运行：
+```bash
+linear issue view GXG-123 --json
+```
+Comments require a GraphQL query via `linear api` (CLI v3.2.0 removed `issue comment list`).
+
+评论中可能包含 scope 定义、设计决策、PoC 结果、review 反馈、跨 agent 交接上下文。仅在批量 list/triage 时可跳过评论阅读。
+
+### Creating an Issue
+
+1. 搜索重复：`linear issue list --team GXG --query "keyword" --all --sort priority --json`
+2. 检测当前 git branch：`git branch --show-current`
+3. 起草 issue（标题、描述、标签、项目、团队、负责人、优先级）
+4. 呈现给用户确认
+5. 执行：
+   ```bash
+   linear issue create \
+     -t "[Domain] Clear description" \
+     --team GXG \
+     --priority 2 \
+     --label feature --label backend \
+     --json
+   ```
+6. 报告 issue identifier 和链接
+
+### Implementing a Linear Issue
+
+1. 获取完整上下文（view + comments）
+2. 移到 Todo：`linear issue update GXG-123 --state "Todo" --json`
+3. 读取 acceptance criteria 和依赖
+4. 创建 feature branch（命名含 issue ID）
+5. TDD 实现
+6. 完成后移到 In Review：`linear issue update GXG-123 --state "In Review" --json`
+7. 添加 completion comment：
+   ```bash
+   BRANCH=$(git branch --show-current)
+   linear issue comment add GXG-123 --body "## Completion Summary
+   **Branch:** \`$BRANCH\`
+   **PR:** <pr-url-or-pending>
+   **Summary:** <what was done>" --json
+   ```
+
+### Bulk Operations
+
+3+ issue 的批量操作：
+1. 收集所有目标 issue
+2. 以表格呈现：Issue ID、Current State、Proposed Change、Reason
+3. 加 `--dry-run` 预览
+4. 等用户确认后执行
+5. 报告摘要：N succeeded, N failed
+
+### Sub-Issue Management
+
+子 issue 继承父 issue：
+- 相同 project 和 team
+- 相同标签（除非有理由覆盖）
+- 通过 parent 关系链接
+
+```bash
+# 创建子 issue
+linear issue create -t "Sub-task title" --team GXG --parent GXG-123 --json
+# 或给已有 issue 设置 parent
+linear issue update GXG-456 --parent GXG-123 --json
+```
+
+### Sprint Planning
+
+1. 收集当前状态：
+   ```bash
+   linear cycle current --json
+   linear cycle next --json
+   linear issue list --team GXG --state backlog --sort priority -A --json
+   linear user list --json
+   ```
+2. 分析：按优先级排序（P0 bugs > blockers > high-value features > tech debt）
+3. 以表格呈现计划：issue、priority、assignee、estimate、rationale
+4. 确认后批量分配到 cycle
+
+### Backlog Triage
+
+1. 拉取未分类项：
+   ```bash
+   linear issue list --team GXG --state triage --sort priority -A --json
+   linear issue list --team GXG --state backlog --sort priority -A --json
+   ```
+2. 对每个 issue 推荐：priority、labels、assignee、cycle placement
+3. 以表格呈现 triage 计划
+4. 确认后执行
+5. 标记 stale issue（3+ cycles 无活动）— 先提醒用户 review
+
+### Status Integrity
+
+- 永远不要硬编码 state 名称，先查：
+  ```bash
+  linear workflow-state list --json
+  ```
+- 关父 issue 前先查子 issue：
+  ```bash
+  linear issue children GXG-123 --json
+  ```
+- 任何子 issue 未 Done 都不能关父 issue
+
+### Label Taxonomy
+
+应用标签前先确认存在：
+```bash
+linear label list --json
+```
+
+| Category | Labels | Rule |
+|----------|--------|------|
+| **Type** | `feature`, `bug`, `chore`, `tech-debt`, `spike` | 恰好一个 |
+| **Domain** | `frontend`, `backend`, `infra`, `design`, `security`, `testing` | 1-2 个 |
+| **Workflow** | `blocked`, `in-review`, `needs-design`, `needs-split` | 按需 |

package/skills/gxpm-planning/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: gxpm-planning
+description: Break plans into independently-grabbable issues using vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, break down a feature, or turn discussion into a structured PRD.
+---
+
+# Planning
+
+Break any plan into independently-grabbable issues using **tracer-bullet vertical slices**.
+
+## 入口条件
+
+**何时触发**
+- 用户想将计划转化为 issues。
+- 用户要求创建 implementation tickets。
+- 用户需要拆分 feature 为可执行单元。
+- 用户希望将讨论转化为结构化 PRD。
+- `plan` 阶段中 `implementation-plan` 过大，需要拆分为子 issue。
+
+**前置条件**
+- 已有计划、spec、或 PRD；或可从当前对话上下文中合成。
+
+**Skill 边界（什么情况下应该加载别的 skill）**
+- 需求或术语尚未澄清 → `/gxpm-grill`
+- 架构决策需要分析 → `/gxpm-architecture`
+- 具体代码实现 → `/gxpm-implementer`
+- Issue 分类与状态路由 → `/gxpm-triage`
+
+## 可操作流程
+
+### 垂直切片规则
+
+- Each slice delivers a narrow but **COMPLETE** path through every layer (schema, API, UI, tests).
+- A completed slice is demoable or verifiable on its own.
+- Prefer many thin slices over few thick ones.
+
+### Slices may be HITL or AFK
+
+- **HITL** — requires human interaction (architectural decision, design review).
+- **AFK** — can be implemented and merged without human interaction.
+- Prefer AFK over HITL where possible.
+
+### Process
+
+1. **Gather context** — read the plan, spec, or PRD. Fetch from the issue tracker if referenced.
+2. **Explore codebase** (optional) — understand current state to inform slice titles.
+3. **Draft vertical slices** — break into end-to-end slices, NOT horizontal layers.
+4. **Quiz the user** — present as numbered list with:
+   - Title
+   - Type (HITL / AFK)
+   - Blocked by (dependencies)
+   - User stories covered
+5. **Iterate** until user approves granularity and dependencies.
+6. **Publish** — create issues in dependency order (blockers first). Apply `needs-triage` label.
+
+### Issue body template
+
+```markdown
+## Parent
+Reference to parent issue (if applicable).
+
+## What to build
+Concise description of this vertical slice. Describe end-to-end behavior, not layer-by-layer implementation.
+
+## Acceptance criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Blocked by
+- Reference to blocking ticket, or "None — can start immediately"
+```
+
+### To PRD: Synthesize from Context
+
+Turn the current conversation context into a PRD. Do NOT interview the user — synthesize what you already know.
+
+#### PRD Template
+
+```markdown
+## Problem Statement
+The problem from the user's perspective.
+
+## Solution
+The solution from the user's perspective.
+
+## User Stories
+1. As an <actor>, I want a <feature>, so that <benefit>
+(Extensive list covering all aspects.)
+
+## Implementation Decisions
+- Modules to build/modify
+- Interfaces to modify
+- Schema changes
+- API contracts
+
+## Testing Decisions
+- What makes a good test (behavior, not implementation)
+- Which modules to test
+
+## Out of Scope
+Explicitly excluded items.
+
+## Further Notes
+Any additional notes.
+```
+
+### gxpm integration
+
+- During `plan`, if the `implementation-plan` is too large, use `/planning` to suggest vertical slices as sub-issues.
+- Each sub-issue should be created with `gxpm issue create --auto-id`.
+- The parent issue's `implementation-plan` should reference child issue IDs.
+- For PRD synthesis, publish the PRD as a new issue with `gxpm issue create --auto-id` and label it `needs-triage`.
+
+## 红旗清单 / 反模式
+
+- **STOP：禁止水平层拆分。** 不要按 schema → API → UI → tests 分层拆 issue；必须是端到端垂直切片。
+- **STOP：禁止跳过用户确认直接发布 issue。** 必须在用户批准粒度和依赖后再 publish。
+- **STOP：禁止遗漏 blocked by 依赖声明。** 每个 slice 必须注明依赖或标记为无依赖。
+- **STOP：禁止 thick slice。** 宁要多个薄切片，不要少数厚切片。
+- **危险信号：** Issue body 描述的是层-by-layer 实现而非端到端行为 → 重写为垂直切片描述。
+- **危险信号：** 子 issue 创建后父 issue 未引用子 issue IDs → 补全引用。
+
+## 验证清单 / 出口条件
+
+- [ ] 每个 slice 有明确 Title、Type（HITL/AFK）、Blocked by、覆盖的 User Stories。
+- [ ] 用户已批准粒度和依赖关系。
+- [ ] Issues 已按依赖顺序创建（blockers 优先）。
+- [ ] 每个新 issue 已应用 `needs-triage` label。
+- [ ] PRD 包含所有必需章节（Problem Statement、Solution、User Stories、Implementation Decisions、Testing Decisions、Out of Scope）。
+- [ ] 父 issue 的 `implementation-plan` 引用了所有子 issue IDs。
+
+**失败时路由**
+- 需求仍不清晰 → `/gxpm-grill`
+- 实现计划仍需进一步拆分 → 重新执行 Planning Process
+- 架构决策受阻 → `/gxpm-architecture`

package/skills/gxpm-prototype/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gxpm-prototype
+description: Build a throwaway prototype to validate a design before committing to it. Use when you need to sanity-check a data model, state machine, or UI design before writing behavior-spec.
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+## 入口条件
+
+**何时触发**
+- 用户说 "prototype this"、"let me play with it"、"try a few designs"。
+- 在 `specify` 阶段之前，需要快速验证数据模型或状态机设计。
+- 不确定 UI 方向，想先探索几种 radically different 的变体。
+- 业务逻辑分支复杂，难以在纸上推理清楚。
+
+**Skill 边界（什么情况下应该加载别的 skill）**
+- 需求/范围尚未澄清 → `/gxpm-grill`
+- 需要正式的 BDD 行为规约 → `/gxpm-specifier`
+- 需要架构层面的模块设计 → `/gxpm-architecture`
+- 已经确认设计，需要实现 → `/gxpm-tdd`
+
+## 可操作流程
+
+### Pick a branch
+
+Identify which question is being answered:
+
+- **"Does this logic / state model feel right?"** → Logic prototype. Build a tiny interactive terminal app that pushes the state machine through cases hard to reason about on paper.
+- **"What should this look like?"** → UI prototype. Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+
+The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (backend module → logic; page or component → UI) and state the assumption at the top of the prototype.
+
+### Rules that apply to both
+
+1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used so context is obvious — but name it so a casual reader can see it's a prototype, not production.
+2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast and then delete it.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
+6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo.
+
+## 红旗清单 / 反模式
+
+- **STOP：不要把原型当作生产代码。** 没有测试、没有错误处理、没有抽象 — 这些是故意的，不是 TODO。
+- **STOP：不要在原型中追求完美。** 30 分钟能回答的问题不要花 3 小时。
+- **STOP：不要把原型留在仓库里腐烂。** 回答完问题后要么删除，要么把验证过的决策吸收进正式代码。
+- **STOP：不要为原型写 behavior-spec。** 原型在 specify 之前，不需要 BDD 规约。
+- **危险信号：** 原型代码被 copy-paste 到正式实现 → 这是有意外的技术债务，应重新实现。
+- **危险信号：** 原型运行需要复杂的 setup → 简化它，否则学习成本太高。
+
+## 验证清单 / 出口条件
+
+- [ ] 回答了预先定义的 question（logic feel right? or what should it look like?）。
+- [ ] 代码明确标记为 PROTOTYPE / throwaway。
+- [ ] 用户（或代理自己）能够运行并观察状态变化。
+- [ ] 决策已记录（commit message、ADR、issue comment、或 NOTES.md）。
+- [ ] 原型已删除，或关键决策已吸收进正式代码。
+
+**失败时路由**
+- 原型验证后需求仍不清晰 → `/gxpm-grill`
+- 原型验证后需要正式规约 → `/gxpm-specifier`
+- 原型暴露架构问题 → `/gxpm-architecture`

package/skills/gxpm-refactor-safely/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: gxpm-refactor-safely
+description: Plan and execute safe refactoring using dependency analysis. Use when user asks to rename, extract, split, move, or simplify code, or when a code review suggests refactoring.
+---
+
+## gxpm-refactor-safely
+
+### 入口条件
+
+**Skill boundary:**
+- If you do **not yet understand** the target code, load `/gxpm-explore-codebase` first.
+- If you discover a **bug** during refactoring, stop refactoring and load `/gxpm-diagnose` or `/gxpm-debug-issue`.
+- If you need to **rename or move** symbols across the codebase, confirm the `rename` tool is available in your GitNexus MCP; otherwise use manual renaming with `detect_changes` validation.
+
+Use GitNexus to plan and execute refactoring with confidence. When simplifying code, follow the scan-checklist-incremental-verify loop below.
+
+### 可操作流程
+
+1. **Understand** — Use `impact` with `direction: "upstream"`, `query`, and `context` to understand the target code, its callers, edge cases, and test coverage before touching it.
+2. **Scan for simplification opportunities** (checklist):
+   - **Deep nesting (>3 levels)** → guard clauses or extracted helpers
+   - **Long functions (>50 lines or >1 responsibility)** → split by responsibility
+   - **Nested ternaries** → if/else, early-return, or switch
+   - **Generic names** (`data`, `tmp`, `x`) → descriptive names
+   - **Duplicated logic (same pattern ≥2 times)** → shared function or constant
+   - **Dead code** (unused imports, unreachable branches, stale comments) → remove after confirming with `impact`/`context`
+3. **For renames**, use `rename` with `dry_run: true` to preview all affected locations.
+4. **Apply each simplification incrementally** — run tests after **every** narrow edit:
+   - Use the project's test command (e.g. `bun test`, `npm test`).
+   - If tests fail, **revert that change immediately** and reconsider.
+   - Only proceed to the next simplification when the current one is green.
+5. **After all changes**, run `detect_changes` to verify the refactoring impact, ensure the build succeeds, and keep the diff clean.
+
+### 红旗清单 / 反模式
+
+**Safety Checks**
+- Always preview before applying (rename mode gives you an edit list).
+- Check `impact` before major refactors.
+- Use `detect_changes` to ensure affected flows are expected.
+- Use `cypher` only for custom graph questions that `query`/`context` cannot answer.
+
+**Protected Blocks**
+
+Some code must not be simplified even if it looks complex. Respect block-level protection annotations in any language:
+
+```js
+/* gxpm-simplify-ignore-start: perf-critical */
+// manually unrolled XOR — 3x faster than a loop
+result[0] = buf[0] ^ key[0];
+result[1] = buf[1] ^ key[1];
+/* gxpm-simplify-ignore-end */
+```
+
+Supported comment styles: `//`, `/* */`, `#`, `<!-- -->`. The `reason` field is optional but recommended. Never modify, rename, or delete code inside a protected block.
+
+- Start with the narrowest GitNexus query or impact target, then expand.
+- Prefer dry-run previews for coordinated renames.
+
+### 验证清单 / 出口条件
+
+- run `detect_changes` to verify the refactoring impact, ensure the build succeeds, and keep the diff clean.
+- Target: complete any review/debug/refactor task in ≤5 graph tool calls.

package/skills/gxpm-review-army/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: gxpm-review-army
+description: Agent Army 并行审查模式的使用指南。在 self-review 和 ship 阶段通过多角色并行扇出提升审查质量。
+status: stable
+---
+
+# gxpm-review-army
+
+在 gxpm 的 `self-review` 和 `ship` 阶段使用 Agent Army 并行审查模式，替代单一 reviewer 视角，显著提升审查覆盖面和问题发现率。
+
+## 入口条件
+
+- issue 已进入 `self-review` 或 `ship` 阶段
+- 需要比单一 reviewer 更全面的多维度审查
+- 变更涉及安全敏感、性能敏感或可访问性相关代码
+
+## 可操作流程
+
+### 在 self-review 阶段启用 Review Army
+
+```bash
+gxpm self-review cleanup <issue-id> --army
+```
+
+这会同时创建：
+- `self-review.json` — 原有单一 reviewer 的审查记录
+- `review-report.json` — Review Army 的并行审查报告（初始为 draft，待各角色填充 findings）
+
+### Review Army 角色构成
+
+| 角色 | 职责 | 触发条件 |
+|------|------|----------|
+| **Spec Compliance Reviewer** | 验收标准符合性 | 所有变更 |
+| **Code Quality Reviewer** | 代码质量与可维护性 | 所有变更 |
+| **Security Reviewer** | 安全漏洞与敏感数据 | 涉及外部输入、权限、依赖的变更 |
+| **Test Reviewer** | 测试覆盖与质量 | 所有变更 |
+| **Accessibility Reviewer** | 可访问性 | 涉及 UI 的变更 |
+
+### 在 ship 阶段启用 Ship Audit Army
+
+```bash
+gxpm ship pr-check <issue-id> --army
+```
+
+这会同时创建：
+- `ship-readiness.json` — 原有 ship readiness 检查清单
+- `ship-audit-report.json` — Ship Audit Army 的专项审计报告
+
+### Ship Audit Army 角色构成
+
+| 角色 | 职责 |
+|------|------|
+| **Security Auditor** | 发布前安全专项审计 |
+| **Performance Auditor** | 发布前性能影响评估 |
+| **Docs Auditor** | 文档同步性检查 |
+
+### Review Report 格式
+
+```json
+{
+  "army": "review-army",
+  "phase": "self-review",
+  "findings": [
+    {
+      "role": "security-reviewer",
+      "severity": "blocking",
+      "location": "core/auth.ts:42",
+      "rationale": "外部输入直接进入文件路径拼接，存在路径遍历风险",
+      "recommendation": "使用 path.resolve 并限制在允许目录内，或改用 UUID 映射"
+    }
+  ]
+}
+```
+
+### Severity 分级
+
+| 级别 | 含义 | 对 gate 的影响 |
+|------|------|----------------|
+| **blocking** | 必须修复后才能进入下一阶段 | 阻止 phase transition |
+| **important** | 强烈建议修复，但可在后续迭代处理 | 不阻止，但需记录 |
+| **suggestion** | 可选改进，供参考 | 不阻止 |
+
+### 与单一 reviewer 的协同
+
+- **无 `--army` 标志时**：完全保持原有单一 reviewer 流程，无任何变化
+- **有 `--army` 标志时**：Army 审查与单一 reviewer 并行产出，review-report 作为额外输入
+- 单一 reviewer 负责**综合判断**和**合并建议**，Army 角色提供**专业视角**
+
+## 红旗清单 / HARD-GATE
+
+- **Review Army 产出的 blocking finding 未解决就推进到 ship** → 必须 STOP，回到 self-review 修复
+- **在 ship 阶段发现 security auditor 的 blocking 问题** → 必须 STOP，回退到 implement 修复后重新走 review
+- **为赶时间跳过 Accessibility Reviewer** → 可访问性是法律责任，不可跳过
+- **混淆 important 和 blocking 的优先级** → 只有 blocking 会阻止 gate，但 important 需在 ship notes 中说明计划
+
+## 验证清单
+
+- [ ] `--army` 标志正确传递，review-report 或 ship-audit-report 已创建
+- [ ] 每个 Army 角色的 findings 已填入报告
+- [ ] blocking 问题数为 0 或已在 ship notes 中说明豁免理由
+- [ ] 所有 finding 包含完整的 location、rationale、recommendation
+- [ ] 单一 reviewer 的 self-review.json 仍正常产出（向后兼容）
+
+## 常见说辞表
+
+| 说辞 | 现实 | 正确做法 |
+|------|------|----------|
+| "Army 审查太慢，我直接用单一 reviewer" | 5 个角色并行执行，实际时间不比串行慢 | 使用 `--army`，让专业角色并行工作 |
+| "这些 finding 都是 suggestion，不重要" | suggestion 累计反映设计问题 | 关注 suggestion 的模式，而非单个 |
+| "Security Reviewer 太严格了" | 安全漏洞的修复成本随阶段指数增长 | 在 self-review 阶段解决，不要留到 ship |
+| "Accessibility 可以后续补" | 可访问性缺陷在发布后再修复成本 10x | 在 implement 阶段就通过 Accessibility Reviewer 检查 |
+
+## Read Next
+
+- `agents/reviewer.md` — 单一 reviewer 的协同说明
+- `core/agent-runtime.ts` — Agent Runtime 技术细节
+- `docs/governance/gherkin-style.md` — behavior-spec 写作规范