@ecc-hgy/ae 0.3.0 → 0.4.0

package/README.md

@@ -5,6 +5,29 @@
 
 Agentic Engineering is a lightweight personal software lifecycle method: SDD records what to build, TDD drives how to prove it works. It is delivered as a zero-dependency npm CLI plus agent skills for Claude Code and Codex.
 
+## How It Works
+
+```text
+   (one-time)  ─────▶  S0 Bootstrap · ae setup → ae init
+                            │
+   (each request) ──▶  Router · is this request a *need*?
+                            │
+                ┌──── no ────┴──── yes ────┐
+                ▼                           ▼
+           just do it                enter S1 Main Loop
+       (Q&A / quick fix /                   │
+        throwaway script)                   ├─ A. Need:   align → PRD → design → todo → TDD → verify
+                                            └─ B. Accept: accept → debug → fix → reverify → sediment
+                                                          │
+                                                          ▼  (rules proven useful)
+                                                     S2 Evolution
+
+   Legend:  SDD = align→PRD→design→todo   ·   TDD = TDD→verify, fix→reverify
+   State:   spec/ = what to build (persistent) · INDEX.md = need@node · handoff.md = session snapshot
+```
+
+A router (the `using-agentic-engineering` skill) gates each non-trivial request: a *need* enters the SDD+TDD loop, everything else is just done. Questions, quick fixes, and throwaway scripts never pay the ceremony.
+
 ## Quick Start
 
 ```bash
@@ -37,7 +60,7 @@ Both commands are idempotent. They create missing files, skip existing files, an
 
 - `AGENTS.md` is the canonical project instructions file.
 - `CLAUDE.md` is a short pointer to `AGENTS.md`; do not maintain a separate copy there.
-- All project-specific rules live in `AGENTS.md` under `## Project-Specific Rules`.
+- `ae init` renders `AGENTS.md` nearly blank (title + goal); add your own rules and sections as the project grows — no imposed format.
 
 ## Platform Scope
 
@@ -66,6 +89,7 @@ The two hard gates are:
 
 | Skill | Role |
 |-------|------|
+| `using-agentic-engineering` | Router: at the start of a non-trivial change, decides whether it enters the SDD+TDD loop and dispatches to the right node skill. |
 | `brainstorming` | Coarse requirement alignment before writing PRD. |
 | `grill-me` | Fine-grained questioning for interface, field, parameter, or expected-state ambiguity. |
 | `to-prd` | Writes `spec/needs/<need-name>/prd.md`. |
@@ -78,6 +102,7 @@ The two hard gates are:
 | `handoff` | Writes the latest session snapshot to `handoff.md`. |
 | `improve-codebase-architecture` | User-triggered architecture deepening review. |
 | `zoom-out` | User-triggered higher-level codebase map. |
+| `karpathy-guidelines` | Always-on coding discipline during A5/B5: think before coding, simplicity first, surgical changes, goal-driven execution. |
 
 ## Documentation
 
@@ -101,11 +126,16 @@ tests/      node:test coverage for CLI behavior
 
 ## Roadmap
 
-1. Stage 2: npm CLI asset distribution with `init` and `ingest-mother`. Superseded by v0.2.
-2. v0.2: split CLI into `setup` + `init`, remove slash command assets, and move rule sync into `ae init`.
-3. v0.3: remove rules injection; make `AGENTS.md` the single source of truth and `CLAUDE.md` a pointer.
-4. Stage 3: design `ae update` for skill/template upgrades and implement `ae index-rebuild`.
-5. Add CI and Windows path validation before broader distribution.
+Completed:
+
+- v0.2: split CLI into `setup` + `init` and remove slash command assets.
+- v0.3: remove rules injection; make `AGENTS.md` the single source of truth and `CLAUDE.md` a pointer.
+
+Next:
+
+1. Design `ae update` for skill/template upgrades.
+2. Implement `ae index-rebuild`.
+3. Add CI and Windows path validation before broader distribution.
 
 ## Limits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecc-hgy/ae",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agentic Engineering is a lightweight personal software lifecycle method: SDD records what to build, TDD drives how to prove it works.",
   "type": "module",
   "bin": {

package/skills/diagnose/SKILL.md

@@ -18,7 +18,7 @@ If B2 has NOT been completed (the expected behavior is still ambiguous), STOP an
 
 ## Exit Contract (hand-off to B4)
 
-After Phase 6, do NOT write the issue file inline - that is B4's job. Instead, hand off a structured summary so B4 can write `spec/needs/<need-name>/issues/<topic>.md` in one pass, using the 7-section format in [assets/issue-7-sections.md](assets/issue-7-sections.md).
+After Phase 6, do NOT write the issue file inline - that is B4's job. Instead, hand off a structured summary so B4 can write `spec/needs/<need-name>/issues/<topic>.md` (`<topic>` is kebab-case) in one pass, using the 7-section format in [assets/issue-7-sections.md](assets/issue-7-sections.md).
 
 Sections this skill is expected to populate:
 

package/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: karpathy-guidelines
+description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
+license: MIT
+---
+
+# Karpathy Guidelines
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

package/skills/review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review
-description: Two-axis review (Standards / Spec) of the changes for a need that is about to close, followed by sedimentation routing - review findings flow into prd.md / design.md / spec/ADR/ / S2 candidates per `spec-framework.md`. Used at S1 node B7.
+description: Two-axis review (Standards / Spec) of the changes for a need that is about to close, followed by sedimentation routing - review findings flow into prd.md / design.md / spec/ADR/ / S2 candidates per `spec/AGENTS.md`. Used at S1 node B7.
 ---
 
 # Review
@@ -96,7 +96,7 @@ After routing:
    - Set every `issues/*.md` referenced in this close to "已验收"
    - If any `prd.md` / `design.md` was patched, leave `status: active` and refresh `last-aligned`
    - If a new ADR was created, add a row under `## ADR` with `status: proposed`
-   - If unsure, run `/ae-index-rebuild`
+   - If unsure, run `ae index-rebuild`
 2. Print a one-block summary to the user:
    - Findings routed to prd / design / ADR / S2-candidates with counts
    - Files modified (path list)

package/skills/tdd/SKILL.md

@@ -135,8 +135,8 @@ After all tests pass, look for [refactor candidates](refactoring.md):
 1. Tick the corresponding `- [ ]` -> `- [x]` in `spec/needs/<need-name>/todo.md`
 2. Update `spec/INDEX.md`:
    - Bump the `todo` column counter (e.g. `2/8` -> `3/8`)
-   - If all `## 实施` items are now checked, set `当前节点` to `A6 verify` (per `spec-framework.md` INDEX rules)
-   - If unsure, run `/ae-index-rebuild`
+   - If all `## 实施` items are now checked, set `当前节点` to `A6 verify` (per `spec/AGENTS.md` INDEX rules)
+   - If unsure, run `ae index-rebuild`
 3. Commit. Suggested message: `feat(<need-name>): T<n> <title>`.
 
 ## After All Slices Checked (A5 only)

package/skills/to-issues/SKILL.md

@@ -68,8 +68,8 @@ Format summary (full rules live in [`todo-template.md`](todo-template.md)):
 
 1. Update `spec/INDEX.md`:
    - Set the `todo` column to `0/N` (where N = total tasks in `## 实施`)
-   - Recompute the `当前节点` column per the rules in `spec-framework.md` §INDEX 推导规则 (likely now `A5 执行`)
-   - If unsure, run `/ae-index-rebuild` for an idempotent rescan
+   - Recompute the `当前节点` column per the rules in `spec/AGENTS.md` §INDEX 推导规则 (likely now `A5 执行`)
+   - If unsure, run `ae index-rebuild` for an idempotent rescan
 2. Hand off to the next S1 node: A5 `tdd` will read this `todo.md` (plus `design.md`) and drive the red-green-refactor loop. Tell the user the task list is ready and recommend invoking `tdd` next.
 
 ## Boundaries

package/skills/to-issues/todo-template.md

@@ -13,13 +13,13 @@
 - B1 <blocker description, link back to the design section that needs sharpening>
 
 <!--
-Rules for maintaining this file (see also `spec-framework.md` §frontmatter / todo.md):
+Rules for maintaining this file:
 
 - NO frontmatter — this is a rolling working artifact, not a stateful spec document.
 - Use `- [ ]` for unfinished, `- [x]` for finished. Never delete completed items — they are visible history.
 - Sort by dependency order (blockers first); within the same level, sort by suggested execution order.
 - If a slice depends on a design decision that is still open, put it in `## 阻塞 / 待澄清` instead of `## 实施`.
-- Each slice MUST be traceable to a section in `design.md`. If a new slice has no traceable design section, that itself is a finding — go back and patch `design.md` rather than smuggling new scope into `todo.md` (matches `spec-framework.md` §边界规则: "todo 不应该出现 design 里没提的事").
+- Each slice MUST be traceable to a section in `design.md`. If a new slice has no traceable design section, that itself is a finding — go back and patch `design.md` rather than smuggling new scope into `todo.md`.
 - Slice identifiers: `T<n>` for execution tasks, `B<n>` for blockers. Stable across the life of the need; do not renumber.
 - Acceptance criteria: a single observable behavior that proves the slice is done. If it needs multiple lines, the slice is probably too coarse — split it.
 -->

package/skills/to-prd/SKILL.md

@@ -15,7 +15,7 @@ Check with the user that these seams match their expectations.
 
 2.5. Align the `need-name` (kebab-case) with the user. This is the slug used to create `spec/needs/<need-name>/`. Surface a concrete suggestion derived from the PRD topic and confirm before writing.
 
-3. Write the PRD using the template below. Save it to `spec/needs/<need-name>/prd.md` with the frontmatter block shown below the template. After saving, update `spec/INDEX.md` (add or update the row for this need) — or run `/ae-index-rebuild` to recompute.
+3. Write the PRD using the template below. Save it to `spec/needs/<need-name>/prd.md` with the frontmatter block shown below the template. After saving, update `spec/INDEX.md` (add or update the row for this need) — or run `ae index-rebuild` to recompute.
 
 <prd-template>
 
@@ -97,8 +97,8 @@ State transitions:
 1. Update `spec/INDEX.md`:
    - If the need is new: add a row under `## 需求`
    - If updating: set the `prd` column to `active`
-   - Recompute the `当前节点` column per the rules in `spec-framework.md` §INDEX 推导规则
-   - If unsure, run `/ae-index-rebuild` for an idempotent rescan
+   - Recompute the `当前节点` column per the rules in `spec/AGENTS.md` §INDEX 推导规则
+   - If unsure, run `ae index-rebuild` for an idempotent rescan
 2. Hand off to the next S1 node: A3 `writing-plans` will read this `prd.md` and produce `spec/needs/<need-name>/design.md`. Tell the user the PRD is ready and recommend invoking `writing-plans` next.
 
 ## Boundaries

package/skills/using-agentic-engineering/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: using-agentic-engineering
+description: Router for projects that use Agentic Engineering. Use at the start of a feature, bug fix, or other non-trivial change to decide whether it should enter the SDD+TDD loop and which node/skill to start from. Skip for quick fixes, questions, and throwaway scripts.
+---
+
+# Using Agentic Engineering
+
+This project follows the **Agentic Engineering** method: SDD records *what to build* (in `spec/`), TDD proves *it works*. This skill is a **router** — it decides whether the current request enters that loop and, if so, hands off to the right node skill. It does not carry the method itself; each node has its own skill.
+
+## Instruction priority
+
+1. **The user's explicit request this turn** — highest. If they say "just do X" / "skip the process," do exactly that.
+2. **`AGENTS.md`** — the project's own rules (whatever the project declares there).
+3. **Agentic Engineering defaults (below)** — lowest.
+
+AE never blocks something you were explicitly asked to do. These are defaults, not laws.
+
+## Step 0 — Orient (only when needed)
+
+Read `handoff.md` (latest session snapshot) and `spec/INDEX.md` (needs + current node) **only when you lack context** — at the start of a fresh session, or when you can't tell whether this request continues existing work or starts something new. If you already have that context from the conversation, skip straight to routing. Don't re-read them every turn.
+
+## Step 1 — Route: is this a *need*?
+
+The one question: **does this request create or change a *need* — durable, product-facing behavior worth recording in `spec/`?**
+
+**Does NOT enter the loop — just do it, no ceremony:**
+- Questions / explanations ("what does this do?", "why is it slow?")
+- Quick fixes, one-line changes, typos
+- Throwaway / one-off scripts, spikes, experiments
+- Chores: rename, format, dependency bump, run tests, git
+- Anything the user explicitly asked to do directly
+
+**Enters the loop:**
+- A new feature or non-trivial capability → go to **A1**
+- A bug / wrong behavior on an existing need → go to **B2**
+- Continuing an existing need → resume at its **current node** (from `spec/INDEX.md`)
+
+**Unsure?** Default to *not* entering: do what was asked, then add one line — "This looks like it might be a need; want me to capture it in `spec/` / align first?" — and hand the decision back to the user. Don't gate.
+
+## Step 2 — Dispatch (only when it enters the loop)
+
+Hand off to the node skill below. Two hard gates are rigid:
+- **A1 not aligned → do not write `prd.md`.**
+- **B2 expected behavior not aligned → do not start fixing.**
+
+| Node | Purpose | Skill |
+|------|---------|-------|
+| A1 | Align the requirement | `brainstorming` (+ `grill-me` for detail) |
+| A2 | Write `prd.md` | `to-prd` |
+| A3 | Write `design.md` | `writing-plans` |
+| A4 | Write `todo.md` | `to-issues` |
+| A5 | Implement (TDD) | `tdd` |
+| A6 | Verify on the real path | `verification-before-completion` |
+| B2 | Align expected behavior | `grill-me` |
+| B3 | Find root cause | `diagnose` |
+| B4 | Write the issue file | (7-section format) |
+| B5 | Fix (TDD) | `tdd` |
+| B7 | Review & sediment findings | `review` |
+
+`karpathy-guidelines` is always-on whenever you write or change code (no node).
+
+Spec file mechanics — INDEX derivation, frontmatter, state machine, R1 — live in `spec/AGENTS.md`.

package/skills/verification-before-completion/SKILL.md

@@ -135,8 +135,8 @@ This is non-negotiable.
 If verification passes:
 
 1. Update `spec/INDEX.md`:
-   - Recompute `当前节点` per `spec-framework.md` INDEX rules - for a fresh need this becomes "B1 user acceptance" (the next node is user-driven, not skill-driven)
-   - If unsure, run `/ae-index-rebuild`
+   - Recompute `当前节点` per `spec/AGENTS.md` INDEX rules - for a fresh need this becomes "B1 user acceptance" (the next node is user-driven, not skill-driven)
+   - If unsure, run `ae index-rebuild`
 2. Hand off to B1: tell the user the need is ready for their hands-on acceptance test. Do NOT mark anything `archived` - `archived` is reserved for needs that get superseded, not completed.
 
 If verification fails:

package/skills/writing-plans/SKILL.md

@@ -103,8 +103,8 @@ If you find issues, fix them inline. No need to re-review — just fix and move
 
 1. Update `spec/INDEX.md`:
    - Set the `design` column to `active` (or `draft` if key trade-offs still need user approval)
-   - Recompute the `当前节点` column per the rules in `spec-framework.md` §INDEX 推导规则
-   - If unsure, run `/ae-index-rebuild` for an idempotent rescan
+   - Recompute the `当前节点` column per the rules in `spec/AGENTS.md` §INDEX 推导规则
+   - If unsure, run `ae index-rebuild` for an idempotent rescan
 2. If you promoted any decision to `spec/ADR/`, also add a row under `## ADR` in `INDEX.md`.
 3. Hand off to the next S1 node: A4 `to-issues` will read this `design.md` and produce `spec/needs/<need-name>/todo.md`. Tell the user the design is ready and recommend invoking `to-issues` next.
 

package/src/skeleton.js

@@ -27,6 +27,10 @@ const ENTRY_FILES = [
   'handoff.md',
   path.join('spec', 'README.md'),
   path.join('spec', 'INDEX.md'),
+  path.join('spec', 'AGENTS.md'),
+  path.join('spec', 'CLAUDE.md'),
+  path.join('spec', 'ADR', 'AGENTS.md'),
+  path.join('spec', 'ADR', 'CLAUDE.md'),
 ];
 
 export async function createDirectories(target, options = {}) {

package/templates/entries/AGENTS.md

@@ -1,24 +1,3 @@
 # {{PROJECT_NAME}}
 
 > {{PROJECT_GOAL}}
-
-## Project-Specific Rules
-
-<!-- 在这里写本项目的稳定规则,例如:
-     - 代码风格 / 注释语言
-     - 提交规范
-     - 协作偏好
-     这些规则会被 Claude Code / Codex 在每次 session 自动加载。
-     未来新规则直接追加到本段,不需要其他工具命令。 -->
-
-## Stack
-
-TODO: 简述项目技术栈与运行环境。
-
-## Structure
-
-TODO: 简述目录结构,标注关键入口。
-
-## Operating Guidelines
-
-TODO: 简述代码、测试、提交、PR 的操作规范。

package/templates/entries/README.md

@@ -1,18 +1,32 @@
 # {{PROJECT_NAME}}
 
-{{PROJECT_GOAL}}
+> {{PROJECT_GOAL}}
 
-## Setup
+<!--
+根 README 的核心:让别人 30 秒搞清「为什么有用、能做什么、怎么用」。
+下面是建议骨架,按需增删、不必都填,也不必拘泥小节名:
+- 它是什么 + 一句话价值 → 上面的标题 + 一行(已占位)
+- 为什么 / 给谁 → 解决什么问题、面向谁
+- Quick Start → 最快见效的一段命令 / 步骤(装好 + 第一个能见效的操作)
+- 使用示例 → 典型场景(必要时再贴一段真实用法)
+- 目录地图 / 文档入口 → 关键目录 + 深入文档的链接
+-->
 
-TODO: 记录安装和启动方式。
+## 这是什么
 
-## Usage
+TODO: 一段话说清它解决什么问题、给谁用、用它能做什么。
 
-TODO: 记录常用操作。
+## Quick Start
 
-## Project Map
+TODO: 最快跑起来的命令或步骤。
 
-- `reference/`: 原始素材，只读心态。
-- `spec/`: SDD/TDD 规格产物。
-- `data/`: 运行产物、导出和缓存。
-- `scripts/`: 辅助脚本。
+<!-- ## 使用示例 —— 有典型场景时再加,贴一段真实用法 -->
+
+## 目录地图
+
+- `spec/`:SDD/TDD 规格产物——需求索引看 `spec/INDEX.md`,项目地图看 `spec/README.md`。
+- `reference/`:原始素材,只读心态。
+- `data/`:运行产物、导出、缓存。
+- `scripts/`:辅助脚本。
+
+<!-- 文档入口:AGENTS.md(项目指令)· handoff.md(当前态快照)· spec/INDEX.md(需求索引) -->

package/templates/entries/spec/ADR/AGENTS.md

@@ -0,0 +1,30 @@
+# spec/ADR/ 规则
+
+> 架构决策记录(ADR)规则。在 `spec/ADR/` 下创建或修改 ADR 时遵守本文件。
+
+## 命名
+
+`NNNN-<标题>.md`,**4 位序号**,kebab-case 标题。例:`0001-postgres-as-primary-store.md`。
+
+## frontmatter
+
+```yaml
+---
+status: accepted          # proposed | accepted | superseded
+date: 2026-06-14
+supersedes: 0000-xxx.md   # 仅当取代旧 ADR 时填
+---
+```
+
+正文按具体决策自然组织(背景 / 决策 / 理由 / 影响),不强加重模板。
+
+## 状态机
+
+```text
+proposed ─(评审接受)─► accepted ─(新 ADR 取代)─► superseded
+```
+
+- `proposed`:新提案,未拍板(由 writing-plans / review / improve-codebase-architecture 创建时默认)。
+- `accepted`:已评审接受;视为**约束**,其他需求不得违背。
+- `superseded`:被新 ADR 取代;新 ADR 的 `supersedes` 指回旧编号,**不删旧文件**。
+

package/templates/entries/spec/ADR/CLAUDE.md

@@ -0,0 +1,5 @@
+# spec/ADR/
+
+**Always read [AGENTS.md](./AGENTS.md) in this directory before creating or editing an ADR.**
+
+`spec/ADR/AGENTS.md` defines ADR naming, frontmatter, and the proposed/accepted/superseded state machine.

package/templates/entries/spec/AGENTS.md

@@ -0,0 +1,35 @@
+# spec/ 规则
+
+> 本目录(`spec/`)的工作规则。在 `spec/` 下读写文件时遵守本文件。
+
+## 总领
+
+S1 节点 → 产物 → skill 的路由总览,见随包的 `using-agentic-engineering` skill——它判定"进不进 AE 流程"并分发到各节点。
+
+两道硬门禁:**A1 未对齐不写 prd**;**B2 期望态未对齐不修复**。
+
+
+## R1:落盘后同步 INDEX
+落盘 `spec/needs/<需求名>/` 下任何文件后,**必须同步更新 `spec/INDEX.md`** 对应行。若不确定如何更新,按上面「INDEX 推导规则」手动重算(未来可用 `ae index-rebuild` 幂等重扫)。
+
+### INDEX 推导规则
+
+`spec/INDEX.md` 给模型看:一次扫描看到所有需求 + 状态 + 进度。`当前节点` 列**不存储**在任何 frontmatter,由该需求下文件状态**实时推导**:
+
+| 条件 | 当前节点 |
+|------|---------|
+| prd 不存在 或 status=draft | A1 / A2 |
+| prd active + design 不存在/draft | A3 设计 |
+| prd+design active + todo 不存在 | A4 拆解 |
+| prd+design active + todo 有未完成项 | A5 执行 |
+| todo 全勾 + 未端到端验证 | A6 verify |
+| 所有 issues 已验收 + 已交付 | 已完成 |
+| 存在 active 的 issues | 进 B 子路径,按 issues 状态推 B2…B7 |
+| prd / design 任一 archived | 已归档 |
+
+- INDEX 是**推导态**:文件状态变就重新推导,**不要手编 `当前节点` 列**。
+
+
+## 何时升 ADR
+
+决策影响**多个需求**或属项目级不变量时,从 `design.md` 升到`spec/ADR`(判断:推翻它会改动 >1 个需求)。单需求的技术决策留在该需求的 `design.md`。

package/templates/entries/spec/CLAUDE.md

@@ -0,0 +1,5 @@
+# spec/
+
+**Always read [AGENTS.md](./AGENTS.md) in this directory before working under `spec/`.**
+
+`spec/AGENTS.md` defines the S1 node map, the INDEX derivation table, and the post-write INDEX sync rule (R1).

package/templates/entries/spec/INDEX.md

@@ -2,14 +2,27 @@
 
 ## 需求
 
+<!--
+各列怎么填:
+- 需求名:`spec/needs/<需求名>/` 的 kebab 目录名
+- prd / design:对应文件 frontmatter 的 status(draft/active/archived);文件不存在填 -
+- todo:todo.md 的 已勾数/总数(如 5/8,即拆解任务的完成进度);无 todo.md 填 -。这是 A5 内部子进度,不是节点位次(节点看「当前节点」列)
+- issues:该需求 issues/ 下文件数 + 是否有未结(如 0 / 1 active);无则 -
+- 当前节点:由文件状态推导得出,不手编(推导规则见 spec/AGENTS.md「INDEX 推导规则」)
+-->
+
 | 需求名 | prd | design | todo | issues | 当前节点 |
 |--------|-----|--------|------|--------|----------|
 
 ## ADR
 
+<!-- 编号 4 位 / 状态 proposed|accepted|superseded / 日期,均取自各 ADR frontmatter(详见 spec/ADR/AGENTS.md) -->
+
 | 编号 | 标题 | 状态 | 日期 |
 |------|------|------|------|
 
 ## 跨需求引用
 
+<!-- 从各 prd/design frontmatter 的 related-needs 聚合 -->
+
 - 暂无

package/templates/entries/spec/README.md

@@ -1,5 +1,7 @@
 # Spec Map
 
+> 给人看:回忆"项目长什么样"。以 ASCII 图为主,可省细节、突出全貌。**README ≠ INDEX 镜像**——INDEX 给模型看进度,这里给人看全貌。
+
 ## Needs
 
 ```text
@@ -12,6 +14,8 @@ TODO: 用 ASCII 图画出需求地图。
 TODO: 用 ASCII 图画出核心业务流程。
 ```
 
+> 全局架构总览画在这里(而非写进某个需求的 design.md)。
+
 ## Relationships
 
 ```text