# AppGenesisForge

> **Template Version: v3.0.0** (2026-05-03) — Agent prefix rollback. Agent definitions revert to bare names (`product-lead`, `backend-dev`, …) after real-world Agent Teams runs showed the `agf-` prefix on agent `name:` field caused inter-teammate `SendMessage` routing issues. Project skills (`agf-writing-prd`, …) and slash commands (`/agf-team-start`, …) **keep** the `agf-` prefix — they have no routing impact and the prefix still helps namespace-isolate from built-ins / plugins. See `CHANGELOG.md` for the v2 → v3 migration map.

## Project Overview

AI 应用开发项目，前端 Web、后端服务、AI Agent 三方向并行。

**当前仓库形态**：AI 团队协作模板（脚手架）——`.claude/` 团队配置与 `docs/` 规范就绪，Tech Stack 已落地（见 ADR-000）；尚无应用代码，等待执行层在首个 feature 启动时创建 `backend/` 与 `frontend/`。

## Tech Stack

技术栈**详尽决策**（备选、理由、版本查证）唯一来源是 [`docs/adr/000-system-architecture.md`](docs/adr/000-system-architecture.md)。本文件 `## Tech Stack` 仅放当前生效版本号摘要 + ADR 链接，不重复决策理由。

**当前摘要**：React + Vite、FastAPI + PostgreSQL、SQLAlchemy + Alembic、DeepSeek/Doubao/Qwen/MiniMax 多 LLM、docker-compose 仅编排 Postgres。详见 ADR-000。

**任何技术栈调整必须新开 ADR**（由 `tech-lead` 撰写）+ 同步更新本段摘要的版本号 / 链接，不在本文件重复决策理由。

## Project-Specific Rules

- 本文件只放项目特有规则，团队通用规则统一放在 `.claude/standards/`，结构性指引在 `.claude/rules/`。
- 项目涉及外部合规、部署约束、第三方集成限制时，在此处追加。
- 设计交付物路径约定：`docs/design/[feature]/spec.md`（设计规范）+ `docs/design/[feature]/index.html`（自包含静态原型，Tailwind CDN 或内联样式，可直接 `open` 打开），资源放 `assets/`。
- 修改 `.claude/agents/*.md` 的职责或产出时，必须同步检查 `docs/team-capability-map.md`（"主要输出"列）与 `.claude/standards/team-roles.md`（仅当工具/skill/推荐 mode 变更时）。
- 涉及多 LLM SDK 接入（DeepSeek/Doubao/Qwen/MiniMax 切换、fallback、env 变量）→ 必须先看 skill `.claude/skills/agf-wiring-multi-llm-sdk/`。
- SIT 测试由 execution-layer dev 自跑（不是独立 phase）→ 必须按 skill `.claude/skills/agf-running-sit-tests/` 流程；证据落到 `progress/<role>.md` 的 `**SIT 证据**` 段，由 `code-reviewer` 在 code review 时 audit（参见 `.claude/agents/code-reviewer.md` `## SIT Audit` 节）。
- 写 E2E / UAT 报告 → skill `.claude/skills/agf-writing-qa-report/`（v2.0.0 rename，原 `agf-writing-sit-report`，SIT 不再覆盖）。
- 写 PRD → skill `agf-writing-prd`；写 ADR → skill `agf-writing-adr`。
- 程序化生成中文 docx 报告（决议书 / 评审 / 投标书等高密度文档）→ skill `agf-writing-docx-reports`（docx-js）；程序化生成中文 pptx（制度 / 党政 / 宣贯 deck）→ skill `agf-writing-pptx-reports`（python-pptx）。两者依赖 `.claude/skills/docx/` 与 `.claude/skills/pptx/`（Anthropic 第三方低层 skill，附带 `scripts/office/soffice.py` 做 PDF 预览闭环）。
- Release 推 tag + `gh release create` 完成后（仅 MAJOR / MINOR）→ 必须 `/agf-release-retro vX.Y.Z` 触发，按 skill `.claude/skills/agf-running-release-retro/` 完成复盘，产物归档到 `docs/reviews/retro-vX.Y.Z-YYYY-MM-DD.md`；PATCH 跳过。
- 实施计划（派工前用 `superpowers:writing-plans` 生成）必须轻量化 —— 参见 `.claude/standards/plans-format.md`（无 inline 代码、无逐 step commit、每 Task ≤ 3 步、整个 Plan ≤ 500 字）。
- 仓库目录约定见 `.claude/rules/repo-layout.md`；Team Mode 启动协议见 `.claude/rules/team-mode.md`（按 path 自动加载）。

## Tool Boundaries

四层 hook 防御（注册位置：`.claude/settings.json` + `.git/hooks/pre-commit`，文档：`.claude/standards/security.md`）：

1. **`PreToolUse` (Bash) — `block-dangerous-bash.sh`**：硬阻断 `rm -rf` / `DROP TABLE` / `git push --force` / `git reset --hard`。
2. **`UserPromptSubmit` — `scan-secrets.sh`**：硬阻断 AWS/GitHub/OpenAI/Anthropic/Google/Slack/DeepSeek/Doubao/Qwen/MiniMax 密钥 + PEM/SSH/PuTTY 私钥 + BIP39 助记词。
3. **`PostToolUse` (WebFetch/WebSearch/Read/Bash) — `sanitize-tool-output.sh`**：软告警外部内容里的 prompt-injection 指令。
4. **`pre-commit` (git) — `scan-commit.sh`**：commit 前对 staged diff 跑同套 secret 正则，防 Edit/Write 绕过 prompt 扫描。安装：`ln -sf ../../.claude/hooks/scan-commit.sh .git/hooks/pre-commit`。

`.claude/settings.json` 的 `permissions.deny` 已禁读 `.env*`、`~/.ssh/**`、`~/.aws/**`、`~/.gnupg/**` 等敏感路径，并禁 `curl|sh` / `eval` 等远程执行链路。

附加 workflow hooks（**不属于安全防御**，仅维护团队工作流）：

5. **`TeammateIdle` — `teammate-keepalive.sh`**：task list 还有 pending 时阻止 teammate 提前 idle。
6. **`UserPromptSubmit` — `skill-suggester.sh`**：按 `.claude/hooks/skill-rules.json` 软建议相关 skill / 命令；不阻断。
7. **`SubagentStop` / `TeammateIdle` — `check-progress-file.sh`**：执行层 role 退出时若 `progress/<role>.md` 缺 SIT 证据段则阻断（v2.0.0+ 兜底）。
8. **`PreToolUse` (TaskCreate) — `validate-task-schema.sh`**：派单前校验 task 6 段齐全（description / 上下游产物 / AC 等），漏字段阻断。

撞到硬阻断时按 `.claude/standards/security.md` "No Equivalent Bypass" 处理（不得寻找等价绕过）。

## Team Runtime Contract

本项目复用 `.claude/` 中的 AI 团队模板。权威来源：
- 角色与协作边界：`.claude/standards/team-roles.md`
- 工作流（含 Parallel Dispatch + worktree 强制）：`.claude/standards/workflow.md`
- 文档与单一来源原则：`.claude/standards/document-rules.md`
- Superpowers 使用规范：`.claude/standards/superpowers.md`
- 测试与验收：`.claude/standards/testing.md`、`.claude/standards/ac-lifecycle.md`
- 编码与安全：`.claude/standards/coding.md`、`.claude/standards/security.md`
- 观测与成本：`.claude/standards/observability.md`、`.claude/standards/cost-budget.md`
- 版本与发布：`.claude/standards/versioning.md`（SemVer 应用细则 + release 流程）
- 对话回复风格：`.claude/standards/communication.md`（所有 agent 面向人的回复精简，docs 产出物不受影响）

运行时关键约束（摘要，细则以权威来源为准）：

- `.claude/standards/team-roles.md` 是角色额外工具与预加载 skills 的唯一团队级能力基线；表中 `Permission` 列是**团队约定的"推荐运行模式"**，并非 Claude Code 官方 sub-agent frontmatter 字段。
- `product-lead` 是唯一流程编排者；`tech-lead` 仅在缺少基线、新技术选型或架构风险升级时强制介入。
- 会话入口判断（直接执行 vs 派给 `product-lead`）见 `.claude/standards/workflow.md` "Session Entry" 节。
- Team Mode 启动条件与协议见 `.claude/rules/team-mode.md`（path 命中 `.claude/agents/**` 等时自动加载）。
- 交付链路固定为 `代码实现 + Unit + SIT 自跑 → code review (含 SIT Audit) → E2E → UAT`；任一阶段失败后，由 `product-lead` 重新分派执行层修复。
- `code-reviewer` 为 review-only 角色；`qa-engineer` 负责执行 E2E / UAT 并提交报告（集成层 SIT 由 dev 自跑、code-reviewer 审证据），最终业务签字由 `product-lead` 完成。
- `backend-dev` / `ai-agent-dev` 在高风险变更（schema 迁移、认证逻辑、LLM 提供商切换、生产 prompt 变更等）必须先进 Plan Mode 拿 product-lead 授权。
- token 消耗与成本按 `.claude/standards/cost-budget.md` 分级（含会话规模上限、cache 利用率 ≥ 60% 与 14 agent 默认 model 路由）；如需查看本次会话用量，跑 Claude Code 内置 `/usage`。
- 对话回复一律按 `.claude/standards/communication.md` 执行；写入 `docs/` 的产出物不压缩。

若本文件中的项目规则与团队规范冲突，以本文件为准。
