Move completed plans in plans/active/ to plans/completed/, and add verification results.
Step 1: Find the Plan to Archive
If an argument is passed (filename or path), use it directly.
Otherwise, list all plans/active/ under .md：
ls plans/active/*.md 2>/dev/null
If there are multiple, sort by mtime and ask the user which one to choose. If there is only one, use it directly. If the directory does not exist or is empty, output "No plan to archive found" and end.
Step 2: Read the Plan Content
Read the target plan file and confirm:
- Whether it has an implementation steps section.canonical format（
/designoutput,plan_runner.pyparsed) steps are- [ ] **S<phase>.<num>** — <title>S-code entries, phases areany###header(the parser is^###\s+(.+)$, conventionally written as### Phase N — <title>, either a colon or a dash works);old plans also have## Phase X/### Step X.Yheader-style notation, both must be recognized - Whether it has
## 驗證or## Verificationsections - Whether it has a
## Industry & Standards Referencesection
List all steps in the plan as a tracking checklist, marking the completion status of each item.First capture by canonical S-code format（- [ ] **S1.1** — <title>, with the phase being the nearest ### header above it); if that fails, fall back to the old header-style format (## Phase X / ### Step X.Y）。If both capture an empty list, stop and ask the user, do not treat it as "0 steps" and continue—an empty list would make the completion rate in Step 3 meaningless.
The denominator of the completion rate is the length of this list(that is, the actual number of steps in the plan), not the number of tasks—TaskCreate does not exist on the default model (see rules/task-tracking-availability.md); using the task count as the denominator will directly zero out in a tool-less environment. If the session has a Task tool, you can additionally use TaskCreate to mirror this list.
Step 2.5: Generate the Execution Report
Check whether <plan-dir>/.plan-state/<slug>.state.json exists (<slug> is the plan filename without .md). If the plan was automatically written by the runner after all_done as <plan-dir>/.plan-state/<slug>.report.md, you can read that first to get a rough idea; but the content actually embedded in the plan must always be based on the freshly rerun report output—after all_done, every complete／skip(for example, adding a summary afterward) will rewrite that file, but other state-writing operations (such as reset) will not, so it is safest to go by the freshly generated one.
Exists: run
python3 ~/Documents/agent-skills/scripts/plan_runner.py report <plan>
Place stdout verbatiminto the plan's ## 執行摘要 section (if that section already exists, replace the whole section, do not append repeatedly), positioned before ## 驗證結果 .Do notadd --output and write it as a side file—if you use a side file, remember to move it along with the mv in Step 4; if you forget to move it, it becomes an orphan; KB ingest will also not associate the side file with the plan; the two files will then drift apart on their own.
Does not exist: in the ## 執行摘要 section, write a line "(This plan was not advanced by /plan-run; no execution record)", and continue to the next step.
Why do this before moving: state is placed in .plan-state/ Hide the directory, Step 4's mv only moves .md, after archiving the plan and state are separated, and the execution record must first be embedded into the plan itself to be preserved. The report format is invalid for parse_plan (the beginning is fixed as ### 執行摘要 without the word Phase, each phase title uses ####, and does not use - [ ] lists (the summary section and the list items under "Incomplete and Exceptions" all begin with - **<step>** ), each line of the summary begins with > quote, and the remaining lines also do not begin with whitespace or # , with the whole section wrapped under ## 執行摘要 ), and after archiving, even if the plan is re- init , no extra steps or phases will appear.
The verification table in Step 3 can directly reference the failed/skipped list under "Incomplete and Exceptions" in the report, without needing to re-check item by item.
Step 3: Supplement verification results
At the top of the plan file (immediately after --- frontmatter) add:
**狀態：✅ 完成（YYYY-MM-DD）**
Then append or update the ## 驗證結果 section, comparing item by item against the list established in Step 2:
| # | Phase/Step | Expected result | Actual result | Status |
|---|---|---|---|---|
| 1 | Phase 1: ... | ... | ... | PASS/FAIL |
FAIL items must include an explanation (whether it is an acceptable deviation or an issue to be handled).
If the plan has ## Industry & Standards Reference, compare item by item to confirm implementation status (APPLIED / PARTIAL / NOT_APPLIED, with the latter two including reasons: environmental limitations, decision changes, or omissions).
Completion rate = PASS step count / total step count:
- < 100%：Warning — there are incomplete steps; confirm whether they are known acceptable deviations
- < 80%：Block archiving — the user must be informed and asked to confirm whether to still archive
Other content (number of tests passed, any deviations or supplementary explanations) is kept in this section.
Step 4: Move files
mkdir -p plans/completed
mv plans/active/<filename>.md plans/completed/<filename>.md
After confirming the move succeeded, output:✅ 已歸檔：plans/completed/<filename>.md。The final reply must include the condensed version of the embedded execution summary: the report path on its own line (e.g.,報告：plans/completed/<filename>.md（## 執行摘要 section), for the user to open the file directly for review), the Progress line,#### 彙整 the full text of the three lists (deviations from plan / side effects / deferred to-dos), the step status table for each phase (the per-step summary quotes may be omitted), and the full text of the Step 2.5 "Incomplete and Exceptions" section — only embedding the summary into the archived .md does not count as delivery; the user must see it in this reply. For a plan judged in Step 2.5 as "no execution record", reply truthfully here with "(This plan was not advanced via /plan-run, no execution record)", and do not fabricate summary content.
Automation (optional)
If you want each ExitPlanMode to automatically save the plan to plans/active/afterward, see docs/hooks-setup.md。
Directory conventions
plans/
├── active/ # 進行中（Hook 自動存入 / /plan 手動建立）
├── completed/ # 已實作完成（/plan-archive 歸檔）
└── archived/ # 長期封存（不再參考的舊 plan）