easy-coding-harness 0.1.8 → 0.3.0

package/templates/common/skills/ec-task-management/SKILL.md

@@ -13,32 +13,17 @@ Communicate with the user in the user's language.
 ## Capabilities
 
 ### List tasks
-Scan `.easy-coding/tasks/`. For each task folder show: id, `title` (if present), `status`,
-`created_at`, and whether it is active (status not in {COMPLETE, CLOSED}). Group by active
-vs finished so the user sees at a glance what is in flight. This is read-only — change
-nothing.
+Call the state API:
+`{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py list-tasks`.
+Show each task's id, title, status, created_at, and whether it is active. This is read-only.
 
 ### Create a task
-Create `.easy-coding/tasks/{MM-DD-short-name}/task.json` using the runtime schema:
-
-```json
-{
-  "type": "feature | bugfix | refactor | perf",
-  "title": "<one-line summary of the task>",
-  "status": "INIT",
-  "created_at": "<ISO 8601>",
-  "created_by": "<agent id>",
-  "context": {},
-  "spawned_from": null,
-  "spawned_tasks": [],
-  "closed_reason": null,
-  "repos": []
-}
-```
-
-Only set `current_task`/`current_stage` in state.json if the user explicitly wants to start
-the task now — otherwise leave the workflow state untouched and tell them to run
-`{{skill_trigger}}ec-workflow` when ready.
+Create through the state API, never by hand-editing `task.json` or session files:
+`{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py create-task --session-file <P> --task-id <MM-DD-short-name> --type <feature|bugfix|refactor|perf> --title "<one-line summary>" --agent <agent-id> --no-set-current`.
+
+If the user explicitly wants to start the task now, omit `--no-set-current`; otherwise leave
+the current workflow pointer untouched and tell them to run `{{skill_trigger}}ec-workflow`
+when ready.
 
 ## Boundaries
 

package/templates/common/skills/ec-verification/SKILL.md

@@ -75,9 +75,15 @@ change formally returns to IMPLEMENT and re-walks REVIEW → VERIFICATION.
 ## 5. Archive flow (only after acceptance)
 
 Runs automatically once the user accepts:
-1. MEMORY_SHORT — ec-memory writes the short memory entry.
-2. MEMORY_LONG — ec-memory distills long memory.
-3. COMPLETE — clear `current_task` in state.json, set task.json `status:"COMPLETE"`, output
-   the task summary (what was done, files changed, key decisions).
+1. MEMORY_SHORT — call
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py transition --session-file <P> --stage MEMORY_SHORT --agent <agent-id>`,
+   then hand control to ec-memory to write the short memory entry.
+2. MEMORY_LONG — after MEMORY_SHORT returns, call
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py transition --session-file <P> --stage MEMORY_LONG --agent <agent-id>`,
+   then hand control to ec-memory to distill long memory or perform its no-op gate.
+3. COMPLETE — after MEMORY_LONG returns, call
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py transition --session-file <P> --stage COMPLETE --agent <agent-id>`,
+   which clears session `current_task` for the completed task. Then output the task summary
+   (what was done, files changed, key decisions).
 
 Hand control back to ec-workflow at each transition; ec-workflow owns the stage writes.

package/templates/common/skills/ec-workflow/SKILL.md

@@ -18,14 +18,19 @@ replies are English.
    - Missing → tell the user to run the `easy-coding init` CLI first. Stop.
    - `status != "COMPLETE"` → tell the user to run `{{skill_trigger}}ec-init` first. Stop.
      Do not perform project initialization yourself; that is ec-init's job.
+   - `[easy-coding:upgrade-init-pending:X]` in breadcrumbs → tell the user: "Harness upgraded
+     to vX. Running `{{skill_trigger}}ec-init` is recommended to adapt project knowledge and
+     complete migration. You can skip and start working — the reminder will persist until
+     ec-init runs." Do NOT stop. Proceed with normal startup.
 2. **Required reading** (cheap, always):
    - `.easy-coding/SOUL.md` — project identity and dialogue standards; obey for the session.
    - `.easy-coding/RULES.md` — coding rules; re-checked before every write.
    - Latest 5 entries in `.easy-coding/memory/short/` — recent task context.
    Do NOT bulk-read ABSTRACT.md or long memory here; ec-analysis loads them on demand.
 3. **State check + Intent routing.** Read the hook-injected breadcrumbs (`[current-task:X]`,
-   `[workflow-state:Y]`) to determine the active task and stage, then decide based on
-   whether the user's message carries a task-related prompt beyond the bare skill trigger.
+   `[workflow-state:Y]`, `[easy-coding:session-file:P]`) to determine the active task,
+   stage, and session file, then decide based on whether the user's message carries a
+   task-related prompt beyond the bare skill trigger.
 
    **No prompt (bare trigger):**
    - `current_task` set with an active stage → resume that stage (see Resume and handoff).
@@ -53,9 +58,10 @@ replies are English.
         directly (step 4).
 
 4. **New task.** When creating a task (from step 3), create
-   `.easy-coding/tasks/{MM-DD-task-slug}/task.json` with `type`, `title` (one-line summary
-   of the user's prompt), `status:"INIT"`, `created_at`, `created_by` (current agent id),
-   set `current_task` in state.json, and enter INIT.
+   the task through the state API, which creates `task.json`, sets `status:"INIT"`, writes
+   `stage_history`, and sets the session `current_task`:
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py create-task --session-file <P> --task-id <MM-DD-task-slug> --type <type> --title "<one-line summary>" --agent <agent-id>`.
+   Then enter INIT.
 
 ## State machine
 
@@ -72,22 +78,28 @@ any stage --[user abort via ec-task-close]--> CLOSED
 
 | Stage | Owner skill | What happens | Exit condition |
 |---|---|---|---|
-| INIT | ec-workflow | collect context, settle task scope wording | task understood |
+| INIT | ec-workflow | collect context, settle scope AND delivery form (change code vs. produce a document) | task understood |
 | ANALYSIS | ec-analysis | dev-spec + execution plan + test strategy | analysis presented |
 | WAITING_CONFIRM | ec-workflow | blocking gate; user reviews the plan | explicit user confirmation |
 | IMPLEMENT | ec-implementing | code changes per confirmed plan | all units done |
 | REVIEW | ec-reviewing | multi-dimension code review | verdict = accept |
 | VERIFICATION | ec-verification | hard gate: lint/typecheck/test + coverage | all pass AND user accepts |
 | MEMORY_SHORT | ec-memory | archive: short memory entry | written |
-| MEMORY_LONG | ec-memory | archive: long memory distillation | written |
+| MEMORY_LONG | ec-memory | archive: long memory distillation (conditional — no-op when short memory is under threshold) | state API `memory_long` instruction handled |
 | COMPLETE | ec-workflow | clear current_task, set task status, summary | terminal |
 | CLOSED | ec-task-close | user abort; no memory flow | terminal |
 
+> **INIT delivery-form rule.** When creating the task, `type` and `title` must faithfully
+> reflect the delivery form implied by the user's request. A refactor/fix/feature is a CODE
+> task; do not record it as an analysis/report task. Do not let ANALYSIS later re-interpret a
+> code task into a documentation-only task — that is a downgrade (see ec-analysis HARD RULE 5).
+
 ## Task switching
 
 When the user confirms switching from task A to task B:
 1. Task A's status is already persisted in its `task.json` — nothing extra to save.
-2. Set `current_task` to task B's id in the session file (`.easy-coding/sessions/{ppid}.json`).
+2. Set the current task through the state API:
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py set-current --session-file <P> --task-id <task-b-id> --agent <agent-id>`.
 3. Read task B's `task.json` to determine its current stage.
 4. Resume task B's stage via the appropriate stage skill.
 
@@ -100,13 +112,24 @@ routing matches, and switching happens again.
 - **Never skip a stage.** ANALYSIS cannot jump to VERIFICATION; IMPLEMENT cannot start before
   WAITING_CONFIRM passes. No exception for "simple" tasks — simple tasks have short analyses,
   not skipped ones.
+- **ANALYSIS entry gate.** When entering ANALYSIS, your FIRST TWO tool calls must be:
+  (1) Read `.easy-coding/templates/dev-spec-skeleton.md`, then (2) Write its exact content
+  to the task's dev-spec.md. This is a mechanical copy, not a generation task. Do not read
+  code, load memory, or analyze before the skeleton is on disk. This is ec-analysis
+  HARD RULE 1 — violating it means the analysis has failed. Your reply to the user must
+  be the complete dev-spec.md content, not a summary or custom format.
+  Additionally, ANALYSIS must stay faithful to the user's delivery form — it may NOT downgrade
+  a code task to a report-only task — and the 改动范围 table must list only real project code,
+  never `.easy-coding/` harness artifacts (ec-analysis HARD RULES 5 and 6).
 - **WAITING_CONFIRM is a real gate.** Proceed only on explicit user confirmation of BOTH the
   analysis conclusion and the test strategy. Silence, enthusiasm, or a topic change is not
   confirmation. Sole exception: `behavior.auto_mode: true` in `.easy-coding/config.yaml`
-  AND the user asked for autonomous execution.
-- **On every transition** update the active task's `task.json` immediately (not at turn end):
-  set `status` to the new stage, append `{stage, agent, entered_at}` to `stage_history`, set
-  `last_agent` to the current agent id (`claude-code` / `codex` / `qoder`).
+  AND the user asked for autonomous execution. `auto_mode` ONLY waives this confirmation step;
+  it carries NO scope or delivery-form decision. Never cite `auto_mode` (or "the user already
+  decided in INIT") to justify narrowing scope or downgrading a code task to a report.
+- **On every transition** call the state API immediately (not at turn end):
+  `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py transition --session-file <P> --stage <STAGE> --agent <agent-id>`.
+  Do not hand-edit `status`, `stage_history`, `last_agent`, `current_task`, or session files.
 - **Hook enforcement.** The `inject-workflow-state` hook validates every stage transition
   against the state machine. If you see `[ILLEGAL-TRANSITION:...]` in the injected context,
   you MUST revert the task's status to the previous valid stage and explain why the
@@ -120,14 +143,21 @@ routing matches, and switching happens again.
 - **Task switching is allowed at any stage.** The suspended task retains its stage in
   task.json. Do not run memory flows for suspended tasks — only completed tasks get archived.
 - **Archive only after user acceptance.** VERIFICATION passing does not complete the task.
-  After the user accepts, MEMORY_SHORT → MEMORY_LONG → COMPLETE run automatically.
-- **COMPLETE closeout:** set task.json `status:"COMPLETE"`, clear `current_task` in the
-  session file, output a summary (what was done, files changed, key decisions).
+  After the user accepts, call state API transitions in order:
+  MEMORY_SHORT → MEMORY_LONG → COMPLETE. Do not jump directly from VERIFICATION to COMPLETE.
+  When transitioning to MEMORY_LONG, pass the state API snapshot to ec-memory and treat its
+  `memory_long` object as authoritative: `action == "no-op"` advances to COMPLETE without
+  reading or writing long memory; `action == "distill"` runs distillation for `trim_count`
+  older short-memory entries.
+- **COMPLETE closeout:** call the state API with `--stage COMPLETE`. The state API clears
+  session `current_task` for terminal tasks, so the next hook injection returns to Ready.
+  Then output a summary (what was done, files changed, key decisions).
 
 ## Resume and handoff
 
 Hook breadcrumbs you may receive: `[workflow-state:X]`, `[current-task:Y]`,
-`[easy-coding:handoff-from:Z]`, `[easy-coding:init-required]`.
+`[easy-coding:session-file:P]`, `[easy-coding:handoff-from:Z]`,
+`[easy-coding:init-required]`.
 
 Resuming an active task (whether from session restart, handoff, or task switch):
 1. Read `task.json` and the dev-spec sections relevant to the current stage.
@@ -154,7 +184,8 @@ switches agents by itself.
 
 Start every reply with the single Markdown blockquote status line injected by the hook,
 then a blank line. Do not render machine breadcrumbs such as `[workflow-state:...]` to the
-user. If no status line is injected (harness inactive), do not invent one.
+user. If no status line is injected (harness inactive), do not invent one. Status display is
+script-owned; skills must never construct or "fix" the status line manually.
 
 ## Boundaries
 

package/templates/main-constraint/AGENTS.md.tpl

@@ -37,18 +37,31 @@ First run `ec-init`; daily work goes through `ec-workflow`.
 
 - Stages do not skip. WAITING_CONFIRM is a real gate — implement only after the user confirms
   the plan and test strategy (unless `behavior.auto_mode` is on and the user asked for it).
+- ANALYSIS must follow template-first: read `.easy-coding/templates/dev-spec-skeleton.md` then
+  write its exact content to the task's dev-spec.md as the FIRST tool calls, then fill sections
+  incrementally via edits. Reply to the user with the complete dev-spec.md content — never a
+  summary table or custom format.
 - VERIFICATION is a hard gate: lint + typecheck + test must pass on fresh evidence, and
   coverage must match the test strategy, before a task can complete.
 - Archive (memory flow) runs only after explicit user acceptance — an unaccepted task's
   memory is dirty data.
 - NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
+- All cross-platform modules (skills, hooks, references) must use universal agent protocols.
+  Do not rely on any specific agent's proprietary conventions unless the module is explicitly
+  a platform-specific compatibility layer. Reference files use descriptive filenames (e.g.,
+  `memory-migration.md`), not platform convention names.
 
 ## Runtime contract
 
-- Workflow state lives at `{{workflow_state_path}}`; the CLI only installs files and creates
-  the project-init task — agent skills perform all project analysis.
+- Workflow state operations go through `{{platform_config_dir}}/hooks/easy_coding_state.py`;
+  do not hand-edit session files, `current_task`, task `status`, `stage_history`, or
+  `last_agent`.
+- The hook injects `[easy-coding:session-file:P]`; pass that path to the state script with
+  `--session-file <P>` when changing the current task or stage.
+- Workflow session files live at `{{workflow_state_path}}`; the CLI only installs files and
+  creates the project-init task — agent skills perform all project analysis.
 - Cross-repo references in git-tracked task artifacts use repo NAMES, never local paths.
-  Cache local paths only in `.easy-coding/state.json.repo_paths`.
+  Cache local paths only through the state script so they land on the current task.
 
 <!-- ═══ end easy-coding-harness generated ═══ -->
 

package/templates/main-constraint/CLAUDE.md.tpl

@@ -35,18 +35,31 @@ First run `/ec-init`; daily work goes through `/ec-workflow`.
 
 - Stages do not skip. WAITING_CONFIRM is a real gate — implement only after the user confirms
   the plan and test strategy (unless `behavior.auto_mode` is on and the user asked for it).
+- ANALYSIS must follow template-first: read `.easy-coding/templates/dev-spec-skeleton.md` then
+  write its exact content to the task's dev-spec.md as the FIRST tool calls, then fill sections
+  incrementally via edits. Reply to the user with the complete dev-spec.md content — never a
+  summary table or custom format.
 - VERIFICATION is a hard gate: lint + typecheck + test must pass on fresh evidence, and
   coverage must match the test strategy, before a task can complete.
 - Archive (memory flow) runs only after explicit user acceptance — an unaccepted task's
   memory is dirty data.
 - NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
+- All cross-platform modules (skills, hooks, references) must use universal agent protocols.
+  Do not rely on any specific agent's proprietary conventions unless the module is explicitly
+  a platform-specific compatibility layer. Reference files use descriptive filenames (e.g.,
+  `memory-migration.md`), not platform convention names.
 
 ## Runtime contract
 
-- Workflow state lives at `{{workflow_state_path}}`; the CLI only installs files and creates
-  the project-init task — agent skills perform all project analysis.
+- Workflow state operations go through `{{platform_config_dir}}/hooks/easy_coding_state.py`;
+  do not hand-edit session files, `current_task`, task `status`, `stage_history`, or
+  `last_agent`.
+- The hook injects `[easy-coding:session-file:P]`; pass that path to the state script with
+  `--session-file <P>` when changing the current task or stage.
+- Workflow session files live at `{{workflow_state_path}}`; the CLI only installs files and
+  creates the project-init task — agent skills perform all project analysis.
 - Cross-repo references in git-tracked task artifacts use repo NAMES, never local paths.
-  Cache local paths only in `.easy-coding/state.json.repo_paths`.
+  Cache local paths only through the state script so they land on the current task.
 
 <!-- ═══ end easy-coding-harness generated ═══ -->
 

package/templates/runtime/memory/SHORT_MEMORY_TEMPLATE.md

@@ -0,0 +1,75 @@
+---
+memory_schema: 2
+id: SM-YYYYMMDD-001
+date: YYYY-MM-DD
+task_type: feature | bugfix | refactor | perf | doc | workflow
+project_mode: startup | iteration
+domain:
+  - "{business domain or module}"
+tags:
+  - "{keyword}"
+related_files:
+  - "{key file or module}"
+commit: none
+verification: passed | partial | not_run
+memory_value: business | technical | both | none
+target_long: BUSINESS | TECHNICAL | BOTH | NONE
+---
+
+# Short Memory Template
+
+> This template defines the format for files under `.easy-coding/memory/short/`.
+> File naming convention: `{NNN}_{YYYYMMDD}_{smart_name}.md`
+> Short memories are immutable after creation — they serve as a sliding window of recent
+> details and a buffer for long-term distillation candidates.
+> When short memories reach the threshold (default 10), the newest 5 are kept as recent
+> context; older entries are distillation candidates for long-term memory.
+> Sorting: by frontmatter `date` ascending; if date is missing or tied, by filename prefix
+> number ascending; then by filename ascending.
+
+## Task Summary
+
+- Goal: {the actual problem solved}
+- Scope: {modules, pages, interfaces, or files involved}
+- Result: {completed / partially completed / not completed, with reasons}
+- Key Constraints: {encoding, compatibility, interface, spec, or user-specified constraints; "none" if none}
+
+## Execution Evidence
+
+| Type | Content |
+|---|---|
+| Key Files | {file or module list; "none" if none} |
+| Verification Commands | {test / build / lint commands and results; explain if not run} |
+| Manual Acceptance | {key behaviors checked; "none" if none} |
+| Commit Info | {commit hash; "none" if not committed} |
+
+## Business Memory Candidates
+
+> Only record business facts with future reuse value. Write "none" if none.
+
+- Concepts / Field Semantics: {concepts, fields, enums, state meanings}
+- Workflows / State Transitions: {chain steps, pre/post conditions, exception branches}
+- Business Rules / Compatibility: {admission criteria, decision basis, grayscale or legacy reasons}
+- Upstream/Downstream Contracts: {producers, consumers, interface or message fields}
+- Business Troubleshooting: {common misdiagnosis, priority check paths}
+
+## Technical Memory Candidates
+
+> Only record engineering facts with future reuse value. Write "none" if none.
+
+- Architecture / Interface Decisions: {module boundaries, dependency direction, interface contracts}
+- Engineering Rules / Workflows: {coding, commit, release, installation, directory boundaries}
+- Implementation Patterns / Reusable Approaches: {recommended approaches, fallback strategies, compatibility patterns}
+- Pitfalls / Fix Strategies: {root cause, fix approach, verification method}
+- Verification Experience: {test commands, environment constraints, acceptance paths}
+
+## Non-Distillation Content
+
+> Content that should NOT enter long-term memory, with reasons — prevents accidental absorption of noise.
+
+- {routine file lists / temp logs / one-time data / non-reusable implementation details; "none" if none}
+
+## Related Memories
+
+- Predecessor: {related short memory id, long-term topic, or "none"}
+- Successor: {follow-up task; "none" if none}

package/templates/runtime/memory/long/BUSINESS.md

@@ -1,14 +1,47 @@
+---
+memory_schema: 2
+memory_file: BUSINESS
+last_updated: YYYY-MM-DD
+---
+
 # Business Memory
 
-Durable business rules, product decisions, and domain context. Maintained by ec-memory
-during MEMORY_LONG; entries are distilled from short memories whose `target_long` is
-`business` or `both`.
+> Durable facts about "what the business is, why it works this way, and how upstream/downstream systems interact."
+
+## Core Concepts & Field Semantics
+
+| Concept / Field | Meaning | Applicable Scenario | Source | Status |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
+
+## Business Workflows & State Transitions
+
+| Workflow / State | Trigger | Key Steps | Exception Branches | Source | Status |
+|---|---|---|---|---|---|
+| (none) | — | — | — | — | — |
+
+## Business Rules & Compatibility Background
+
+| Rule | Applicable Scenario | Decision Basis | Impact Scope | Source | Status |
+|---|---|---|---|---|---|
+| (none) | — | — | — | — | — |
+
+## Upstream/Downstream Contracts
+
+| Contract | Producer | Consumer | Fields / Interface | Notes | Source |
+|---|---|---|---|---|---|
+| (none) | — | — | — | — | — |
+
+## Business Troubleshooting Experience
+
+| Problem | Common Misdiagnosis | Priority Checks | Fix / Handling | Source |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
 
-Entry format — one `##` section per entry:
+## Deprecated Records
 
-- Heading: `## BM-{NNN} {short title}`
-- First line: `status: active` (active | deprecated | superseded | deleted)
-- Body: the rule or decision, why it holds, and which tasks/files evidence it.
+> Audit zone — short summaries only. Not loaded into ANALYSIS context by default.
 
-Conflict priority when distilling: current code > latest user confirmation > this round's
-candidate > existing entries. Index every entry in MEMORY.md.
+| Deprecated Date | Original Summary | Reason | Replacement / Source |
+|---|---|---|---|
+| (none) | — | — | — |

package/templates/runtime/memory/long/MEMORY.md

@@ -1,3 +1,38 @@
-# Easy Coding Memory Index
+---
+memory_schema: 2
+memory_file: MEMORY
+last_updated: YYYY-MM-DD
+---
 
-Long-term memory entries are indexed here by ec-memory.
+# Long-Term Memory Index
+
+> This file is an index and navigation aid only — it does not hold detailed content.
+> Business facts go in `BUSINESS.md`; technical/architecture/engineering facts go in `TECHNICAL.md`.
+> Status values: `active / deprecated / superseded`. Default analysis reads only `active` topics.
+
+## Quick Navigation
+
+| Topic | Type | Keywords | Detail File | Status | Last Updated | Source |
+|---|---|---|---|---|---|---|
+| (none) | — | — | — | — | — | — |
+
+## Current Priority Business Domains
+
+- (none)
+
+## Current Priority Technical Domains
+
+- (none)
+
+## Reading Strategy
+
+- For business concepts, field semantics, workflows, rules, contracts, or troubleshooting → read `BUSINESS.md`.
+- For architecture decisions, interface decisions, engineering rules, patterns, pitfalls, or verification experience → read `TECHNICAL.md`.
+- Default: read only `active` topics. Read `deprecated` / `superseded` only during migration, conflict investigation, or user-requested history tracing.
+- If long-term memory conflicts with current code or the user's latest statement, trust current code and user — update memory status during the next distillation.
+
+## Migration Audit
+
+| Date | Source | Result |
+|---|---|---|
+| (none) | — | — |

package/templates/runtime/memory/long/TECHNICAL.md

@@ -1,3 +1,47 @@
+---
+memory_schema: 2
+memory_file: TECHNICAL
+last_updated: YYYY-MM-DD
+---
+
 # Technical Memory
 
-Durable architecture decisions, implementation patterns, and verification lessons live here.
+> Durable facts about "how code is organized, how engineering works, and how to avoid past pitfalls."
+
+## Architecture & Interface Decisions
+
+| Decision | Reason | Impact Scope | Source | Status |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
+
+## Engineering Rules & Workflows
+
+| Rule | Applicable Scenario | Enforcement | Source | Status |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
+
+## Implementation Patterns & Reusable Approaches
+
+| Pattern | Applicable Scenario | Recommended Approach | Anti-pattern / Caveats | Source |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
+
+## Pitfalls & Fix Strategies
+
+| Problem | Root Cause | Fix | Verification | Source |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
+
+## Verification, Release & Installation Experience
+
+| Scenario | Recommended Command / Path | Notes | Source |
+|---|---|---|---|
+| (none) | — | — | — |
+
+## Deprecated Records
+
+> Audit zone — short summaries only. Not loaded into ANALYSIS context by default.
+
+| Deprecated Date | Original Summary | Reason | Replacement / Source |
+|---|---|---|---|
+| (none) | — | — | — |

package/templates/runtime/templates/dev-spec-skeleton.md

@@ -0,0 +1,80 @@
+[阶段：ANALYSIS]
+
+## 技术方案：{任务标题}
+
+### 项目模式
+{初创项目/迭代项目}
+
+### 任务类型
+{新功能 / Bug 修复 / 重构 / 性能优化 / 前端设计实现}
+
+### 需求解析
+- **目标**：{待填写 — 真正要解决的问题}
+- **输入**：{待填写 — 用户输入 / 系统输入 / 触发条件}
+- **输出**：{待填写 — 先声明交付形态（改代码 / 出文档），再写最终交付结果。交付形态须忠于用户原始需求，不得擅自降级}
+- **边界**：{待填写 — 明确不做什么}
+
+### 现状
+- **相关代码 / 页面 / 接口 / 模块**：{待填写 — 基于实际文件与代码的现状说明}
+- **当前实现方式**：{待填写 — 现在是如何工作的}
+- **现有问题 / 缺口**：{待填写 — 为什么需要改}
+- **证据**：{待填写 — 引用的关键文件、类、页面、接口，含 file:line}
+
+### 冲突摘要
+- 需求 vs RULES：{待填写 或 "无冲突"}
+- 需求 vs ABSTRACT：{待填写 或 "无冲突"}
+- 需求 vs 现有代码：{待填写 或 "无冲突"}
+- Dev-Spec vs 现有代码：{待填写 或 "无冲突"}
+
+### 待用户决策
+- {待填写 — 影响技术路线、接口、改动范围的问题逐条列出；任何"本次不做全部 / 分批落地 / 范围或交付形态收窄"必须列入此处交由用户拍板，不得自行决定并假托既定；若无则写"无"}
+
+### 影响面分析
+- **涉及模块**：{待填写}
+- **核心类 / 页面 / 接口**：{待填写}
+- **数据库变更**：{有/无}
+- **接口变更**：{有/无}
+- **关联历史任务**：{待填写 — 相关短期记忆序号；无则"无"}
+
+### 改动范围
+> 只列真实项目源码/配置文件的改动。禁止把 `.easy-coding/` 下的 harness 产物（dev-spec / execution.jsonl / test-strategy / 记忆 / 报告等）当作改动对象。本表为空仅允许用于"用户明确要求的无代码交付形态"；代码类任务（重构/修复/功能）若此表为空，即为自我降级。
+
+| 改动文件 | 改动类型 | 文件编码 | 改动核心内容 |
+|----------|---------|---------|-------------|
+| `{文件路径}` | 新增 | 项目编码 {X}，依据：{xxx} | {核心改动} |
+| `{文件路径}` | 修改 | 保持原编码 {X} | {核心改动} |
+| `{文件路径}` | 删除 | — | {删除原因} |
+
+### 修改方案
+- **总体改法**：{待填写 — 一句话说清改哪里、怎么改}
+- **后端改动**：{待填写；不涉及则写"不涉及"}
+- **前端改动**：{待填写；不涉及则写"不涉及"}
+- **兼容处理**：{待填写 — 旧逻辑如何迁移、保留或替换}
+- **风险点**：{待填写 — 最容易出问题的位置}
+
+### 实施拆解
+
+| 单元 | 说明 | 类型 | 涉及文件 | 依赖 |
+|------|------|------|---------|------|
+| U1 | {title} | {backend/frontend/test/...} | {files} | — |
+| U2 | {title} | {type} | {files} | — |
+| U3 | {title} | {type} | {files} | U1, U2 |
+
+**执行策略**：{parallel / sequential / single}
+- 第一批（并行）：U1 {title} ｜ U2 {title}
+- 第二批（等待第一批）：U3 {title}
+（若 single：单一实施单元，主 agent 直接执行）
+
+### 测试策略
+
+| 测试点 | 级别 | 归属单元 | 方式 | 验证命令 |
+|--------|------|---------|------|---------|
+| {描述} | 必测 | U1 | 单测 | `npm test -- --filter=xxx` |
+| {描述} | 应测 | U2 | 快照 | `npm test -- --snapshot` |
+
+- **人工验收**：{待填写 — 用户需要检查的关键行为}
+- **无法验证项**：{待填写 — 无 / 说明缺失环境、数据或权限}
+
+### 风险与注意事项
+- {风险 1}
+- {风险 2}