# .agents Navigation

## 1. 目的
- 提供可复用的 Agent 资产目录与执行入口，确保任务从“路由 -> 门禁 -> 执行 -> 验证 -> 闭环”一致进行。

## 2. 适用场景
- 适用：在仓库内进行 feature/bugfix/refactor/exploration/market-discovery/digital-user-research 等任务。
- 不适用：与仓库执行流程无关的纯闲聊。

## 3. 输入
| 输入项 | 必填 | 说明 | 示例 |
|---|---|---|---|
| 用户任务描述 | 是 | 用于 workflow 路由 | “修复回归 bug” |
| 当前仓库上下文 | 是 | 分支、issue、规则、验证命令 | `git status` + rules |
| GitHub 鉴权（如需） | 条件必填 | API 操作读取环境变量 | `GITHUB_TOKEN` |

## 4. 步骤
1. 每次新输入先按 `/workspace/AGENTS.md` 完成意图路由并输出字段。
2. 执行 Issue First Gate，确认 workflow / issue / branch。
3. 加载 workflow stage 的 required skills（可叠加 recommended skills）。
4. 使用 assets 模板回填 issue/PR。
5. 执行最小验证命令后再提交。

## 5. 输出
| 输出物 | 格式 | 去向 |
|---|---|---|
| 路由结果（Matched Workflow/Match Reason/Fallback Used） | 文本/json | 会话上下文 |
| 规范 issue/PR 内容 | markdown | GitHub issue/PR |
| 验证记录与闭环结果 | 文本 | issue/PR 评论与提交记录 |

## 6. 约束
- 必须：先按 `AGENTS.md` 路由，再 Gate，再执行。
- 必须：GitHub 鉴权只从 `GITHUB_TOKEN` 读取。
- 禁止：Gate 未通过直接进入实现。
- 禁止：重复创建语义重叠的 workflow/skill 资产。

## 7. 验证
- [ ] 路由结果完整输出（Matched Workflow/Match Reason/Fallback Used）。
- [ ] Gate 状态明确（PASS/BLOCKED）。
- [ ] 最小验证命令已执行并记录。
- [ ] 闭环动作已完成（issue/PR/release/close）。

## Directory map
- `rules/`: Global constraints and review rules.
- `workflows/`: Task-type execution flows (`feature`, `bugfix`, `refactor`, `exploration`).
- `skills/`: Reusable capability packs invoked by task context.
- `commands/`: Lightweight command playbooks and gate checks.

### Standard subdirectories (for skills/workflows)
- `scripts/`: Executable code that agents can run.
- `references/`: Supplemental documents loaded on demand.
- `assets/`: Static resources such as templates, images, or data files.

## Quick selection guide
- New feature: workflow `feature-delivery` + skill `github-operator`.
- Bug fix: workflow `bugfix` + skill `github-operator`.
- Refactor: workflow `refactor` + skill `github-operator`.
- Research/spike: workflow `exploration` + skill `exploration-logger`.
- Market analysis/opportunity discovery: workflow `market-discovery` + skill `market-discovery`.
- Public-review user research/journey mapping: workflow `digital-user-research` + skill `digital-user-research`.
- Generic issue-tracking execution loop: workflow `issue-tracked-execution` + skill `github-operator`.
- Complex/unclear task: add skill `task-planner` first.
- PR description writing: add skill `pr-writer`.

## Naming conventions
- Branch: `<type>-<issue id>` or `cursor/<type>-<issue id>`.
- Commit: `type(scope): summary`.
