agent-project-sdlc 0.1.0

package/assets/README.md

@@ -0,0 +1,5 @@
+# Canonical Assets
+
+This directory stores package canonical assets that `sdlc-harness sync` will materialize into project workspaces.
+
+In this source repository, assets should be updated through `sdlc-harness package sync-source` so changes to the workflow authoring files do not drift from package contents.

package/assets/agents/.gitkeep

@@ -0,0 +1 @@
+

package/assets/agents/AGENTS_CORE.md

@@ -0,0 +1,164 @@
+# AI SDLC Harness Protocol
+
+本仓库使用 AI SDLC Harness 工作流。开始任何工作前，把 `.agent/` 和 `.docs/`
+视为项目事实源。
+
+## 事实源
+
+- 生命周期状态：`.agent/state/lifecycle.yaml`
+- 执行计划：`.agent/state/plan.yaml`
+- 计划草案：`.agent/state/plan.draft.yaml`
+- 项目长期记忆：`.agent/state/memory.md`
+- 产品文档：`.docs/01_product/`
+- 架构文档：`.docs/02_architecture/`
+- 技术方案：`.docs/03_tech_plan/`
+- 实现文档：`.docs/04_implementation/`
+- Review 文档：`.docs/06_review/`
+- 测试文档：`.docs/07_test/`
+- 发布文档：`.docs/08_release/`
+- RFC 文档：`.docs/rfc/`
+- 全局文档索引：`.docs/INDEX.md`
+
+## 派生视图
+
+- 每个 `.docs/<stage>/overview.md` 是对应阶段 Markdown slices 的 generated artifact。
+- Markdown slices 和 `.docs/INDEX.md` 才是事实源，`overview.md` 只用于人类浏览和阶段交接。
+- 不要手写或局部编辑 `overview.md`。
+- 任意 `.docs/<stage>/**/*.md` 发生新增、修改、拆分、合并或废弃后，运行 `make docs-overview`。
+- 提交或阶段交付前，运行 `make validate-doc-overviews` 或 `make validate-harness` 确认 Markdown 总览未过期。
+
+## Plan Protocol
+
+- `plan.yaml` 是当前执行计划事实源。open task 直接包含 `allowed_paths`、`required_gates`、`acceptance_criteria` 和必要的 `working_notes`。
+- task 完成并写入 implementation doc 后，删除 open task 的详细执行字段，只保留简短 `summary`、`implementation_doc` 和 `gate_result`。
+- `plan.draft.yaml` 是架构阶段生成的计划草案，不自动覆盖 `plan.yaml`。
+- 不维护 checkpoint 文件；任务现场只存在于 open task 的 plan 条目里。
+- 历史动作记录以 git commit 为准，产物结果以 implementation doc 为准。
+- `SPRINTING` 阶段每完成一个 task，先在 open task 仍保留完整 `allowed_paths`、`required_gates`、`acceptance_criteria` 等执行合同时创建 task implementation commit；随后再压缩 `plan.yaml` 为 done 摘要并创建 task completion ledger commit。两段提交 push 成功前不进入下一个 task。
+
+## Prompt Language Contract
+
+- 面向人阅读的说明、规则、SOP、检查清单使用中文。
+- 机器契约保持英文，包括字段名、路径、命令、阶段枚举、状态枚举、脚本参数。
+- 不翻译 `.agent/state/*.yaml`、`.agent/managed/policies/*.yaml` 中的 key。
+- 不翻译 `current_phase`、`active_skill`、`allowed_paths`、`required_gates`、`implementation_doc` 等字段名。
+- 不翻译 `REQUIREMENT_GATHERING`、`ARCHITECTING`、`SPRINTING`、`REVIEWING`、`TESTING`、`RELEASING`、`RFC_RECALIBRATION`、`BLOCKED` 等阶段枚举。
+- 不翻译 `pending`、`in_progress`、`done`、`blocked`、`pending_revision`、`cancelled` 等任务状态。
+- 不翻译 `make validate-*`、`python3 tools/transition.py --to <PHASE>`、`.docs/01_product/`、`.agent/state/plan.yaml` 等命令和路径。
+- 后续更新 `.agent/skills/*/SKILL.md` 或 `.agent/managed/templates/*.md` 时，遵循“中文解释 + 英文精确标识符”。Harness 根目录由 `package.json#sdlcHarness.harnessFolderName` 或 `sdlc-harness.config.json#harnessFolderName` 决定；未配置的项目默认使用 `.agent`。
+
+## 通用执行原则
+
+以下原则完整迁移自 `multica-ai/andrej-karpathy-skills` 的 MIT guideline，并按本仓库的 Prompt Language Contract 转为“中文说明 + 英文关键词”形式，与阶段化 Harness 协议合并执行。
+
+### Karpathy Guidelines（MIT 完整本地化）
+
+这些 behavioral guidelines 用来减少常见的 LLM coding mistakes，并可与项目级 instructions 合并使用。
+
+**Tradeoff:** 这些 guidelines 更偏向 caution over speed。对于 trivial tasks，可以使用 judgment。
+
+## 1. Think Before Coding
+
+**不要 assume，不要 hide confusion，要 surface tradeoffs。**
+
+Before implementing:
+- 显式说明你的 assumptions。如果 uncertain，先 ask。
+- 如果存在多种 interpretations，要把它们列出来，不要 silently pick。
+- 如果存在 simpler approach，要说出来。必要时要 push back。
+- 如果某件事 unclear，先 stop，说明 confusing 的点，再 ask。
+
+## 2. Simplicity First
+
+**用 minimum code 解决问题，不做 speculative work。**
+
+- 不添加超出用户请求的 features。
+- 不为 single-use code 添加 abstractions。
+- 不添加未被请求的 `flexibility` 或 `configurability`。
+- 不为 impossible scenarios 添加 error handling。
+- 如果你写了 200 行，而它本可以是 50 行，就 rewrite it。
+
+Ask yourself: “Would a senior engineer say this is overcomplicated?” 如果答案是 yes，就 simplify。
+
+## 3. Surgical Changes
+
+**只 touch 必须修改的内容，只 clean up your own mess。**
+
+When editing existing code:
+- 不要“顺手 improve”相邻代码、comments 或 formatting。
+- 不要 refactor 没有 broken 的东西。
+- Match existing style，即使你个人会用不同写法。
+- 如果发现 unrelated dead code，只 mention it，不要 delete it。
+
+When your changes create orphans:
+- 移除由 YOUR changes 造成 unused 的 imports、variables、functions。
+- 除非用户明确要求，不要移除 pre-existing dead code。
+
+The test: 每一行 changed line 都应该能直接 trace 到用户请求。
+
+## 4. Goal-Driven Execution
+
+**定义 success criteria，并 loop until verified。**
+
+把任务转换为 verifiable goals:
+- `Add validation` → 为 invalid inputs 写 tests，然后 make them pass。
+- `Fix the bug` → 写一个能 reproduce 它的 test，然后 make it pass。
+- `Refactor X` → 确保 tests 在 before and after 都 pass。
+
+对于 multi-step tasks，先给出 brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria 可以让你 independent loop。Weak criteria，例如 “make it work”，会导致 constant clarification。
+
+---
+
+**这些 guidelines 生效的信号：** diffs 中 unnecessary changes 更少，因为 overcomplication 导致的 rewrites 更少，并且 clarifying questions 出现在 implementation 之前，而不是 mistakes 之后。
+
+### Harness 补充原则
+
+1. 阶段约束优先：除非用户明确要求其它工作流动作，否则使用 `active_skill` 指定的 Skill，并服从当前阶段的 allowed paths、required gates 和交付物边界。
+2. 文档先于实现：产品文档和技术方案未形成前，不写业务代码；需求变更必须进入 RFC 工作流。
+3. 验证闭环：多步骤工作先给出简短计划，并为关键步骤绑定验证方式。除非被阻塞，否则持续迭代到对应 `required_gates`、阶段 gate 或明确的人工验收标准满足。
+4. 派生物可再生成：`overview.md`、包内 assets 等 generated artifact 必须由对应命令刷新，不手写局部补丁。
+
+## 工作规则
+
+1. 选择任何角色或 Skill 前，先读取 `.agent/state/lifecycle.yaml`。
+2. 除非用户明确要求其它工作流动作，否则使用 `active_skill` 指定的 Skill。
+3. 产品文档和技术方案未形成前，不写业务代码。
+4. 在 `SPRINTING` 阶段，一次只执行一个任务。
+5. 在 `SPRINTING` 阶段，只编辑当前 open task 的 `allowed_paths` 允许的文件。
+6. 不要在当前 open task 的 `required_gates` 通过前把任务标记为 `done`。
+7. 代码 gate 通过后，更新任务实现文档和 `.docs/INDEX.md`。
+8. `reviewer` 角色只读，不直接修改源码。
+9. 需求变更必须进入 RFC 工作流。
+10. task/release 历史动作记录使用 git commit、tag 或外部 release 系统，不维护 `.agent/archive/` 常规归档。
+11. 在 `SPRINTING` 阶段，task 完成闭环必须先提交保留完整 open task 合同的 task implementation commit，再提交压缩 `plan.yaml` 后的 task completion ledger commit；如果没有 remote/upstream、权限或凭证导致无法 push，不要开始下一个 task，先报告 blocker。
+12. 文档 slice 发生变化后，运行 `make docs-overview` 刷新对应 `overview.md`。
+13. open task 必须在 `plan.yaml` 中包含完整执行合同，再继续推进或交接。
+14. 如果信息缺失，或 gate 因基础设施原因失败，停止推进并报告 blocker。
+
+## 宏指令
+
+- `/status`：报告当前阶段、角色、任务、阻塞项和下一步动作。
+- `/next`：运行当前阶段映射的 Skill。
+- `/advance`：校验当前阶段出口 gate，通过后才尝试流转。
+- `/rfc <file>`：挂起当前流程并进入 RFC recalibration。
+- `/syncdocs`：同步 `.docs/INDEX.md` 与当前文档事实源。
+- `/overview`：运行 `make docs-overview`，刷新 `.docs/<stage>/overview.md` 派生视图。
+- `/review`：运行只读 Review 工作流。
+- `/test`：运行测试计划和验证工作流。
+
+## 阶段流转
+
+正常阶段流转不要手动编辑 `.agent/state/lifecycle.yaml`。使用：
+
+```sh
+python3 tools/transition.py --to <PHASE>
+```
+
+流转前先运行阶段 gate，通常使用 `make validate-current`，或使用
+`.agent/policies/phase_contracts.yaml` 中列出的具体 `make validate-*` 目标。

package/assets/github/.gitkeep

@@ -0,0 +1 @@
+

package/assets/github/harness.yml

@@ -0,0 +1,45 @@
+name: Harness Gates
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      gate:
+        description: "Make target to run"
+        required: true
+        default: "validate-harness"
+        type: choice
+        options:
+          - validate-harness
+          - validate-doc-overviews
+          - validate-current
+          - validate-pm
+          - validate-design
+          - validate-dev
+          - validate-review
+          - validate-test
+          - validate-release
+          - validate-rfc
+
+jobs:
+  harness:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: "npm"
+      - name: Install package dependencies
+        run: npm install
+      - name: Test sdlc-harness package
+        run: npm test --workspace agent-project-sdlc
+      - name: Check package canonical source drift
+        run: npm --workspace agent-project-sdlc exec -- sdlc-harness package check-source
+      - name: Run harness gate
+        run: make "${HARNESS_GATE}"
+        env:
+          HARNESS_GATE: ${{ github.event.inputs.gate || 'validate-harness' }}

package/assets/make/.gitkeep

@@ -0,0 +1 @@
+

package/assets/make/sdlc-harness.mk

@@ -0,0 +1,78 @@
+PYTHON ?= python3
+
+.PHONY: help status docs-overview validate-doc-overviews validate-harness validate-current validate-pm validate-design validate-dev validate-review validate-test validate-release validate-rfc lint test-current-domain test-all build
+
+help:
+	@echo "AI SDLC Harness commands"
+	@echo "  make status              查看 lifecycle 和 task 状态"
+	@echo "  make docs-overview       生成 .docs 各阶段 overview.md 派生视图"
+	@echo "  make validate-doc-overviews 校验 .docs 各阶段 overview.md 是否最新"
+	@echo "  make validate-harness    校验 Harness 骨架、配置和提示词语言契约"
+	@echo "  make validate-current    运行当前 lifecycle phase 的 gate"
+	@echo "  make validate-pm         校验产品需求产物"
+	@echo "  make validate-design     校验架构设计、技术方案和任务草案"
+	@echo "  make validate-dev        校验 sprint 任务状态、路径、代码 gate 和实现文档"
+	@echo "  make validate-review     校验 Review report"
+	@echo "  make validate-test       校验 regression/test plan"
+	@echo "  make validate-release    校验 release note、smoke result 和 rollback plan"
+	@echo "  make validate-rfc        校验 RFC 产物并运行完整回归入口"
+
+status:
+	$(PYTHON) tools/status.py
+
+docs-overview:
+	$(PYTHON) tools/build_doc_overviews.py --all
+
+validate-doc-overviews:
+	$(PYTHON) tools/build_doc_overviews.py --all --check
+
+validate-harness:
+	$(PYTHON) tools/validate_harness.py
+	$(PYTHON) tools/validate_prompt_language.py
+	$(PYTHON) tools/build_doc_overviews.py --all --check
+
+validate-current:
+	$(PYTHON) tools/run_current_gate.py
+
+validate-pm:
+	test -f .docs/INDEX.md
+	$(PYTHON) tools/validate_prd.py
+
+validate-design:
+	$(PYTHON) tools/validate_design.py
+	$(PYTHON) tools/validate_plan_draft.py
+
+validate-dev:
+	$(PYTHON) tools/validate_plan.py
+	$(PYTHON) tools/validate_allowed_paths.py
+	$(MAKE) lint
+	$(MAKE) test-current-domain
+	$(PYTHON) tools/validate_task_docs.py
+
+validate-review:
+	test -f .docs/06_review/REVIEW_REPORT.md
+	$(PYTHON) tools/validate_review.py
+
+validate-test:
+	$(MAKE) test-all
+	$(PYTHON) tools/validate_test_plan.py
+
+validate-release:
+	$(MAKE) build
+	$(PYTHON) tools/validate_release_plan.py
+
+validate-rfc:
+	$(PYTHON) tools/validate_rfc.py
+	$(MAKE) test-all
+
+lint:
+	@echo "No project lint command configured yet. Replace this target with your stack-specific lint command."
+
+test-current-domain:
+	@echo "No domain test command configured yet. Replace this target with focused tests for current_task_id."
+
+test-all:
+	@echo "No full test command configured yet. Replace this target with the project regression suite."
+
+build:
+	@echo "No build command configured yet. Replace this target with the project build/package command."

package/assets/policies/allowed_paths.yaml

@@ -0,0 +1,55 @@
+global:
+  never_edit_without_confirmation:
+    - ".git/**"
+    - ".env"
+    - ".env.*"
+    - "secrets/**"
+    - "production/**"
+
+phases:
+  REQUIREMENT_GATHERING:
+    write:
+      - ".docs/00_raw/**"
+      - ".docs/01_product/**"
+      - ".docs/INDEX.md"
+
+  ARCHITECTING:
+    write:
+      - ".docs/02_architecture/**"
+      - ".docs/03_tech_plan/**"
+      - ".docs/05_decisions/**"
+      - "<harnessRoot>/state/plan.draft.yaml"
+      - ".docs/INDEX.md"
+
+  SPRINTING:
+    write_from_task_allowed_paths: true
+    always_allow:
+      - ".docs/04_implementation/**"
+      - ".docs/INDEX.md"
+      - "<harnessRoot>/state/plan.yaml"
+      - "<harnessRoot>/state/gate_results.log"
+
+  REVIEWING:
+    read_only_source: true
+    write:
+      - ".docs/06_review/**"
+      - ".docs/INDEX.md"
+
+  TESTING:
+    write:
+      - ".docs/07_test/**"
+      - "tests/**"
+      - ".docs/INDEX.md"
+
+  RELEASING:
+    write:
+      - ".docs/08_release/**"
+      - ".docs/INDEX.md"
+
+  RFC_RECALIBRATION:
+    write:
+      - ".docs/rfc/**"
+      - ".docs/01_product/**"
+      - ".docs/03_tech_plan/**"
+      - "<harnessRoot>/state/plan.yaml"
+      - ".docs/INDEX.md"

package/assets/policies/gates.yaml

@@ -0,0 +1,48 @@
+gates:
+  validate-harness:
+    command: "make validate-harness"
+    purpose: "验证 Harness 模板、状态源、策略和 Skill 文件是否完整"
+    required_for:
+      - "all"
+
+  validate-pm:
+    command: "make validate-pm"
+    purpose: "验证 PRD、验收标准、Out of Scope 和 Open Questions"
+    required_for:
+      - "REQUIREMENT_GATHERING"
+
+  validate-design:
+    command: "make validate-design"
+    purpose: "验证架构设计、技术方案、任务草案和任务字段完整性"
+    required_for:
+      - "ARCHITECTING"
+
+  validate-dev:
+    command: "make validate-dev"
+    purpose: "验证任务状态、allowed_paths、代码检查、测试和实现文档"
+    required_for:
+      - "SPRINTING"
+
+  validate-review:
+    command: "make validate-review"
+    purpose: "验证 Review 报告、风险结论和测试入口建议"
+    required_for:
+      - "REVIEWING"
+
+  validate-test:
+    command: "make validate-test"
+    purpose: "验证测试矩阵、回归记录和覆盖缺口"
+    required_for:
+      - "TESTING"
+
+  validate-release:
+    command: "make validate-release"
+    purpose: "验证发布说明、Smoke Test、部署检查和回滚方案"
+    required_for:
+      - "RELEASING"
+
+  validate-rfc:
+    command: "make validate-rfc"
+    purpose: "验证 RFC 格式、影响分析、回归要求和状态"
+    required_for:
+      - "RFC_RECALIBRATION"

package/assets/policies/phase_contracts.yaml

@@ -0,0 +1,140 @@
+phases:
+  IDLE:
+    goal: "等待项目启动"
+    role: "manager"
+    skill: "manager"
+    inputs:
+      - "<harnessRoot>/state/lifecycle.yaml"
+    outputs:
+      - "<harnessRoot>/state/lifecycle.yaml"
+    gates: []
+    next: "REQUIREMENT_GATHERING"
+
+  REQUIREMENT_GATHERING:
+    goal: "收集需求并形成产品方案"
+    role: "pm"
+    skill: "pm_prd"
+    inputs:
+      - ".docs/00_raw/"
+    outputs:
+      - ".docs/01_product/"
+      - ".docs/INDEX.md"
+    gates:
+      - "make validate-pm"
+    next: "ARCHITECTING"
+
+  ARCHITECTING:
+    goal: "根据产品方案生成架构设计、技术方案和任务草案"
+    role: "architect"
+    skill: "architect_design"
+    inputs:
+      - ".docs/01_product/"
+      - ".docs/02_architecture/"
+    outputs:
+      - ".docs/02_architecture/"
+      - ".docs/03_tech_plan/"
+      - "<harnessRoot>/state/plan.draft.yaml"
+    gates:
+      - "make validate-design"
+    next: "SPRINTING"
+
+  SPRINTING:
+    goal: "按任务状态执行开发、测试和实现文档沉淀"
+    role: "developer"
+    skill: "dev_sprint"
+    inputs:
+      - "<harnessRoot>/state/plan.yaml"
+      - "current open task plan contract"
+      - ".docs/01_product/"
+      - ".docs/03_tech_plan/"
+    outputs:
+      - "src/"
+      - "tests/"
+      - ".docs/04_implementation/"
+      - "<harnessRoot>/state/gate_results.log"
+    gates:
+      - "make validate-dev"
+    next: "REVIEWING"
+
+  REVIEWING:
+    goal: "只读审查实现质量、需求一致性和架构风险"
+    role: "reviewer"
+    skill: "reviewer"
+    inputs:
+      - ".docs/01_product/"
+      - ".docs/03_tech_plan/"
+      - ".docs/04_implementation/"
+      - "git diff"
+    outputs:
+      - ".docs/06_review/REVIEW_REPORT.md"
+    gates:
+      - "make validate-review"
+    next: "TESTING"
+
+  TESTING:
+    goal: "形成测试矩阵并完成回归验证"
+    role: "tester"
+    skill: "tester"
+    inputs:
+      - ".docs/01_product/"
+      - ".docs/03_tech_plan/"
+      - ".docs/04_implementation/"
+      - ".docs/06_review/"
+    outputs:
+      - ".docs/07_test/"
+      - "tests/"
+    gates:
+      - "make validate-test"
+    next: "RELEASING"
+
+  RELEASING:
+    goal: "发布准备、发布检查和回滚方案"
+    role: "release_manager"
+    skill: "release_manager"
+    inputs:
+      - ".docs/07_test/"
+      - "build artifacts"
+    outputs:
+      - ".docs/08_release/"
+    gates:
+      - "make validate-release"
+    next: "COMPLETED"
+
+  COMPLETED:
+    goal: "当前里程碑已完成"
+    role: "manager"
+    skill: "manager"
+    inputs:
+      - ".docs/08_release/"
+    outputs:
+      - "<harnessRoot>/state/lifecycle.yaml"
+    gates: []
+    next: "IDLE"
+
+  RFC_RECALIBRATION:
+    goal: "处理需求变更、影响分析、局部补丁和任务回退"
+    role: "rfc_owner"
+    skill: "rfc_recalibrate"
+    inputs:
+      - ".docs/rfc/"
+      - ".docs/01_product/"
+      - ".docs/03_tech_plan/"
+      - "<harnessRoot>/state/plan.yaml"
+    outputs:
+      - ".docs/rfc/"
+      - "<harnessRoot>/state/plan.yaml"
+      - ".docs/INDEX.md"
+    gates:
+      - "make validate-rfc"
+    next: "SPRINTING"
+
+  BLOCKED:
+    goal: "等待人工补充信息、授权或基础设施处理"
+    role: "manager"
+    skill: "manager"
+    inputs:
+      - "<harnessRoot>/state/lifecycle.yaml"
+    outputs:
+      - "<harnessRoot>/state/lifecycle.yaml"
+    gates: []
+    next: "REQUIREMENT_GATHERING"

package/assets/policies/risk_matrix.yaml

@@ -0,0 +1,27 @@
+risk_levels:
+  P0:
+    label: "必须人工确认"
+    examples:
+      - "生产数据删除、迁移或不可逆写入"
+      - "认证、授权、支付、审计、合规策略变化"
+      - "跨服务接口契约破坏性变更"
+      - "无法通过本地或 CI gate 复现的关键失败"
+    action: "进入 BLOCKED，说明风险和所需确认"
+
+  P1:
+    label: "需要明确记录并建议人工复核"
+    examples:
+      - "公共 API 行为变化"
+      - "核心性能路径改造"
+      - "测试覆盖明显不足但业务要求继续"
+      - "与既有技术方案存在偏移"
+    action: "记录在实现文档、Review 报告或 RFC 中"
+
+  P2:
+    label: "Agent 可继续处理"
+    examples:
+      - "局部 bug 修复"
+      - "文档补充"
+      - "单任务范围内的测试补充"
+      - "非破坏性重构"
+    action: "按当前阶段 Skill 继续推进"

package/assets/skills/architect_design/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: architect_design
+description: Use during ARCHITECTING to create architecture docs, technical plans, interface contracts, and task drafts.
+---
+
+# Architect Design Skill
+
+## 目的
+
+把已确认的 PRD 转成可实施的架构设计、技术方案、接口契约和机器可读任务草案。
+
+## 角色提示词
+
+你是资深架构师，目标是把产品需求转成能落地、能验证、能分工的技术方案。你不仅要产出 architecture / tech plan 文档，还要在对话中帮助用户澄清边界、约束、风险和可行路径。
+
+开始设计前，先确认 PRD 的 requirement IDs、目标用户、验收标准、Out of Scope 和未决问题。如果需求不足以做技术决策，要明确列出缺口；如果存在多种方案，要用简洁的 tradeoff 说明成本、风险、迁移复杂度、可测试性和长期维护影响。
+
+架构产物应区分稳定边界和实现计划：architecture slice 记录领域边界、子系统、关键风险和长期约束；tech plan slice 记录接口契约、数据模型、模块方案、任务拆分和 gate。不要把重大架构变化藏在 task 描述里。
+
+## 输入
+
+- `.docs/INDEX.md`
+- 相关 `.docs/01_product/` PRD
+- 现有 `.docs/02_architecture/`
+- 当前代码结构概览
+- `<harnessRoot>/managed/templates/TECH_DESIGN_TEMPLATE.md`
+- `<harnessRoot>/managed/templates/PLAN_TEMPLATE.yaml`
+
+## 输出
+
+- `.docs/02_architecture/` 下的架构文档
+- `.docs/03_tech_plan/` 下的技术方案
+- 需要长期保留的 ADR 写入 `.docs/05_decisions/`
+- `<harnessRoot>/state/plan.draft.yaml`
+- 更新后的 `.docs/INDEX.md`
+
+## 语义切片
+
+- `.docs/02_architecture/` 按领域边界、子系统、跨模块架构问题或关键技术风险切片。
+- `.docs/03_tech_plan/` 按可实现范围、接口契约、数据模型、模块方案或任务组切片。
+- `.docs/05_decisions/` 按单个架构决策切片，即一份 ADR 只记录一个 durable decision。
+- 如果一个技术方案跨越多个独立模块，应拆成多个 tech plan slice，并在 `plan.draft.yaml` 中分别引用。
+- 如果实现计划改变了已有模块边界，应更新相关 architecture slice，而不是只在 task 描述里补一句。
+- 每次新增、拆分、合并或废弃 slice 后，都要更新 `.docs/INDEX.md`。
+
+## 规则
+
+1. 技术方案必须引用 PRD 路径和 requirement IDs。
+2. 每个 open task 必须包含 `id`、`title`、`status`、`summary`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `implementation_doc`。
+3. `plan.draft.yaml` 不得自动覆盖 `plan.yaml`。
+4. 风险或不清晰的问题按 `<harnessRoot>/managed/policies/risk_matrix.yaml` 标记。
+5. 任务边界应足够小，能在一次开发执行和一份 implementation doc 内闭环。
+
+## 完成检查
+
+- [ ] 架构文档和技术方案已生成。
+- [ ] 相关接口契约和数据结构已明确。
+- [ ] 已判断 architecture / tech plan / ADR 的语义切片边界。
+- [ ] task draft 字段完整且范围清晰。
+- [ ] `.docs/INDEX.md` 已链接新增产物。
+- [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。
+- [ ] `make validate-design` 准备通过。