prizmkit 1.1.191 → 1.1.192
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.
- package/bundled/VERSION.json +3 -3
- package/bundled/adapters/antigravity/skill-adapter.js +13 -4
- package/bundled/adapters/codex/skill-adapter.js +28 -8
- package/bundled/adapters/cursor/skill-adapter.js +13 -4
- package/bundled/adapters/pi/skill-adapter.js +28 -7
- package/bundled/dev-pipeline/.env.example +4 -12
- package/bundled/dev-pipeline/README.md +5 -10
- package/bundled/dev-pipeline/assets/skill-subagent-integration.md +3 -6
- package/bundled/dev-pipeline/prizmkit_runtime/atomic_io.py +48 -0
- package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +66 -23
- package/bundled/dev-pipeline/prizmkit_runtime/cli.py +10 -7
- package/bundled/dev-pipeline/prizmkit_runtime/commands.py +2 -21
- package/bundled/dev-pipeline/prizmkit_runtime/config.py +24 -76
- package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +125 -67
- package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +77 -430
- package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +93 -49
- package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -3
- package/bundled/dev-pipeline/prizmkit_runtime/paths.py +0 -6
- package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +36 -14
- package/bundled/dev-pipeline/prizmkit_runtime/processes.py +206 -151
- package/bundled/dev-pipeline/prizmkit_runtime/reset.py +2 -23
- package/bundled/dev-pipeline/prizmkit_runtime/reset_preserve.py +15 -134
- package/bundled/dev-pipeline/prizmkit_runtime/results.py +25 -0
- package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +68 -83
- package/bundled/dev-pipeline/prizmkit_runtime/runner_classification.py +15 -5
- package/bundled/dev-pipeline/prizmkit_runtime/runner_models.py +1 -29
- package/bundled/dev-pipeline/prizmkit_runtime/runner_prompts.py +0 -2
- package/bundled/dev-pipeline/prizmkit_runtime/runner_status.py +7 -2
- package/bundled/dev-pipeline/prizmkit_runtime/runners.py +276 -217
- package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +124 -122
- package/bundled/dev-pipeline/prizmkit_runtime/runtime_helper.py +90 -9
- package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +183 -130
- package/bundled/dev-pipeline/prizmkit_runtime/status.py +1 -3
- package/bundled/dev-pipeline/prizmkit_runtime/stream_progress.py +2780 -0
- package/bundled/dev-pipeline/prizmkit_runtime/task_checkout.py +27 -101
- package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +58 -4
- package/bundled/dev-pipeline/scripts/check-session-status.py +43 -19
- package/bundled/dev-pipeline/scripts/continuation.py +6 -4
- package/bundled/dev-pipeline/scripts/detect-stuck.py +28 -28
- package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +7 -2
- package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +7 -2
- package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +10 -7
- package/bundled/dev-pipeline/scripts/init-change-artifact.py +8 -2
- package/bundled/dev-pipeline/scripts/init-pipeline.py +14 -69
- package/bundled/dev-pipeline/scripts/parse-stream-progress.py +31 -2616
- package/bundled/dev-pipeline/scripts/patch-completion-notes.py +4 -24
- package/bundled/dev-pipeline/scripts/prompt_framework.py +56 -9
- package/bundled/dev-pipeline/scripts/status_common.py +591 -0
- package/bundled/dev-pipeline/scripts/update-bug-status.py +85 -463
- package/bundled/dev-pipeline/scripts/update-checkpoint.py +227 -65
- package/bundled/dev-pipeline/scripts/update-feature-status.py +76 -509
- package/bundled/dev-pipeline/scripts/utils.py +5 -12
- package/bundled/dev-pipeline/templates/bootstrap-tier3.md +4 -4
- package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +7 -0
- package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +1 -1
- package/bundled/dev-pipeline/templates/sections/artifact-manifest.md +1 -1
- package/bundled/dev-pipeline/templates/sections/bugfix-phase-manual-verification.md +1 -1
- package/bundled/dev-pipeline/templates/sections/bugfix-phase-review.md +1 -1
- package/bundled/dev-pipeline/templates/sections/bugfix-phase-test.md +2 -1
- package/bundled/dev-pipeline/templates/sections/checkpoint-system.md +1 -1
- package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +1 -1
- package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +2 -2
- package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md +2 -2
- package/bundled/dev-pipeline/templates/sections/phase-prizmkit-test.md +2 -1
- package/bundled/dev-pipeline/templates/sections/phase-review-full.md +1 -1
- package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +3 -6
- package/bundled/dev-pipeline/templates/session-status-schema.json +2 -5
- package/bundled/dev-pipeline/tests/_helpers.py +418 -0
- package/bundled/dev-pipeline/tests/conftest.py +45 -1
- package/bundled/dev-pipeline/tests/test_auto_skip.py +4 -69
- package/bundled/dev-pipeline/tests/test_checkpoint_state.py +126 -1
- package/bundled/dev-pipeline/tests/test_daemon_and_scripts.py +257 -0
- package/bundled/dev-pipeline/tests/test_e2e_pipeline_run.py +500 -0
- package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +59 -117
- package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py +12 -10
- package/bundled/dev-pipeline/tests/test_python_runner_parity.py +431 -3099
- package/bundled/dev-pipeline/tests/test_recovery_workflow.py +7 -8
- package/bundled/dev-pipeline/tests/test_repository_bootstrap.py +0 -1
- package/bundled/dev-pipeline/tests/test_reset_modes.py +15 -27
- package/bundled/dev-pipeline/tests/test_reset_preserve.py +54 -139
- package/bundled/dev-pipeline/tests/test_runner_bookkeeping.py +766 -0
- package/bundled/dev-pipeline/tests/test_runner_lifecycle.py +1257 -0
- package/bundled/dev-pipeline/tests/test_runtime_helper.py +97 -20
- package/bundled/dev-pipeline/tests/test_session_launch.py +1101 -0
- package/bundled/dev-pipeline/tests/test_stream_progress.py +585 -0
- package/bundled/dev-pipeline/tests/test_unified_cli.py +155 -2034
- package/bundled/dev-pipeline/tests/test_utils.py +3 -3
- package/bundled/skills/_metadata.json +9 -63
- package/bundled/skills/app-planner/SKILL.md +32 -303
- package/bundled/skills/app-planner/references/app-design-guide.md +0 -4
- package/bundled/skills/app-planner/references/generated-plan-review.md +2 -1
- package/bundled/skills/app-planner/references/project-brief-guide.md +14 -0
- package/bundled/skills/app-planner/references/project-conventions-discovery.md +4 -6
- package/bundled/skills/app-planner/references/project-state-detection.md +2 -3
- package/bundled/skills/bug-fix-workflow/SKILL.md +1 -2
- package/bundled/skills/bug-fix-workflow/references/bug-diagnosis.md +4 -7
- package/bundled/skills/bug-planner/SKILL.md +54 -435
- package/bundled/skills/bug-planner/references/generated-plan-review.md +3 -2
- package/bundled/skills/bug-planner/references/input-formats.md +32 -0
- package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +4 -6
- package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +4 -28
- package/bundled/skills/feature-pipeline-launcher/SKILL.md +4 -6
- package/bundled/skills/feature-pipeline-launcher/references/configuration.md +4 -28
- package/bundled/skills/feature-planner/SKILL.md +60 -439
- package/bundled/skills/feature-planner/assets/planning-guide.md +1 -1
- package/bundled/skills/feature-planner/references/completeness-review.md +34 -0
- package/bundled/skills/feature-planner/references/decomposition-patterns.md +2 -2
- package/bundled/skills/feature-planner/references/error-recovery.md +1 -1
- package/bundled/skills/feature-planner/references/generated-plan-review.md +3 -2
- package/bundled/skills/feature-planner/references/incremental-feature-planning.md +3 -1
- package/bundled/skills/feature-workflow/SKILL.md +1 -2
- package/bundled/skills/prizmkit/SKILL.md +7 -1
- package/bundled/skills/prizmkit-code-review/SKILL.md +14 -6
- package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +7 -4
- package/bundled/skills/prizmkit-code-review/references/review-report-template.md +16 -0
- package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +58 -20
- package/bundled/skills/prizmkit-implement/SKILL.md +1 -1
- package/bundled/skills/prizmkit-init/SKILL.md +24 -127
- package/bundled/skills/prizmkit-init/assets/project-brief-template.md +3 -3
- package/bundled/skills/prizmkit-plan/SKILL.md +6 -8
- package/bundled/skills/prizmkit-plan/references/clarify-guide.md +1 -1
- package/bundled/skills/prizmkit-plan/references/independent-plan-review.md +5 -2
- package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +6 -5
- package/bundled/skills/prizmkit-prizm-docs/SKILL.md +1 -13
- package/bundled/skills/prizmkit-prizm-docs/references/op-update.md +1 -1
- package/bundled/skills/prizmkit-retrospective/SKILL.md +6 -4
- package/bundled/skills/prizmkit-test/SKILL.md +25 -133
- package/bundled/skills/prizmkit-test/references/independent-test-review.md +5 -2
- package/bundled/skills/prizmkit-test/references/test-coverage-model.md +6 -0
- package/bundled/skills/prizmkit-workflow/SKILL.md +2 -3
- package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +4 -3
- package/bundled/skills/recovery-workflow/SKILL.md +7 -7
- package/bundled/skills/recovery-workflow/evals/evals.json +1 -1
- package/bundled/skills/recovery-workflow/references/detection.md +1 -3
- package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py +0 -6
- package/bundled/templates/project-memory-template.md +1 -2
- package/package.json +1 -1
- package/src/scaffold.js +28 -7
- package/bundled/dev-pipeline/SCHEMA_ANALYSIS.md +0 -53
- package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py +0 -649
- package/bundled/dev-pipeline/scripts/init-refactor-pipeline.py +0 -463
- package/bundled/dev-pipeline/scripts/update-refactor-status.py +0 -1512
- package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md +0 -240
- package/bundled/dev-pipeline/templates/refactor-list-schema.json +0 -266
- package/bundled/dev-pipeline/templates/sections/refactor-critical-paths.md +0 -15
- package/bundled/dev-pipeline/templates/sections/refactor-mission.md +0 -9
- package/bundled/dev-pipeline/templates/sections/refactor-phase-commit-report.md +0 -24
- package/bundled/dev-pipeline/templates/sections/refactor-phase-implement.md +0 -16
- package/bundled/dev-pipeline/templates/sections/refactor-phase-init.md +0 -9
- package/bundled/dev-pipeline/templates/sections/refactor-phase-plan.md +0 -22
- package/bundled/dev-pipeline/templates/sections/refactor-phase-review.md +0 -19
- package/bundled/dev-pipeline/templates/sections/refactor-phase-test.md +0 -24
- package/bundled/dev-pipeline/templates/sections/refactor-reminders.md +0 -12
- package/bundled/dev-pipeline/templates/sections/refactor-session-context.md +0 -6
- package/bundled/dev-pipeline/templates/sections/refactor-task-contract.md +0 -52
- package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py +0 -478
- package/bundled/skills/feature-planner/assets/evaluation-guide.md +0 -44
- package/bundled/skills/refactor-pipeline-launcher/SKILL.md +0 -219
- package/bundled/skills/refactor-pipeline-launcher/references/configuration.md +0 -78
- package/bundled/skills/refactor-planner/SKILL.md +0 -467
- package/bundled/skills/refactor-planner/assets/planning-guide.md +0 -291
- package/bundled/skills/refactor-planner/references/behavior-preservation.md +0 -187
- package/bundled/skills/refactor-planner/references/error-recovery.md +0 -45
- package/bundled/skills/refactor-planner/references/fast-path.md +0 -59
- package/bundled/skills/refactor-planner/references/generated-plan-review.md +0 -107
- package/bundled/skills/refactor-planner/references/planning-phases.md +0 -172
- package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +0 -230
- package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +0 -1120
- 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`,
|
|
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.**
|
|
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
|
|
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
|
|
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
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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
|
-
|
|
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
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
```
|
|
272
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
293
|
-
1.1 **
|
|
294
|
-
1.2 **
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
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
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
-
|
|
351
|
-
-
|
|
352
|
-
-
|
|
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
|
-
|
|
390
|
-
|
|
391
|
-
|
|
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
|
-
|
|
94
|
+
## Output Rules & Local Generated-Plan Review Gate
|
|
403
95
|
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
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
|
-
|
|
411
|
-
|
|
412
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|