prizmkit 1.1.191 → 1.1.193

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/bundled/VERSION.json +3 -3
  2. package/bundled/adapters/antigravity/skill-adapter.js +13 -4
  3. package/bundled/adapters/codex/skill-adapter.js +28 -8
  4. package/bundled/adapters/cursor/skill-adapter.js +13 -4
  5. package/bundled/adapters/pi/skill-adapter.js +28 -7
  6. package/bundled/dev-pipeline/.env.example +4 -12
  7. package/bundled/dev-pipeline/README.md +28 -44
  8. package/bundled/dev-pipeline/assets/feature-list-example.json +0 -1
  9. package/bundled/dev-pipeline/assets/skill-subagent-integration.md +6 -6
  10. package/bundled/dev-pipeline/prizmkit_runtime/atomic_io.py +48 -0
  11. package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +66 -23
  12. package/bundled/dev-pipeline/prizmkit_runtime/cli.py +10 -7
  13. package/bundled/dev-pipeline/prizmkit_runtime/commands.py +2 -21
  14. package/bundled/dev-pipeline/prizmkit_runtime/config.py +48 -78
  15. package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +127 -67
  16. package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +158 -462
  17. package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +102 -50
  18. package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -25
  19. package/bundled/dev-pipeline/prizmkit_runtime/paths.py +0 -6
  20. package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +47 -21
  21. package/bundled/dev-pipeline/prizmkit_runtime/processes.py +217 -156
  22. package/bundled/dev-pipeline/prizmkit_runtime/reset.py +39 -27
  23. package/bundled/dev-pipeline/prizmkit_runtime/reset_preserve.py +34 -174
  24. package/bundled/dev-pipeline/prizmkit_runtime/results.py +25 -0
  25. package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +133 -110
  26. package/bundled/dev-pipeline/prizmkit_runtime/runner_classification.py +15 -5
  27. package/bundled/dev-pipeline/prizmkit_runtime/runner_models.py +1 -95
  28. package/bundled/dev-pipeline/prizmkit_runtime/runner_prompts.py +0 -2
  29. package/bundled/dev-pipeline/prizmkit_runtime/runner_status.py +7 -2
  30. package/bundled/dev-pipeline/prizmkit_runtime/runners.py +540 -262
  31. package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +175 -135
  32. package/bundled/dev-pipeline/prizmkit_runtime/runtime_helper.py +90 -9
  33. package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +214 -133
  34. package/bundled/dev-pipeline/prizmkit_runtime/status.py +1 -3
  35. package/bundled/dev-pipeline/prizmkit_runtime/stream_progress.py +2783 -0
  36. package/bundled/dev-pipeline/prizmkit_runtime/task_checkout.py +27 -102
  37. package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +58 -4
  38. package/bundled/dev-pipeline/scripts/check-session-status.py +56 -20
  39. package/bundled/dev-pipeline/scripts/continuation.py +8 -7
  40. package/bundled/dev-pipeline/scripts/detect-stuck.py +47 -33
  41. package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +13 -16
  42. package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +20 -10
  43. package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +10 -7
  44. package/bundled/dev-pipeline/scripts/init-change-artifact.py +25 -4
  45. package/bundled/dev-pipeline/scripts/init-pipeline.py +14 -69
  46. package/bundled/dev-pipeline/scripts/parse-stream-progress.py +31 -2616
  47. package/bundled/dev-pipeline/scripts/patch-completion-notes.py +4 -24
  48. package/bundled/dev-pipeline/scripts/prompt_framework.py +85 -20
  49. package/bundled/dev-pipeline/scripts/status_common.py +591 -0
  50. package/bundled/dev-pipeline/scripts/update-bug-status.py +85 -463
  51. package/bundled/dev-pipeline/scripts/update-checkpoint.py +254 -65
  52. package/bundled/dev-pipeline/scripts/update-feature-status.py +76 -509
  53. package/bundled/dev-pipeline/scripts/utils.py +5 -12
  54. package/bundled/dev-pipeline/templates/bootstrap-tier3.md +5 -5
  55. package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +7 -0
  56. package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +7 -7
  57. package/bundled/dev-pipeline/templates/sections/artifact-manifest.md +1 -1
  58. package/bundled/dev-pipeline/templates/sections/bugfix-phase-manual-verification.md +1 -1
  59. package/bundled/dev-pipeline/templates/sections/bugfix-phase-review.md +1 -1
  60. package/bundled/dev-pipeline/templates/sections/bugfix-phase-test.md +2 -1
  61. package/bundled/dev-pipeline/templates/sections/checkpoint-system.md +1 -1
  62. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +1 -1
  63. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +2 -2
  64. package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md +2 -2
  65. package/bundled/dev-pipeline/templates/sections/phase-prizmkit-test.md +2 -1
  66. package/bundled/dev-pipeline/templates/sections/phase-review-full.md +1 -1
  67. package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +3 -6
  68. package/bundled/dev-pipeline/templates/session-status-schema.json +2 -5
  69. package/bundled/skills/_metadata.json +9 -63
  70. package/bundled/skills/app-planner/SKILL.md +32 -303
  71. package/bundled/skills/app-planner/references/app-design-guide.md +0 -4
  72. package/bundled/skills/app-planner/references/generated-plan-review.md +2 -1
  73. package/bundled/skills/app-planner/references/project-brief-guide.md +14 -0
  74. package/bundled/skills/app-planner/references/project-conventions-discovery.md +4 -6
  75. package/bundled/skills/app-planner/references/project-state-detection.md +2 -3
  76. package/bundled/skills/bug-fix-workflow/SKILL.md +1 -2
  77. package/bundled/skills/bug-fix-workflow/references/bug-diagnosis.md +4 -7
  78. package/bundled/skills/bug-planner/SKILL.md +54 -435
  79. package/bundled/skills/bug-planner/references/generated-plan-review.md +3 -2
  80. package/bundled/skills/bug-planner/references/input-formats.md +32 -0
  81. package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +4 -6
  82. package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +4 -28
  83. package/bundled/skills/feature-pipeline-launcher/SKILL.md +4 -6
  84. package/bundled/skills/feature-pipeline-launcher/references/configuration.md +4 -28
  85. package/bundled/skills/feature-planner/SKILL.md +60 -439
  86. package/bundled/skills/feature-planner/assets/planning-guide.md +1 -1
  87. package/bundled/skills/feature-planner/references/completeness-review.md +34 -0
  88. package/bundled/skills/feature-planner/references/decomposition-patterns.md +2 -2
  89. package/bundled/skills/feature-planner/references/error-recovery.md +1 -1
  90. package/bundled/skills/feature-planner/references/generated-plan-review.md +3 -2
  91. package/bundled/skills/feature-planner/references/incremental-feature-planning.md +3 -1
  92. package/bundled/skills/feature-workflow/SKILL.md +1 -2
  93. package/bundled/skills/prizmkit/SKILL.md +7 -1
  94. package/bundled/skills/prizmkit-code-review/SKILL.md +14 -6
  95. package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +7 -4
  96. package/bundled/skills/prizmkit-code-review/references/review-report-template.md +16 -0
  97. package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +58 -20
  98. package/bundled/skills/prizmkit-implement/SKILL.md +1 -1
  99. package/bundled/skills/prizmkit-init/SKILL.md +24 -127
  100. package/bundled/skills/prizmkit-init/assets/project-brief-template.md +3 -3
  101. package/bundled/skills/prizmkit-plan/SKILL.md +6 -8
  102. package/bundled/skills/prizmkit-plan/references/clarify-guide.md +1 -1
  103. package/bundled/skills/prizmkit-plan/references/independent-plan-review.md +5 -2
  104. package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +6 -5
  105. package/bundled/skills/prizmkit-prizm-docs/SKILL.md +1 -13
  106. package/bundled/skills/prizmkit-prizm-docs/references/op-update.md +1 -1
  107. package/bundled/skills/prizmkit-retrospective/SKILL.md +6 -4
  108. package/bundled/skills/prizmkit-test/SKILL.md +25 -133
  109. package/bundled/skills/prizmkit-test/references/independent-test-review.md +5 -2
  110. package/bundled/skills/prizmkit-test/references/test-coverage-model.md +6 -0
  111. package/bundled/skills/prizmkit-workflow/SKILL.md +2 -3
  112. package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +4 -3
  113. package/bundled/skills/recovery-workflow/SKILL.md +7 -7
  114. package/bundled/skills/recovery-workflow/evals/evals.json +1 -1
  115. package/bundled/skills/recovery-workflow/references/detection.md +1 -3
  116. package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py +0 -6
  117. package/bundled/templates/project-memory-template.md +1 -2
  118. package/package.json +1 -1
  119. package/src/scaffold.js +28 -7
  120. package/bundled/dev-pipeline/SCHEMA_ANALYSIS.md +0 -53
  121. package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py +0 -649
  122. package/bundled/dev-pipeline/scripts/init-refactor-pipeline.py +0 -463
  123. package/bundled/dev-pipeline/scripts/update-refactor-status.py +0 -1512
  124. package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md +0 -240
  125. package/bundled/dev-pipeline/templates/refactor-list-schema.json +0 -266
  126. package/bundled/dev-pipeline/templates/sections/refactor-critical-paths.md +0 -15
  127. package/bundled/dev-pipeline/templates/sections/refactor-mission.md +0 -9
  128. package/bundled/dev-pipeline/templates/sections/refactor-phase-commit-report.md +0 -24
  129. package/bundled/dev-pipeline/templates/sections/refactor-phase-implement.md +0 -16
  130. package/bundled/dev-pipeline/templates/sections/refactor-phase-init.md +0 -9
  131. package/bundled/dev-pipeline/templates/sections/refactor-phase-plan.md +0 -22
  132. package/bundled/dev-pipeline/templates/sections/refactor-phase-review.md +0 -19
  133. package/bundled/dev-pipeline/templates/sections/refactor-phase-test.md +0 -24
  134. package/bundled/dev-pipeline/templates/sections/refactor-reminders.md +0 -12
  135. package/bundled/dev-pipeline/templates/sections/refactor-session-context.md +0 -6
  136. package/bundled/dev-pipeline/templates/sections/refactor-task-contract.md +0 -52
  137. package/bundled/dev-pipeline/tests/conftest.py +0 -29
  138. package/bundled/dev-pipeline/tests/live_ai_cli_log_smoke.py +0 -208
  139. package/bundled/dev-pipeline/tests/test_auto_skip.py +0 -1871
  140. package/bundled/dev-pipeline/tests/test_checkpoint_state.py +0 -1314
  141. package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +0 -1712
  142. package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py +0 -627
  143. package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py +0 -478
  144. package/bundled/dev-pipeline/tests/test_python_runner_parity.py +0 -5641
  145. package/bundled/dev-pipeline/tests/test_recovery_workflow.py +0 -322
  146. package/bundled/dev-pipeline/tests/test_repository_bootstrap.py +0 -252
  147. package/bundled/dev-pipeline/tests/test_reset_modes.py +0 -1208
  148. package/bundled/dev-pipeline/tests/test_reset_preserve.py +0 -957
  149. package/bundled/dev-pipeline/tests/test_runtime_commit.py +0 -1113
  150. package/bundled/dev-pipeline/tests/test_runtime_helper.py +0 -303
  151. package/bundled/dev-pipeline/tests/test_unified_cli.py +0 -5504
  152. package/bundled/dev-pipeline/tests/test_utils.py +0 -170
  153. package/bundled/skills/feature-planner/assets/evaluation-guide.md +0 -44
  154. package/bundled/skills/refactor-pipeline-launcher/SKILL.md +0 -219
  155. package/bundled/skills/refactor-pipeline-launcher/references/configuration.md +0 -78
  156. package/bundled/skills/refactor-planner/SKILL.md +0 -467
  157. package/bundled/skills/refactor-planner/assets/planning-guide.md +0 -291
  158. package/bundled/skills/refactor-planner/references/behavior-preservation.md +0 -187
  159. package/bundled/skills/refactor-planner/references/error-recovery.md +0 -45
  160. package/bundled/skills/refactor-planner/references/fast-path.md +0 -59
  161. package/bundled/skills/refactor-planner/references/generated-plan-review.md +0 -107
  162. package/bundled/skills/refactor-planner/references/planning-phases.md +0 -172
  163. package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +0 -230
  164. package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +0 -1120
  165. package/bundled/skills/refactor-workflow/SKILL.md +0 -205
@@ -1,17 +1,11 @@
1
1
  ---
2
2
  name: "feature-planner"
3
- description: "Plan, validate, and manage features for an existing project — add or append features, reprioritize, split, summarize, and generate validated .prizmkit/plans/feature-list.json for dev-pipeline execution. Use this skill for feature scoping, incremental planning, continuing a feature plan, checking feature-list.json, or preparing pipeline input. For planning a new app from scratch, use app-planner instead."
3
+ description: "Plan, validate, and manage features and structural code refactoring for an existing project — add or append features, reprioritize, split, summarize, and generate validated .prizmkit/plans/feature-list.json for dev-pipeline execution. Use this skill for feature scoping, code refactoring, incremental planning, continuing a feature plan, checking feature-list.json, or preparing pipeline input. For planning a new app from scratch, use app-planner instead."
4
4
  ---
5
5
 
6
6
  # feature planner
7
7
 
8
- Plan deliverable features for autonomous dev-pipeline execution on existing projects. This skill creates or updates planning artifacts only:
9
- - **New Feature Set**: create an initial .prizmkit/plans/feature-list.json for a project that has code but no plan yet
10
- - **Incremental Feature Planning**: append, adjust, or reprioritize features in an existing plan
11
-
12
- Always produce a validated `.prizmkit/plans/feature-list.json` that conforms to `dev-pipeline-feature-list`.
13
-
14
- For planning a **new application from scratch** (vision, tech stack, decomposition), use `app-planner` instead.
8
+ Plan deliverable features for autonomous dev-pipeline execution on existing projects. This skill creates or updates planning artifacts only: create an initial `.prizmkit/plans/feature-list.json` (`New Feature Set`) or append/adjust/reprioritize an existing plan (`Incremental Feature Planning`) conforming to `dev-pipeline-feature-list`. For planning a **new application from scratch**, use `app-planner` instead.
15
9
 
16
10
  ## Intent-Aligned Planning Policy
17
11
 
@@ -24,415 +18,88 @@ Before proposing or finalizing feature contracts:
24
18
 
25
19
  ## Invocation Commitment (Hard Rule)
26
20
 
27
- **When the user invokes `/feature-planner`, you MUST execute the feature-planner workflow.** You must NEVER:
28
- - Decide on the user's behalf that the task "doesn't need feature-planner"
29
- - Skip feature-planner to jump directly to spec/plan/implement or any other skill
30
- - Bypass the interactive phases because you judge the task to be "simple" or "obvious"
31
-
32
- If the user's request is about planning a new app from scratch (vision, tech stack selection, app architecture), recommend `app-planner` instead and ask the user to confirm before switching.
33
-
34
- If you believe the task is better suited for a different workflow, you MUST:
35
- 1. **Explain why** you think a different path is more appropriate
36
- 2. **Ask the user explicitly** whether they want to switch or continue with feature-planner
37
- 3. **Only switch if the user confirms** — otherwise proceed with feature-planner as invoked
38
-
39
- The user chose this skill intentionally. Respect that choice.
21
+ **When the user invokes `/feature-planner`, execute this workflow.** Never skip planning phases because the task looks "simple", and never jump directly to spec/plan/implement. If another workflow (`app-planner`, etc.) fits better, explain why, ask the user explicitly, and switch only upon user confirmation.
40
22
 
41
23
  ## Scope Boundary (Hard Rule)
42
24
 
43
- **This skill is PLANNING ONLY.** It may create, append, reprioritize, validate, and review feature planning artifacts, but it must never implement source code or start execution. You must NEVER:
44
- - Create, modify, or delete source code files (*.js, *.ts, *.py, *.go, *.html, *.css, etc.)
45
- - Create project scaffolding, directories, or boilerplate
46
- - Run build/install/test commands (npm init, pip install, etc.)
47
- - Execute any implementation action beyond writing `.prizmkit/plans/feature-list.json`
48
-
49
- **Your ONLY writable outputs are:**
50
- 1. `.prizmkit/plans/feature-list.json` (`.prizmkit/plans/`)
51
- 2. Planner-owned draft state in `.prizmkit/plans/` (e.g., `feature-list.draft.json`) while it is required for deterministic writing, review repair, or explicit recovery
25
+ **This skill is PLANNING ONLY.** Never create/modify/delete source code files, scaffolding, or run build/install/test commands. **Writable outputs only:** `.prizmkit/plans/feature-list.json` and transient planner draft state `.prizmkit/plans/feature-list.draft.json`.
52
26
 
53
- **After planning is complete**, you MUST:
54
- 1. Present the summary and recommended next step (invoking `feature-pipeline-launcher` )
55
- 2. **Ask the user explicitly** whether they want to proceed to execution
56
- 3. If the user wants to adjust → continue refining `.prizmkit/plans/feature-list.json`
57
- 4. **NEVER auto-execute** the pipeline, launcher, composite workflow, or any implementation step
58
- 5. Return the validated list to the caller; only `feature-pipeline-launcher` prepares the runtime command
27
+ **After planning completes:** present the summary, recommend `feature-pipeline-launcher`, and ask whether to proceed; if adjustments are requested, continue refining the list. **NEVER auto-execute** the pipeline, launcher, composite workflow, or implementation; only `feature-pipeline-launcher` builds runtime commands.
59
28
 
60
29
  ## Draft Lifecycle (Hard Rule)
61
30
 
62
- In an ordinary successful flow, `.prizmkit/plans/feature-list.draft.json` is a private reasoning workspace: never presented as a deliverable, never given its own approval round, never retained after the batch lands. Build the batch there, validate it there, and run the entire Local Generated-Plan Review against it; the final list is written exactly once, after that review returns `PASS`, by a single `append` (existing list) or `generate` (new list). Then delete the draft immediately and report `Draft cleanup: removed`. A batch lost before it lands is regenerated from the confirmed decisions rather than recovered. Conditions that must keep a draft — explicit draft-save, interruption, a writer-rejected insert, cleanup failure — are defined in `${SKILL_DIR}/references/error-recovery.md`; name any retained path in the terminal report. For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; modifying entries this session did not create is the one case that still uses `append --replace-tail` for the exact current suffix.
31
+ In an ordinary successful flow, `.prizmkit/plans/feature-list.draft.json` is a private reasoning workspace: never presented as a deliverable, never given its own approval round, never retained after the batch lands. Build, validate, and run Local Generated-Plan Review against it; the final list is written exactly once, after that review returns `PASS`, by one `append` or `generate`. Then delete the draft immediately and report `Draft cleanup: removed`. Conditions that must keep a draft (`explicit save`, `interruption`, `writer rejection`, `cleanup failure`) are in `${SKILL_DIR}/references/error-recovery.md` (naming any retained path). For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; modifying pre-existing entries uses `append --replace-tail`.
63
32
 
64
33
  ## Fresh-Session Task Contract (Hard Rule)
65
34
 
66
- Every new or changed feature is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
67
-
68
- 1. **Self-contained contract**: The feature's `description` and `acceptance_criteria`, read together, MUST define the objective, current state, desired state, selected decisions, constraints, non-goals, relevant integrations, edge cases, and completion evidence. AI rewrite is allowed; dropping a confirmed item is not. There is no word-count upper limit and no acceptance-criteria count upper limit.
69
- 2. **Supplementary evidence only**: `user_context` is supplementary evidence only. It may preserve scoped source excerpts and purpose-tagged references, but it MUST NOT expand, replace, or contradict the contract in `description` and `acceptance_criteria`. If `user_context` were removed, a fresh execution session must still know exactly what to implement and how to prove completion.
70
- 3. **Clarify by impact, do not guess**: Ask when conflicting requirements or multiple plausible antecedents would materially change product behavior, scope, compatibility, safety, cost, or completion evidence. Resolve evidence-backed facts from project context and retain safe low-risk reversible choices as explicit assumptions rather than silently inventing user intent.
71
- 4. **Feature isolation**: In multi-feature planning, each written task contract and its supplementary evidence contain only material relevant to that feature. Repeat shared context only when it explicitly applies to every affected feature. Isolation does not mean split by module or directory. **Domain grouping**: Group by contract-bounded capability — shared domain objects, state machine, invariants, public API, and error semantics. That grouping is not the same module, directory, or written task contract in `description` and `acceptance_criteria`; independently shippable is not a split reason. Before the first user-facing feature table, merge same-domain over-split. Coverage is not one ID per complaint. Ask the user only when two groupings would materially change task boundaries.
72
-
73
- ### Artifact-Wide AI Readability
74
-
75
- - Every generated natural-language value must be a standalone domain statement. This applies to all AI-visible fields and sections, including `project_description`, `global_context`, titles, descriptions, acceptance criteria, rationales, `completion_notes`, `testing`, `user_context`, evidence and environment text, browser verification goals, comments, appendices, and parentheticals.
76
- - Machine metadata such as schema markers, stable IDs, statuses, enums, and timestamps is exempt. Natural-language metadata is not exempt.
77
- - Never emit dialogue-role or chronology labels such as `user said`, `user answered`, `original request`, `this round`, `previous discussion`, `as discussed earlier`, `用户本轮回答`, or `如前面讨论`. Never emit planning question IDs, answer tokens, planning-option recommendation markers, checkpoint provenance, or raw internal answer-map entries as domain content.
78
- - `user_context` may hold independently intelligible evidence, not transcript fragments. Rewrite every confirmed turn into direct product behavior, constraints, rationale, or verification evidence before generation.
79
-
80
- ### Conversational Context Normalization
81
-
82
- - Never persist standalone option labels such as `A`, `B`, `C`, `方案A`, or `方案B` as execution context.
83
- - Expand a selected option into its complete meaning and preserve substantive user rationale and constraints in durable prose at matching detail.
84
- - Do not emit transcript annotations such as `(original response: "...")` in final feature artifacts. Bare option labels and relative shorthand are not independently intelligible and materially useful exact wording.
85
- - Resolve relative statements such as `上面`, `这个`, `按推荐走`, `同前`, `继续这样`, `用刚才的方案`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. If more than one antecedent is plausible, ask the user for clarification; never guess.
86
- - Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization. Apply the concrete accepted recommendations, then omit the raw approval; never repeat it once per accepted recommendation.
87
- - Do not present rejected alternatives as active instructions. Retain one only when its rejection defines a necessary non-goal. Retain exact user wording only when it is independently intelligible and materially useful.
88
-
89
- ### Reference Material Handling
90
-
91
- - Every retained stable code, configuration, machine-consumed interface, or URL reference must be purpose-tagged: state why it is relevant and what the execution AI must inspect. This applies to paths and URLs in both the task contract and `user_context`.
92
- - Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`, uploaded-document paths, screenshot paths, or ad-hoc log paths in durable feature contracts. Instead, copy or normalize the task-relevant content into `description` and `acceptance_criteria`; the task must not depend on that source file still existing.
93
- - Good: `src/auth/login.ts:42-78 — inspect empty-password validation and the response-status transition`; Bad: `src/auth/login.ts:42-78` with no purpose.
94
- - For large materials such as issues, PRDs, logs, or documents, explain the purpose, preserve only task-relevant exact excerpts, and move every confirmed requirement into `description` and `acceptance_criteria`. Retain a location only when it is a stable execution-time source of truth.
95
- - Embed complete large materials only when the execution session cannot access the source and all content is genuinely required. Reference material never substitutes for the task contract.
96
-
97
- ### Good and Bad Normalization Examples
98
-
99
- - Bad: `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation` stored alone.
100
- - Bad: `Selected decision: keep saved filters account-scoped (original response: "方案B")`; the annotation still requires an unseen option list.
101
- - Good: `Selected decision: keep saved filters account-scoped and sync them through the existing preferences API`.
102
- - Good: `Selected decision: use cursor pagination with a 50-item default and preserve current sort order`.
103
- - Bad: storing or repeating `全部按照推荐` / `所有问题都按你的推荐处理` as a feature requirement; it is conversational authorization, not execution context.
104
- - Bad: attaching an entire PRD or transient PRD path only to preserve wording. Good: state the confirmed retry and idempotency behavior directly in the feature contract; retain a purpose-tagged PRD URL only when it is a stable execution-time source of truth.
105
-
106
- **Multi-feature isolation example:**
107
- - User request includes: `Feature A: add saved filters to the dashboard`, `Feature B: export filtered results as CSV`, and `Shared: preserve existing auth permissions`.
108
- - The saved-filters feature contract fully defines saved-filter behavior and includes only matching supplementary evidence plus the shared auth constraint; it MUST NOT include the CSV export request.
109
- - The CSV export feature contract fully defines export behavior and includes only matching supplementary evidence plus the shared auth constraint; it MUST NOT include the saved-filters request.
110
-
111
- ## When to Use
112
-
113
- Trigger conditions are covered by the frontmatter `description`. Do NOT use this skill when:
114
- - The user wants to plan a new app from scratch → use `app-planner`
115
- - The user only wants to run the pipeline → use `feature-pipeline-launcher`
116
- - The user is debugging/refactoring or wants to write source code directly
117
-
118
- ## Resource Loading Rules (Mandatory)
119
-
120
- 1. **Planning reference** — load before writing feature descriptions:
121
- - Read `${SKILL_DIR}/assets/planning-guide.md` for description writing standards, acceptance criteria patterns, complexity estimation, dependency rules, and contract-bounded grouping. Apply that grouping before the first user-facing feature table.
122
-
123
- 2. **Incremental planning reference** — load for incremental mode:
124
- - Read `${SKILL_DIR}/references/incremental-feature-planning.md`
125
-
126
- 3. **Load on-demand references when triggered**:
127
- - Validation errors or interrupted session → read `${SKILL_DIR}/references/error-recovery.md`
128
- - Browser interaction fields needed → read `${SKILL_DIR}/references/browser-interaction.md`
129
- - New feature set for a project (Route A) → read `${SKILL_DIR}/references/new-project-planning.md` for phase guide, quality rules, and delivery checklist
130
- - Feature decomposition from scratch → read `${SKILL_DIR}/references/decomposition-patterns.md` for common app patterns (CRUD, SaaS, Social, E-commerce)
131
- - Phase 6 completeness review → read `${SKILL_DIR}/references/completeness-review.md`
132
-
133
- 4. **Always validate output via script** — see §Output Rules for the validation command.
134
-
135
- If the script is not available, perform these manual validation checks:
136
- 1. **ID sequence**: All feature IDs are sequential (F-001, F-002, F-003, ...)
137
- 2. **No circular dependencies**: No feature depends (directly or transitively) on itself
138
- 3. **Description length**: Minimum 15 words per description (error); see §Output Rules for the recommended-length warning thresholds
139
- 4. **Dependency references**: All referenced features in dependencies exist in features array
140
- 5. **Priority enums**: All priority values are exactly "critical", "high", "medium", or "low" (case-sensitive)
141
- 6. **Status enum**: All status values are one of: pending, in_progress, completed, failed, skipped, split, auto_skipped
142
- 7. **Acceptance criteria**: At least 1 criterion per feature, each is a concrete, measurable statement
143
- 8. **Browser interaction**: If present, may include `tool` and `verify_steps`; planner should add concrete `verify_steps` when known, but the schema permits an empty object for AI runtime exploration.
144
- 9. **Complexity enum**: If present, is one of: low, medium, high, critical
145
- 10. **Model field**: If present, is a non-empty string
146
- 11. **Root schema**: Has $schema='dev-pipeline-feature-list-v1', project_name, and non-empty features array
147
-
148
- 5. **Use script output as source of truth** — if validation fails, fix and re-run until pass
149
-
150
- ## Prerequisites
151
-
152
- Before questions, check optional context files (never block if absent):
153
- - `.prizmkit/prizm-docs/root.prizm` (architecture/project context — typically created by app-planner with captured decisions)
154
- - `.prizmkit/config.json` (existing stack preferences and detected tech stack)
155
- - `.prizmkit/plans/project-brief.md` (project context from app-planner, if available)
156
- - existing `.prizmkit/plans/feature-list.json` (required for incremental mode; inspect it only through the bounded commands below)
157
- - Platform instruction file: use the `platform` field in `.prizmkit/manifest.json` as source of truth when present (`codex` → `AGENTS.md`, `cursor` → existing user-owned `AGENTS.md` when present, `antigravity` → existing user-owned `GEMINI.md` or `AGENTS.md` when present, `claude` → `CLAUDE.md`, `codebuddy` → `CODEBUDDY.md`). A comma-separated list selects those hosts; the six-name form or an older stored `all` means read every matching file. `both` is not a supported alias.
158
- - If `.prizmkit/prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure to understand the codebase layout:
159
- ```bash
160
- find . -maxdepth 2 -type d \
161
- -not -path '*/node_modules/*' -not -path '*/.git/*' \
162
- -not -path '*/dist/*' -not -path '*/build/*' \
163
- -not -path '*/__pycache__/*' -not -path '*/vendor/*' \
164
- -not -path '*/.agent/*' -not -path '*/.agents/*' -not -path '*/.codex/*' \
165
- -not -path '*/.claude/*' -not -path '*/.codebuddy/*' \
166
- -not -path '*/.cursor/*' -not -path '*/.prizmkit/*' \
167
- | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
168
- ```
169
-
170
- **Tech stack from config.json:**
171
- - If `.prizmkit/config.json` contains a `tech_stack` object, use it to pre-fill `global_context` fields in the generated `.prizmkit/plans/feature-list.json`.
172
- - Map config fields to global_context: `language`, `runtime`, `frontend_framework`, `frontend_styling`, `backend_framework`, `database`, `orm`, `testing` → `testing_strategy`, `bundler`, `project_type`.
173
- - Do NOT re-ask the user for tech stack info already present in config.json. Show detected stack and confirm.
174
-
175
- ## Global Context Population
176
-
177
- The `global_context` object in `.prizmkit/plans/feature-list.json` provides technology stack information. Populate it from `.prizmkit/config.json` if available, or ask the user during Phase 1.
178
-
179
- ### Recommended Fields by Project Type
180
-
181
- **Frontend-only projects:**
182
- - `language` (required) — e.g., "TypeScript", "JavaScript"
183
- - `frontend_framework` (required) — e.g., "React", "Vue", "Svelte"
184
- - `frontend_styling` (recommended) — e.g., "Tailwind CSS", "styled-components"
185
- - `testing_strategy` (recommended) — e.g., "Jest + React Testing Library"
186
-
187
- **Backend-only projects:**
188
- - `language` (required) — e.g., "TypeScript", "Python", "Go"
189
- - `backend_framework` (required) — e.g., "Express", "Django", "FastAPI"
190
- - `database` (required if applicable) — e.g., "PostgreSQL", "MongoDB"
191
- - `testing_strategy` (recommended) — e.g., "Jest", "pytest"
192
-
193
- **Full-stack projects (include both frontend AND backend fields):**
194
- - `language`, `frontend_framework`, `backend_framework`, `database`, `testing_strategy` (all recommended)
195
- - Additional: `frontend_styling`, `orm`, `bundler`, `runtime`
196
-
197
- All `global_context` fields are optional — including recommended fields improves downstream code generation quality. See `.prizmkit/dev-pipeline/templates/feature-list-schema.json` for the full schema definition.
198
-
199
- ## Priority and Complexity Calibration (Mandatory)
200
-
201
- Do not let planner output collapse into uniform `Priority: high` and `estimated_complexity: high`. Medium and low assignments are normal when the documented indicators fit. New framework work or multi-file work is not automatically `high` priority; the feature must satisfy the documented priority criteria independently.
202
-
203
- ### Priority Rubric
204
-
205
- | Priority | Use When | Do NOT Use Merely Because |
206
- |----------|----------|---------------------------|
207
- | `critical` | A production-blocking capability, security/compliance requirement, data-loss prevention, or release blocker with no acceptable workaround. | The item is important, large, or requested by a stakeholder. |
208
- | `high` | Core user workflow or platform capability is blocked, revenue/security/auth/data integrity is at risk, a hard deadline depends on it, or many downstream items cannot proceed without it. | The item is multi-file, framework-related, or described with urgent language but no concrete blocker. |
209
- | `medium` | Valuable planned feature, quality improvement, integration, or automation that should be scheduled soon but has a workaround or does not block core operation. | It is less exciting than another item; medium is the default for normal planned work. |
210
- | `low` | Nice-to-have, polish, documentation, cleanup, optional convenience, or isolated improvement with little user/runtime impact. | The item is small; small work can still be high only when it blocks critical outcomes. |
211
-
212
- ### Complexity Rationale Rules
213
-
214
- Assign `estimated_complexity` from concrete scope indicators, not from perceived importance. For each feature, write a short rationale using at least two relevant indicators:
215
- - affected module count and layer count
216
- - file count or expected implementation surface
217
- - API/interface or schema changes
218
- - architectural impact or new infrastructure
219
- - dependency depth and cross-feature coupling
220
- - acceptance-criteria count and edge-case breadth
221
- - test coverage and verification difficulty
222
-
223
- Use `low` for focused changes in 1 module with <=5 acceptance criteria and no public API/schema changes. Use `medium` for normal multi-file or 2-3 module work with bounded interfaces. Use `high` only when multiple concrete high indicators are present, such as 3+ modules plus public API changes, deep dependencies, weak tests, or substantial architectural risk. Use `critical` only for system-wide architectural/infrastructure changes or safety-critical work requiring the strongest orchestrator/reviewer/test guardrails.
224
-
225
- ### Required Planning Review Summary
226
-
227
- Before writing `.prizmkit/plans/feature-list.json`, show a calibration table with rationale columns:
35
+ Every new/changed feature must execute cleanly in a fresh AI session without conversation history (full rules and normalization examples live in `${SKILL_DIR}/references/completeness-review.md`):
36
+ - **Self-contained contract**: `description` + `acceptance_criteria` together define objective, current/desired state, decisions, constraints, non-goals, integrations, edge cases, and completion evidence (no word-count or criteria-count cap). `user_context` is supplementary evidence only; removing `user_context` must leave the contract complete.
37
+ - **Standalone AI readability**: write direct domain statements across all AI-visible fields; omit dialogue-role/chronology labels, question/option IDs (`方案A`/`B`), `(original response: "...")`, blanket recommendation tokens, and transient non-code paths; retain purpose-tagged code/config/interface/URL refs.
38
+ - **Clarify by impact & isolate**: ask on material ambiguity; repeat shared context only where applicable; group by contract-bounded capability and merge same-domain over-splits before presenting the feature table.
228
39
 
229
- ```
230
- ID | Title | Priority | Priority Rationale | Complexity | Complexity Rationale
231
- F-001 | Auth outage recovery | high | Core login blocked; no workaround | high | Auth API + middleware + weak tests
232
- F-002 | Export polish option | medium | Useful workflow; not blocking | medium | UI + API parameter; bounded tests
233
- F-003 | Tooltip copy update | low | Cosmetic clarity only | low | One component; no interface change
234
- ```
40
+ ## Prerequisites & Reference Loading
235
41
 
236
- Anti-pattern rule: do not assign every generated item `Priority: high` and `Complexity: high` unless each item independently satisfies the documented high criteria and its rationale names those criteria. In feature JSON this means `estimated_complexity: high`; in user-facing review summaries label the column `Complexity`.
42
+ 1. Load `${SKILL_DIR}/assets/planning-guide.md` before writing descriptions; load `${SKILL_DIR}/references/incremental-feature-planning.md` for incremental mode, `${SKILL_DIR}/references/completeness-review.md` for Phase 6, and `${SKILL_DIR}/references/new-project-planning.md` / `decomposition-patterns.md` / `browser-interaction.md` / `error-recovery.md` when triggered.
43
+ 2. Check optional workspace files (never block if absent): `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json` (pre-fill `global_context` from `tech_stack`: `language`, `frontend_framework`, `frontend_styling`, `backend_framework`, `database`, `orm`, `testing` → `testing_strategy`, `bundler`, `runtime`; confirm detected stack instead of re-asking), `.prizmkit/plans/project-brief.md`, existing `.prizmkit/plans/feature-list.json` (bounded commands only), and the current host's conventional project-local instruction file when present (non-exhaustive examples: `AGENTS.md`, `CLAUDE.md`, `CODEBUDDY.md`, `.pi/APPEND_SYSTEM.md`) for project conventions and architecture decisions. If `root.prizm` is absent, scan shallow project directories excluding `.git`, `.prizmkit`, platform dirs, and build/vendor folders.
44
+ 3. Always validate via script (`validate-and-generate.py`); use its manual checklist fallback in `references/completeness-review.md` only if unavailable.
237
45
 
238
- ---
239
46
  ## Bounded Existing-List Context (Hard Rule)
240
- For ordinary incremental planning, NEVER read the complete existing `.prizmkit/plans/feature-list.json` into AI context and NEVER perform default full-history keyword search.
241
- 1. Run `python3 ${SKILL_DIR}/scripts/validate-and-generate.py context --input .prizmkit/plans/feature-list.json`; consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and the five most recently appended top-level tasks as `{id, description}` pairs (or all available tasks when fewer than five exist).
242
- 2. Inspect those pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
243
- 3. Incorporate only the minimum exact information whose omission would make scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect. Reject vague `related to F-123` text and whole-description copying; add an old ID to `dependencies` only when it is a real execution prerequisite.
244
- 4. Only for an explicitly identified old ID or a validation error, run `python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-NNN`.
245
- 5. For append-only planning, write `.prizmkit/plans/feature-list.draft.json` with exactly one root field, `features`, containing non-empty unchanged-schema items. This bounded draft is a private reasoning workspace and the review target, not a user approval artifact or a deliverable. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical features.
246
- 6. After consequential decisions and the pre-generation gate pass, write the batch to the additions-only draft with the `context` IDs and check merge feasibility without writing: `python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --dry-run`. Do not ask for separate user approval merely to promote the draft into the final list. The dry run applies the same base, ID, dependency, and DAG checks the real insert will, so a `PASS` review is a promise the insert keeps. Run the real `append` once, after §Local Generated-Plan Review Gate returns `PASS`, then follow §Draft Lifecycle. `generate` remains the initial-plan/full-rewrite path.
247
- ## Scenario Routing
248
- Classify user intent first:
249
-
250
- ### Route A: Initial Feature Set for Existing/App-Planned Project
251
- Use when source code or app-level context already exists but no `.prizmkit/plans/feature-list.json` exists yet. If the user is still defining vision, stack, or product brief from scratch, switch to `app-planner` only after confirmation.
252
-
253
- Actions:
254
- 1. Understand the existing codebase and what's already implemented
255
- 2. Run interactive planning phases to identify needed features
256
- 3. Generate initial `.prizmkit/plans/feature-list.json`
257
-
258
- ### Route B: Incremental Feature Planning
259
- Use when user already has a `.prizmkit/plans/feature-list.json` and wants to add or adjust features.
260
-
261
- Actions:
262
- 1. Load `${SKILL_DIR}/references/incremental-feature-planning.md`
263
- 2. Run the bounded `context` command from §Bounded Existing-List Context (if the file is missing, ask whether to start a new plan); do not read the complete list
264
- 3. Append features with the returned next sequential `F-NNN` IDs through the additions-only `append` command
265
- 4. Preserve confirmed project conventions and self-contained task quality without forcing unrelated recent history into new features
266
47
 
267
- ### Route C: Validate Existing Plan
268
- Use when the user asks to check or validate an existing plan without adding or changing features.
269
-
270
- Run:
271
- ```bash
272
- python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input .prizmkit/plans/feature-list.json
273
- ```
274
-
275
- Report the script result. Do not enter generation, implementation, or launcher flows unless the user separately requests a plan change or command construction.
276
-
277
- ### Route D: Summarize Existing Plan
278
- Use when the user asks to list or summarize the existing feature plan without changing it.
48
+ For ordinary incremental planning, NEVER read the complete existing `.prizmkit/plans/feature-list.json` into AI context and NEVER perform default full-history keyword search.
49
+ 1. Run bounded context first (consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and the five most recently appended top-level tasks as `{id, description}` pairs):
50
+ ```bash
51
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py context --input .prizmkit/plans/feature-list.json
52
+ ```
53
+ 2. Inspect those pairs only for material continuation, duplication, conflict, shared public contract, or real prerequisite (`references/incremental-feature-planning.md`). Load an old task (`show --id F-NNN`) only for an explicit ID or validation error.
54
+ 3. Write only `{ "features": [...] }` to `.prizmkit/plans/feature-list.draft.json`, verify merge safety without writing via `--dry-run`, pass Local Generated-Plan Review (`PASS`), then run `append` once.
279
55
 
280
- Run:
281
- ```bash
282
- python3 ${SKILL_DIR}/scripts/validate-and-generate.py summary --input .prizmkit/plans/feature-list.json
283
- ```
56
+ ## Scenario Routing
284
57
 
285
- Return the generated summary and stop.
58
+ - **Route A — Initial Feature Set**: code/brief exists, no `feature-list.json` → understand codebase → run interactive phases → `generate`.
59
+ - **Route B — Incremental**: `feature-list.json` exists → follow `${SKILL_DIR}/references/incremental-feature-planning.md` + bounded `context` → draft additions → `append`.
60
+ - **Route C — Validate**: run `validate-and-generate.py validate --input .prizmkit/plans/feature-list.json` and report result (no generation/launch).
61
+ - **Route D — Summarize**: run `validate-and-generate.py summary --input .prizmkit/plans/feature-list.json` and return it.
286
62
 
287
63
  ## Core Workflow
288
64
 
289
- Execute the planning workflow in conversation mode with mandatory checkpoints:
290
-
291
65
  ### Interactive Phases
292
- 1. Clarify scope and goals
293
- 1.1 **Requirement clarification** — establish the intent baseline, inspect project evidence, and classify uncertainty by decision impact. Ask about consequential ambiguity in goals, external behavior, scope, non-goals, compatibility, safety, cost, or irreversible choices; label recommendations and group related questions unless answers are dependent. Proceed when consequential ambiguity is resolved and any low-risk reversible assumptions are explicit—not when every unknown has been eliminated.
294
- 1.2 **Collect reference materials** — **Upfront Material Detection (Hard Rule)**: If the user has already provided materials (file paths, URLs, rules, specifications, code snippets) in the same message that invoked this skill: (a) Acknowledge what was received: "I received the following materials: [list]"; (b) Read/fetch all provided materials immediately; (c) You MUST still ask: "Are there any additional materials you'd like to provide?"; (d) NEVER skip this collection step just because the user already provided some materials.
295
-
296
- If the user has NOT provided any materials upfront, explicitly ask whether they have any supplementary materials for you to review. Present this as a single prompt covering all material types:
297
- > "Do you have any reference materials I should review before planning? This can include:
298
- > - **Code paths** — files or directories I should read to understand existing implementation
299
- > - **Documents** — design docs, PRDs, API specs, architecture proposals, or internal wiki pages
300
- > - **Knowledge docs** — `.prizmkit/prizm-docs/` files, README files, or project-specific documentation
301
- > - **Images** — wireframes, mockups, architecture diagrams, or screenshots
302
- > - **Web links** — reference implementations, API documentation pages, or relevant articles
303
- >
304
- > If none, we'll proceed with what's available in the codebase."
305
-
306
- If the user provides materials, require or infer only when unambiguous a task-specific purpose for each material; otherwise ask what the execution AI should inspect. Read/fetch them before Phase 2. For web links, retrieve and analyze the relevant content; for images, analyze the relevant visual evidence. Material ingestion follows the same durability rule as final output: copy or normalize task-relevant requirements and exact evidence, omit transient non-code paths, and retain only purpose-tagged stable execution-time sources. Do not copy complete large materials merely to preserve them.
307
- 2. Confirm constraints and existing architecture
308
- 3. Propose feature set with dependencies. **Contract-bounded over-split (Hard Rule)** — Before the first user-facing feature table, merge items that share one contract-bounded capability. Walkthrough notes, complaints, empty states, and button copy default into few capabilities; one complaint per row is forbidden. Long description, many acceptance criteria, and changing frontend and backend together are not split reasons. Split into additional top-level features only when implementation plus verification clearly cannot finish in one existing headless session, typically after two or more heavy capability seams. Ask the user only when two groupings would materially change task boundaries. Present the contract-grained table and note which complaints landed in which item. Users confirm coverage and contract cuts, not a UI-part menu.
309
- 4. Refine descriptions and acceptance criteria
310
- 4.1 **Per-feature clarification** — for each feature, ask when multiple interpretations of behavior, acceptance criteria, scope, non-goals, material integrations, or completion evidence would materially change the contract. Resolve evidence-backed details from project context, label low-risk reversible assumptions, and reject conversational shorthand that requires an unseen question, recommendation, or option list. Do not force user confirmation for unconstrained implementation details that a fresh session can safely decide and verify.
311
- 4.2 **Browser interaction** (mandatory for fullstack/frontend projects) — see §Browser Interaction Planning below. Qualifying features get `browser_interaction` by default. Only confirm with the user as a batch summary; do NOT ask per-feature.
312
- 5. Verify DAG/order/priorities and show the mandatory priority/complexity calibration table with short rationales for every item
313
- 6. Run the pre-generation Headless Context Completeness Gate (see §Pre-Generation Completeness Review below)
314
- 7. Build the batch in `.prizmkit/plans/feature-list.draft.json` with the `context` IDs; write no final list yet
315
- 8. Apply default testing strategy (see §Testing Defaults below)
316
- 9. Validate the draft batch and fix until pass, then run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below) against it; apply accepted fixes to the draft, revalidate, and repeat until `PASS`
317
- 11. Insert the batch once (`append`, or `generate` for a new list), complete §Draft Lifecycle cleanup, and summarize the final feature table with the inserted IDs, local review verdict, writer result, and cleanup result
318
-
319
- ### Checkpoints (Mandatory Gates)
320
-
321
- Checkpoints catch cascading errors early — skipping one means the next phase builds on unvalidated assumptions, which compounds into much harder debugging later.
322
-
323
- | Checkpoint | Artifact/State | Criteria | Phase |
324
- |-----------|----------------|----------|-------|
325
- | **CP-FP-1** | Scope Confirmed | User confirmed what features to plan and context understood | 1 |
326
- | **CP-FP-2** | Feature Proposals | Feature set with titles+deps identified after same-domain over-split (pre-validation); first table is contract-grained | 3-5 |
327
- | **CP-FP-3** | DAG Validity | No cycles, dependencies resolved (validation dry-run) | 5 |
328
- | **CP-FP-3.1** | Browser Interaction Applied | Qualifying features have `browser_interaction` field; user confirmed or opted out | 4 |
329
- | **CP-FP-3.2** | Testing Defaults Applied | All features have appropriate testing expectations | 7 |
330
- | **CP-FP-3.3** | Completeness Review Passed | Every new or changed feature passes fresh-session simulation from `description` and `acceptance_criteria` without conversation history or `user_context` | 6 |
331
- | **CP-FP-4** | Draft Batch Ready | Additions-only or complete draft holds the whole batch with `context` IDs; final list still untouched | 7-8 |
332
- | **CP-FP-5** | Draft Validation Pass | Draft validation plus the merge dry run return `"valid": true` with zero errors | 9 |
333
- | **CP-FP-6** | Reviewed, Then Inserted Once | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only the draft batch, applied accepted fixes through the draft, revalidated, returned `PASS`, then ran exactly one `append`/`generate` whose `appended_ids` match the batch, and removed the draft | 10-11 |
334
-
335
- **Resume Detection**: If existing artifacts are found, read `${SKILL_DIR}/references/error-recovery.md` §Resume Support for checkpoint-based resumption.
336
-
337
- ## Pre-Generation Completeness Review (Phase 6)
338
-
339
- Before generating `.prizmkit/plans/feature-list.json`, review the full feature set holistically.
340
-
341
- → Read `${SKILL_DIR}/references/completeness-review.md` for the full review process (description adequacy scan, cross-feature completeness check, user presentation, and interactive supplementation).
342
-
343
- This is the mandatory Headless Context Completeness Gate. It reviews every new or changed feature as if the reviewer has never seen the planning conversation and must return `NEEDS_FIXES` when any required artifact-alone question cannot be answered. It does not bulk-rewrite unchanged historical features. Thin descriptions here cost minutes to fix; misimplemented features downstream cost hours.
66
+ 1. **Clarify scope & goals (CP-FP-1)**
67
+ 1.1 **Intent & uncertainty**: establish intent baseline, resolve from project evidence, group consequential questions with labeled recommendations, and proceed once consequential ambiguity is resolved and low-risk reversible assumptions are explicit.
68
+ 1.2 **Upfront Material Detection (Hard Rule)**: if user supplied materials (paths, URLs, specs, code), acknowledge ("I received the following materials: [list]"), read/fetch all immediately, AND still ask "Are there any additional materials you'd like to provide?". If none supplied yet, ask once covering code paths, design docs/PRDs, `.prizmkit/prizm-docs/`/READMEs, images, and web links. Normalize task-relevant evidence cleanly: Material ingestion follows the same durability rule as final output (retain purpose-tagged stable refs/excerpts, omit transient non-code paths).
69
+ 2. **Confirm constraints & architecture** from `root.prizm`/project context and populate `global_context`.
70
+ 3. **Contract-bounded feature table (CP-FP-2)**: merge items sharing one contract-bounded capability before showing the first user-facing table (complaints/walkthrough notes/UI states are not one ID per row; split only at heavy capability seams exceeding one headless session).
71
+ 4. **Refine contracts & `browser_interaction` (CP-FP-3.1)**: run per-feature clarification for consequential behavioral/scope/integration/evidence ambiguity (never force confirmation on safe unconstrained internals); apply Phase 4.2 browser defaults below.
72
+ 5. **DAG & Priority/Complexity Calibration (CP-FP-3)**: prevent uniform `high/high` collapse (follow the rubric and `ID | Title | Priority | Priority Rationale | Complexity | Complexity Rationale` table in `${SKILL_DIR}/references/completeness-review.md`).
73
+ 6. **Headless Context Completeness Gate (CP-FP-3.3, Phase 6)**: read `${SKILL_DIR}/references/completeness-review.md` and run the mandatory Pre-Generation Completeness Review on every new/changed feature (`description` + `acceptance_criteria` must answer all 12 questions alone; return `NEEDS_FIXES` and fix before proceeding; do not bulk-rewrite untouched history).
74
+ 7. **Draft batch & testing defaults (CP-FP-3.2, CP-FP-4)**: write `.prizmkit/plans/feature-list.draft.json` using `context` IDs and apply Phase 8 testing expectations.
75
+ 8. **Validate & Local Generated-Plan Review Gate (CP-FP-5 → CP-FP-6)**: run draft validation + `--dry-run`, run §Local Generated-Plan Review Gate until `PASS`, then insert once (`append` or `generate`), complete §Draft Lifecycle cleanup, and present handoff.
76
+
77
+ **Checkpoints**: **CP-FP-1** Scope Confirmed (1) · **CP-FP-2** Contract-Grained Proposals (3-5) · **CP-FP-3** DAG Validity (5) · **CP-FP-3.1** Browser Interaction (4) · **CP-FP-3.2** Testing Defaults (7) · **CP-FP-3.3** Completeness Review Passed (6) · **CP-FP-4** Draft Batch Ready (7-8) · **CP-FP-5** Draft Validation + Dry-Run Pass (9) · **CP-FP-6** Reviewed, Then Inserted Once (`generated-plan-review.md` reviewed draft batch → accepted fixes → revalidated → `PASS` → single `append`/`generate` matching `appended_ids` → draft removed; 10-11). If resuming prior artifacts, read `${SKILL_DIR}/references/error-recovery.md`.
344
78
 
345
79
  ## Fast Path (Simple Incremental)
346
80
 
347
- For simple incremental planning, skip detailed Phase 2-3 analysis:
348
-
349
- ### Eligibility Criteria (ALL must apply)
350
- - **Incremental mode only** — not new feature set
351
- - **Adding 1-2 features max** to existing plan
352
- - **Each feature**: ≤5 acceptance criteria, <100 words description
353
- - **Dependencies**: depends on ≤2 existing features (no chains)
354
- - **Complexity**: "low" or "medium" only
355
- - **No architectural changes** to existing tech stack
356
-
357
- ### Fast Path Workflow
358
- 1. Run the bounded `context` command from §Bounded Existing-List Context and confirm scope without reading the complete historical list
359
- 2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
360
-
361
- ```
362
- AskUserQuestion:
363
- question: "This qualifies for fast-path (simple incremental addition). How would you like to proceed?"
364
- header: "Approach"
365
- options:
366
- - label: "Fast-path"
367
- description: "Skip detailed Phase 2-3 analysis, draft features directly and add to feature-list.json"
368
- - label: "Full workflow"
369
- description: "Use the complete planning workflow with detailed analysis"
370
- ```
371
-
372
- - **Fast-path** → Continue with fast-path workflow below
373
- - **Full workflow** → Exit fast path, use full workflow from Phase 2
374
- - If the user wants direct implementation instead of planning, exit the planner flow after explicit confirmation and recommend `/prizmkit-plan`; do not invoke implementation from inside `feature-planner`.
375
-
376
- **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
377
- 3. Generate next sequential feature IDs
378
- 4. Draft features (title + description + acceptance_criteria + dependencies)
379
- 5. Run the mandatory pre-generation Headless Context Completeness Gate from Phase 6 on every drafted feature; repair the draft until each returns `PASS`.
380
- 6. Write the additions-only draft as internal input — no second draft-approval pause — and check merge feasibility without writing:
381
- ```bash
382
- python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --dry-run
383
- ```
384
- 7. If valid → run the mandatory Local Generated-Plan Review Gate on the draft, insert once with `append`, complete §Draft Lifecycle cleanup, then present the final written result and recommend the next step
385
- 8. If invalid → apply fixes to the additions-only draft and re-run the dry run (max 2 attempts, then escalate to full workflow)
81
+ Eligible only when ALL apply: incremental mode, `1-2` features max, each `<=5` criteria and `<100` words, `<=2` existing deps (no chains), `low`/`medium` complexity, no stack changes.
82
+ 1. Run bounded `context` without reading full history.
83
+ 2. **User confirmation (mandatory)** — present `AskUserQuestion` with clickable options `"Fast-path"` and `"Full workflow"` (never plain text; if user wants direct coding, exit on confirmation and recommend `/prizmkit-plan`).
84
+ 3. Assign sequential IDs, draft features, and Run the mandatory pre-generation Headless Context Completeness Gate from Phase 6 on every drafted feature until each returns `PASS`.
85
+ 4. Write additions-only draft and check merge feasibility (`--dry-run`). If invalid, fix the additions-only draft and re-run the dry run (max 2 attempts, then escalate to full workflow).
86
+ 5. Run §Local Generated-Plan Review Gate on the draft (`PASS`), insert once with `append`, complete §Draft Lifecycle cleanup, and present handoff.
386
87
 
387
88
  ## Browser Interaction Planning
388
89
 
389
- For fullstack/frontend projects, qualifying features get `browser_interaction` **by default**.
390
-
391
- ### Auto-Detection Rule
392
-
393
- A feature **qualifies** when ALL true:
394
- 1. `global_context.frontend_framework` exists
395
- 2. The feature's `acceptance_criteria` contain UI-related keywords: click, button, modal, page, form, display, navigate, tab, input, opens, shows, renders, visible, redirect, download, upload, preview, select, toggle, dropdown, popup, toast, menu
396
-
397
- A feature is **exempt** when ANY true:
398
- - Backend-only (API endpoints, database migrations, no UI criteria)
399
- - Config/setup/infrastructure
400
- - `status: "completed"` (already implemented)
90
+ Qualifying features (`global_context.frontend_framework` present + UI criteria, excluding backend/config/`completed`) receive `browser_interaction` by default:
91
+ 1. **Ask user for browser tool preference (Mandatory)** via `AskUserQuestion` using `${SKILL_DIR}/references/browser-interaction.md` §Browser Tool Selection (`auto` / `playwright-cli` / `opencli`) before generating fields.
92
+ 2. Auto-generate `browser_interaction` (`opencli` for OAuth/SSO/login state, `playwright-cli` for local UI), show a batch summary (allow per-feature opt-out/override), and follow `${SKILL_DIR}/references/browser-interaction.md` field rules.
401
93
 
402
- ### Default Behavior (Phase 4.2)
94
+ ## Output Rules & Local Generated-Plan Review Gate
403
95
 
404
- 1. **Ask user for browser tool preference (Mandatory)**: Before generating any `browser_interaction` fields, use `AskUserQuestion` to ask which browser verification tool to use as the project default. Read `${SKILL_DIR}/references/browser-interaction.md` §Browser Tool Selection for the exact question format and options (`auto`/`playwright-cli`/`opencli`). Do NOT skip this step or assume a default without asking.
405
- 2. **Auto-generate** `browser_interaction` for ALL qualifying features. Read `${SKILL_DIR}/references/browser-interaction.md` for the object format, field rules, and per-feature `tool` override logic.
406
- 3. **Tool assignment per feature**: Use the user's chosen default. Override to `"opencli"` when the feature involves OAuth/SSO callbacks, third-party dashboard verification, or requires real login state. Override to `"playwright-cli"` when the feature is purely local UI (forms, components, routing). If user chose `"auto"`, AI assigns per-feature based on these rules.
407
- 4. **Present a summary** to the user showing which features received `browser_interaction` (including the `tool` value for each).
408
- 5. **User can opt-OUT** specific features or override the `tool` choice.
96
+ Write via `generate` (complete new draft) or `append` (additions-only batch) — **never hand-write `.prizmkit/plans/feature-list.json`**:
97
+ - Schema `$schema: "dev-pipeline-feature-list-v1"`, sequential `F-NNN`, acyclic DAG, `priority: "critical"|"high"|"medium"|"low"`, `status: "pending"`, English titles for slugs, min 15 words/description (30/50/80/100 recommended for low/medium/high/critical), `estimated_complexity` for scope/risk summaries only.
98
+ - Note: the final list is written exactly once, after that review returns `PASS` (`append --dry-run` validates without writing beforehand).
409
99
 
410
- ## Output Rules
411
-
412
- `.prizmkit/plans/feature-list.json` must conform to `.prizmkit/dev-pipeline/templates/feature-list-schema.json` (`$schema` = `dev-pipeline-feature-list-v1`).
413
-
414
- Key requirements:
415
- - non-empty `features` array
416
- - sequential feature IDs (`F-001`, `F-002`, ...)
417
- - valid dependency DAG (no cycles, all referenced IDs exist)
418
- - `priority`: `"critical"`, `"high"`, `"medium"`, or `"low"` (string, NOT numeric)
419
- - new items default `status: "pending"`
420
- - English feature titles for stable slug generation
421
- - `browser_interaction` auto-generated for qualifying frontend features (with `tool` selection: `auto`/`playwright-cli`/`opencli`)
422
- - descriptions: minimum 15 words (error), recommended minimum 30/50/80/100+ for low/medium/high/critical (warning). There is no word-count upper limit and no acceptance-criteria count upper limit. Keep `description` plus `acceptance_criteria` complete without `user_context`.
423
- - `estimated_complexity` records implementation scope and verification risk for planning summaries, ordering, and downstream context. It does not select a fixed agent count or named review topology; every normal feature session receives the runtime's full guidance.
424
-
425
- **IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
426
- - Initial plan or explicit full-list rewrite: write the complete draft and use `generate`:
427
- ```bash
428
- python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
429
- ```
430
- - Ordinary incremental append: follow §Bounded Existing-List Context, write only the additions-only `features` object, and use `append`:
431
- ```bash
432
- python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
433
- ```
434
-
435
- `generate` fills root defaults for complete drafts. `append` preserves root metadata and historical features, defaults missing new statuses, validates the merged full list, and writes only after validation passes. In ordinary incremental flow the draft is not a second approval checkpoint, but it is the review target, so the real `append` runs once, after the Local Generated-Plan Review returns `PASS`; use `append --dry-run` for every earlier merged check because it validates without writing. If the writer rejects the batch, fix its source draft and retry — a rejection never leaves a partial final list. Then follow §Draft Lifecycle.
100
+ ```bash
101
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
102
+ ```
436
103
 
437
104
  ## Local Generated-Plan Review Gate
438
105
 
@@ -440,56 +107,10 @@ Run this gate after the batch is written to the draft and passes draft validatio
440
107
 
441
108
  Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the draft directly, reading `.prizmkit` artifacts from disk rather than from `git status` or `git diff`, because those files may be gitignored. Use bounded `context` and explicit-ID `show` only for already-committed entries whose contract or dependency semantics a reviewed item relies on; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed feature. Keep the review planning-only: apply accepted findings to the draft, re-run draft validation and the merge dry run, and repeat until it returns `PASS`. Only then insert once, complete §Draft Lifecycle cleanup, and present the final written result. If the insert is rejected after `PASS`, nothing landed: fix the draft, re-run validation and the dry run, and re-review the changed entries.
442
109
 
443
- ## Testing Defaults (Phase 8)
444
-
445
- Set default testing-related fields for each feature. The user can opt out of generated testing expectations.
446
-
447
- | Priority | Testing expectation | Rationale |
448
- |----------|---------------------|-----------|
449
- | high | Require scoped tests and review-gate evidence | Higher-risk feature behavior needs stronger verification. |
450
- | medium | Require focused tests for changed public behavior | Normal changes need meaningful boundary coverage. |
451
- | low | Require the smallest relevant verification | Low-risk changes should stay lightweight. |
452
-
453
- For frontend features with `browser_interaction`, browser verification is enabled by default. The `tool` field uses the user's choice from the mandatory browser tool question in Phase 4.2 (see §Browser Interaction Planning → Default Behavior).
454
-
455
- Present a consolidated testing summary table at Phase 8, then ask for confirmation.
456
-
457
- ## Next-Step Execution Policy (after planning)
458
-
459
- Recommend invoking `feature-pipeline-launcher` to configure and launch the dev-pipeline. Do NOT recommend running shell scripts directly — that is the launcher's responsibility. Follow the post-planning handoff in §Scope Boundary (never auto-execute).
460
-
461
- ## Error Recovery & Resume
462
-
463
- If validation fails or a session is interrupted → read `${SKILL_DIR}/references/error-recovery.md` for the full error type table, decision tree, retry logic, and checkpoint-based resume support.
464
-
465
- Key behaviors: continue informational warnings without a draft-promotion pause; clarify consequential warnings; group critical errors and retry safe fixes at most three times; resume interrupted state from actual artifacts; always write the final list at project-root `.prizmkit/plans/feature-list.json`.
466
-
467
- ## Session Exit Gate
468
-
469
- Prevent accidental session exit without deliverable completion.
470
-
471
- ### Trigger Conditions
472
- Activate when ALL true:
473
- - User expressed intent to produce .prizmkit/plans/feature-list.json
474
- - Current phase < Phase 7
475
- - No valid `.prizmkit/plans/feature-list.json` written in this session
476
-
477
- ### Gate Behavior
478
- When the session appears to be ending:
479
- 1. **Remind**: "You set out to produce `.prizmkit/plans/feature-list.json` but we haven't completed it yet."
480
- 2. Use `AskUserQuestion` with one question:
481
- - **Continue to completion (Recommended)** — resume from current phase
482
- - **Save draft & exit** — write current progress as `.prizmkit/plans/feature-list.draft.json` and retain it as explicit recovery state; terminal cleanup does not apply until planning resumes and completes
483
- - **Abandon** — exit without saving
484
-
485
- ## Handoff Message Template
486
-
487
- After the batch is inserted, report:
488
- 1. Output file path
489
- 2. Total features + newly added features
490
- 3. Dependency and priority highlights
491
- 4. Local generated-plan review result: verdict, reviewed batch IDs plus reviewed root prose when applicable, and accepted fixes (or "none")
492
- 5. Insert result: the writer's `appended_ids` from the single post-review run, plus its validation output and the draft cleanup result (`removed`, or retained path and reason)
493
- 6. Recommended next action: `feature-pipeline-launcher`
110
+ ## Testing, Error Recovery, Session Exit & Handoff
494
111
 
495
- Then apply the post-planning handoff in §Scope Boundary (ask before proceeding; never auto-execute).
112
+ - **Testing Defaults (Phase 8)**: Assign testing expectations matching risk (`high`: scoped tests + review-gate evidence; `medium`: focused changed-behavior tests; `low`: smallest relevant verification) + browser verification for `browser_interaction` items; present consolidated summary for confirmation.
113
+ - **Next-Step Execution Policy**: Recommend `feature-pipeline-launcher`; never recommend manual runtime shell scripts or auto-execute.
114
+ - **Error Recovery & Resume**: On validation failures (max 3 retries on critical errors; clarify consequential warnings; proceed past informational warnings) or interruptions, read `${SKILL_DIR}/references/error-recovery.md`.
115
+ - **Session Exit Gate**: If user intended `.prizmkit/plans/feature-list.json` and phase `< 7` with no valid list written, remind and ask `AskUserQuestion` (`Continue to completion (Recommended)`, `Save draft & exit` retaining `.prizmkit/plans/feature-list.draft.json`, `Abandon`).
116
+ - **Handoff Summary**: Report output path, total + added features, dependency/priority highlights, Local generated-plan review result (verdict, reviewed batch IDs plus reviewed root prose when applicable, accepted fixes), single-run `appended_ids` + validation + Draft cleanup result (`removed`, or retained path and recovery reason), and recommend `feature-pipeline-launcher` (wait for confirmation).
@@ -2,7 +2,7 @@
2
2
 
3
3
  This guide provides structured templates and patterns for writing high-quality feature descriptions, acceptance criteria, complexity estimates, dependency graphs, and contract-bounded grouping decisions. Use during feature-planner sessions.
4
4
 
5
- For app-level design references (vision templates, tech stack matrix), see `app-planner/references/app-design-guide.md`. For feature decomposition patterns (CRUD, SaaS, Social, E-commerce), see `${SKILL_DIR}/references/decomposition-patterns.md`.
5
+ For app-level design, vision templates, and tech stack choices, use `app-planner`. For feature decomposition patterns (CRUD, SaaS, Social, E-commerce), see `${SKILL_DIR}/references/decomposition-patterns.md`.
6
6
 
7
7
  ---
8
8