prizmkit 1.1.174 → 1.1.175
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/skills/_metadata.json +1 -1
- package/bundled/skills/bug-planner/SKILL.md +26 -19
- package/bundled/skills/bug-planner/references/generated-plan-review.md +20 -11
- package/bundled/skills/bug-planner/scripts/validate-bug-list.py +216 -1
- package/bundled/skills/feature-planner/SKILL.md +27 -18
- package/bundled/skills/feature-planner/references/generated-plan-review.md +20 -11
- package/bundled/skills/feature-planner/references/incremental-feature-planning.md +83 -70
- package/bundled/skills/feature-planner/scripts/validate-and-generate.py +213 -0
- package/bundled/skills/refactor-planner/SKILL.md +35 -8
- package/bundled/skills/refactor-planner/references/fast-path.md +4 -4
- package/bundled/skills/refactor-planner/references/generated-plan-review.md +20 -11
- package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +213 -0
- package/package.json +1 -1
|
@@ -4,109 +4,122 @@ Use this reference when the user adds features to an existing app/plan.
|
|
|
4
4
|
|
|
5
5
|
## Pre-Checks
|
|
6
6
|
|
|
7
|
-
1.
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
7
|
+
1. Do not read the complete existing `feature-list.json`. Run:
|
|
8
|
+
```bash
|
|
9
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py context --input .prizmkit/plans/feature-list.json
|
|
10
|
+
```
|
|
11
|
+
2. Consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and the five most recent `{id, description}` pairs.
|
|
12
|
+
3. Use the returned `next_id` for the first addition and continue sequentially.
|
|
13
|
+
4. Preserve confirmed project conventions and dependency correctness without treating recent chronology as relevance.
|
|
14
|
+
5. Project conventions remain handled by the main `SKILL.md` flow before incremental planning begins.
|
|
12
15
|
|
|
13
|
-
If `feature-list.json` is missing, ask whether to initialize a new plan.
|
|
16
|
+
If `feature-list.json` is missing, ask whether to initialize a new plan. If the context command reports invalid input or exhausted ID capacity, stop and resolve that explicit blocker instead of reading or rewriting the entire list in AI context.
|
|
14
17
|
|
|
15
|
-
##
|
|
18
|
+
## Recent-History Relevance Gate
|
|
16
19
|
|
|
17
|
-
|
|
20
|
+
The five recent pairs are a bounded continuity and conflict check, not a default source of new feature content.
|
|
18
21
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
22
|
+
- Add no historical content by default.
|
|
23
|
+
- Inspect recent descriptions only for material continuation, duplication, conflict, a shared public behavior contract, or a real execution prerequisite.
|
|
24
|
+
- Chronology, broad module overlap, shared technology, reusable implementation ideas, and similar wording alone do not establish relevance.
|
|
25
|
+
- When omission would make the new feature's scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect, incorporate only the minimum exact contract-affecting information into that feature.
|
|
26
|
+
- Do not persist vague text such as `related to F-123` and do not copy an entire historical description merely because it overlaps.
|
|
27
|
+
- Add an old ID to `dependencies` only when it is a real execution prerequisite.
|
|
23
28
|
|
|
24
|
-
|
|
25
|
-
- Calculate avg word count per description
|
|
26
|
-
- If avg <30 words → draft concise descriptions
|
|
27
|
-
- If avg 30-80 words → draft standard detail
|
|
28
|
-
- If avg >80 words → draft detailed descriptions
|
|
29
|
+
When the user explicitly identifies an old feature ID for modification or detailed review, or a validation error names it, load only that complete top-level feature:
|
|
29
30
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
- Identify dominant format (Given/When/Then Gherkin, BDD, or loose)
|
|
33
|
-
- Draft new AC in same format
|
|
34
|
-
|
|
35
|
-
4. **Complexity Distribution**
|
|
36
|
-
- Count low/medium/high distribution in existing features
|
|
37
|
-
- Alert if new features deviate significantly (>20 percentile points)
|
|
38
|
-
- Suggest rebalancing if needed
|
|
39
|
-
|
|
40
|
-
### Style Consistency Prompt
|
|
41
|
-
|
|
42
|
-
If new features deviate significantly from detected style:
|
|
43
|
-
|
|
44
|
-
```
|
|
45
|
-
"Your new features use avg X words/description, but existing features use Y.
|
|
46
|
-
Current ratio: low:M%, medium:N%, high:O%.
|
|
47
|
-
Adjust new features to match? (Y/n)"
|
|
31
|
+
```bash
|
|
32
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-NNN
|
|
48
33
|
```
|
|
49
34
|
|
|
50
|
-
|
|
35
|
+
Do not perform default full-history keyword search.
|
|
51
36
|
|
|
52
37
|
## Incremental Planning Flow
|
|
53
38
|
|
|
54
39
|
### Step 1: Clarify Increment Scope
|
|
40
|
+
|
|
55
41
|
Capture:
|
|
56
|
-
- business objective of the new increment
|
|
57
|
-
- affected existing modules
|
|
58
|
-
- timeline or priority constraints
|
|
42
|
+
- business objective of the new increment;
|
|
43
|
+
- affected existing capabilities and current project modules established from project evidence;
|
|
44
|
+
- timeline or priority constraints.
|
|
59
45
|
|
|
60
46
|
### Step 2: Impact Mapping
|
|
47
|
+
|
|
61
48
|
For each candidate feature, identify:
|
|
62
|
-
- upstream
|
|
63
|
-
- downstream impacts
|
|
64
|
-
- risk hotspots
|
|
49
|
+
- real upstream prerequisites;
|
|
50
|
+
- downstream impacts;
|
|
51
|
+
- risk hotspots such as auth, data migration, and API compatibility.
|
|
65
52
|
|
|
66
|
-
|
|
67
|
-
|
|
53
|
+
Use current project evidence as the primary source. The recent five-task window supplies only the narrow relevance evidence permitted by the gate above.
|
|
54
|
+
|
|
55
|
+
### Step 3: Draft Additions
|
|
56
|
+
|
|
57
|
+
Draft new items only; do not rewrite old validated features unless the user explicitly requested an old ID operation.
|
|
68
58
|
|
|
69
59
|
For each new feature:
|
|
70
|
-
- assign next ID
|
|
71
|
-
-
|
|
72
|
-
- link dependencies to
|
|
73
|
-
- keep title in English
|
|
74
|
-
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
60
|
+
- assign the next sequential ID returned by `context`;
|
|
61
|
+
- omit `status` or set it to `pending`;
|
|
62
|
+
- link dependencies to old IDs only for real execution prerequisites;
|
|
63
|
+
- keep the title in English for stable slug generation;
|
|
64
|
+
- write a self-contained description with objective, current and desired behavior, selected decisions, constraints, non-goals, relevant integrations, edge cases, and completion evidence;
|
|
65
|
+
- add concrete measurable acceptance criteria.
|
|
66
|
+
|
|
67
|
+
The additions-only `.prizmkit/plans/feature-list.draft.json` has exactly one root field:
|
|
68
|
+
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"features": [
|
|
72
|
+
{
|
|
73
|
+
"id": "F-NNN",
|
|
74
|
+
"title": "English stable title",
|
|
75
|
+
"description": "Self-contained feature contract",
|
|
76
|
+
"priority": "medium",
|
|
77
|
+
"dependencies": [],
|
|
78
|
+
"acceptance_criteria": ["Concrete measurable result"]
|
|
79
|
+
}
|
|
80
|
+
]
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Each item uses the unchanged final feature-item schema. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional feature fields remain allowed. Root project metadata and historical features must not be copied into this draft.
|
|
78
85
|
|
|
79
86
|
### Step 4: Rebalance Priority
|
|
80
|
-
Allow priority updates for both old and new features if user requests reprioritization.
|
|
81
|
-
Keep dependency correctness as first constraint.
|
|
82
87
|
|
|
83
|
-
|
|
84
|
-
|
|
88
|
+
Default to append only. Reprioritizing historical tasks is an explicit old-task modification, not part of ordinary append flow; require the user to identify the affected IDs and load only those tasks with `show`.
|
|
89
|
+
|
|
90
|
+
### Step 5: Append and Validate
|
|
91
|
+
|
|
92
|
+
Merge the additions-only draft with untouched history outside AI context:
|
|
93
|
+
|
|
85
94
|
```bash
|
|
86
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate.py
|
|
95
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
87
96
|
```
|
|
88
97
|
|
|
89
|
-
Fix and
|
|
98
|
+
The append command validates the existing base, exact sequential new IDs, all old/new dependencies, and the complete DAG before atomically replacing the final list. Fix the additions draft and rerun until valid. Use `generate` only for an initial plan or an explicit full-list rewrite.
|
|
90
99
|
|
|
91
100
|
## Merge/Rewrite Rules
|
|
92
101
|
|
|
93
|
-
- Default: append only
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
- Never
|
|
102
|
+
- Default: append only through the additions-only draft.
|
|
103
|
+
- Preserve every historical task and root value unchanged.
|
|
104
|
+
- Rewrite existing features only when the user explicitly identifies them.
|
|
105
|
+
- Never break valid IDs/references.
|
|
106
|
+
- Never set new features to `in_progress` or `completed`.
|
|
97
107
|
|
|
98
108
|
## Practical Prompts
|
|
99
109
|
|
|
100
110
|
Use concise prompts during interaction:
|
|
101
|
-
-
|
|
102
|
-
-
|
|
103
|
-
-
|
|
111
|
+
- “What is the goal of this increment? Which user problem is the priority?”
|
|
112
|
+
- “Does any of the five recent descriptions represent a real continuation, conflict, shared contract, or prerequisite? If not, no historical content will be carried forward.”
|
|
113
|
+
- “Do you want only an append, or are you explicitly modifying identified historical Feature IDs?”
|
|
104
114
|
|
|
105
115
|
## Final Delivery Checklist
|
|
106
116
|
|
|
107
|
-
- [ ]
|
|
108
|
-
- [ ]
|
|
109
|
-
- [ ]
|
|
110
|
-
- [ ]
|
|
111
|
-
- [ ]
|
|
117
|
+
- [ ] Bounded `context` command used; complete historical list not loaded
|
|
118
|
+
- [ ] At most five recent `{id, description}` pairs inspected
|
|
119
|
+
- [ ] No historical content added by default
|
|
120
|
+
- [ ] Any incorporated history is minimum, contract-affecting, and task-scoped
|
|
121
|
+
- [ ] Old dependency IDs represent real execution prerequisites
|
|
122
|
+
- [ ] Additions-only draft contains no root metadata or historical features
|
|
123
|
+
- [ ] Existing project conventions preserved from project evidence
|
|
124
|
+
- [ ] Complete merged dependency graph validates through `append`
|
|
112
125
|
- [ ] Next step recommendation: `feature-pipeline-launcher`
|
|
@@ -6,6 +6,9 @@ for the dev-pipeline system.
|
|
|
6
6
|
Commands:
|
|
7
7
|
validate Validate an existing .prizmkit/plans/feature-list.json
|
|
8
8
|
template Generate a blank template .prizmkit/plans/feature-list.json
|
|
9
|
+
context Print bounded project context plus the five most recent features
|
|
10
|
+
show Print one explicitly requested top-level feature
|
|
11
|
+
append Merge an additions-only draft into an existing validated list
|
|
9
12
|
generate Validate a draft JSON and generate final feature-list.json with defaults
|
|
10
13
|
summary Print a summary table of features from a .prizmkit/plans/feature-list.json
|
|
11
14
|
grade Generate grading results from eval runs (for npm run skill:review)
|
|
@@ -13,6 +16,9 @@ Commands:
|
|
|
13
16
|
Usage:
|
|
14
17
|
python3 validate-and-generate.py validate --input .prizmkit/plans/feature-list.json [--output validated.json]
|
|
15
18
|
python3 validate-and-generate.py template --output .prizmkit/plans/feature-list.json
|
|
19
|
+
python3 validate-and-generate.py context --input .prizmkit/plans/feature-list.json
|
|
20
|
+
python3 validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-001
|
|
21
|
+
python3 validate-and-generate.py append --input additions.json --output .prizmkit/plans/feature-list.json
|
|
16
22
|
python3 validate-and-generate.py generate --input draft.json --output .prizmkit/plans/feature-list.json
|
|
17
23
|
python3 validate-and-generate.py summary --input .prizmkit/plans/feature-list.json [--format markdown|json]
|
|
18
24
|
python3 validate-and-generate.py grade --workspace /.codebuddy/skill-evals/feature-planner-workspace --iteration iteration-1
|
|
@@ -26,10 +32,12 @@ Python 3.6+ required. No external dependencies.
|
|
|
26
32
|
|
|
27
33
|
import argparse
|
|
28
34
|
import collections
|
|
35
|
+
import copy
|
|
29
36
|
import json
|
|
30
37
|
import os
|
|
31
38
|
import re
|
|
32
39
|
import sys
|
|
40
|
+
import tempfile
|
|
33
41
|
from datetime import datetime, timezone
|
|
34
42
|
|
|
35
43
|
# ---------------------------------------------------------------------------
|
|
@@ -115,6 +123,25 @@ def _write_json(path, data):
|
|
|
115
123
|
fh.write("\n")
|
|
116
124
|
|
|
117
125
|
|
|
126
|
+
def _write_json_atomic(path, data):
|
|
127
|
+
"""Atomically replace *path* with pretty-printed JSON data."""
|
|
128
|
+
parent = os.path.dirname(os.path.abspath(path))
|
|
129
|
+
if parent and not os.path.isdir(parent):
|
|
130
|
+
os.makedirs(parent, exist_ok=True)
|
|
131
|
+
fd, temp_path = tempfile.mkstemp(prefix=".feature-list-", suffix=".tmp", dir=parent)
|
|
132
|
+
try:
|
|
133
|
+
with os.fdopen(fd, "w", encoding="utf-8") as fh:
|
|
134
|
+
json.dump(data, fh, indent=2, ensure_ascii=False)
|
|
135
|
+
fh.write("\n")
|
|
136
|
+
os.replace(temp_path, path)
|
|
137
|
+
except Exception:
|
|
138
|
+
try:
|
|
139
|
+
os.unlink(temp_path)
|
|
140
|
+
except OSError:
|
|
141
|
+
pass
|
|
142
|
+
raise
|
|
143
|
+
|
|
144
|
+
|
|
118
145
|
# ---------------------------------------------------------------------------
|
|
119
146
|
# Cycle detection (Kahn's algorithm)
|
|
120
147
|
# ---------------------------------------------------------------------------
|
|
@@ -745,6 +772,148 @@ def cmd_template(args):
|
|
|
745
772
|
return 0
|
|
746
773
|
|
|
747
774
|
|
|
775
|
+
def _load_valid_existing(path):
|
|
776
|
+
"""Load and validate one existing feature list."""
|
|
777
|
+
data, load_err = _load_json(path)
|
|
778
|
+
if load_err:
|
|
779
|
+
_err(load_err)
|
|
780
|
+
return None, None, 2
|
|
781
|
+
if not isinstance(data, dict):
|
|
782
|
+
_err("Feature list root must be an object")
|
|
783
|
+
return None, None, 1
|
|
784
|
+
|
|
785
|
+
result = validate_feature_list(data, is_new_plan=False)
|
|
786
|
+
if not result["valid"]:
|
|
787
|
+
_err("Existing feature list is invalid")
|
|
788
|
+
for error in result["errors"]:
|
|
789
|
+
_err(" " + error)
|
|
790
|
+
return None, result, 1
|
|
791
|
+
return data, result, 0
|
|
792
|
+
|
|
793
|
+
|
|
794
|
+
def _next_top_level_id(features):
|
|
795
|
+
"""Return the next F-NNN ID, or None when numeric capacity is exhausted."""
|
|
796
|
+
numbers = []
|
|
797
|
+
for feature in features:
|
|
798
|
+
match = FEATURE_ID_RE.match(str(feature.get("id", "")))
|
|
799
|
+
if match:
|
|
800
|
+
numbers.append(int(str(feature["id"])[2:5]))
|
|
801
|
+
next_number = max(numbers, default=0) + 1
|
|
802
|
+
if next_number > 999:
|
|
803
|
+
return None
|
|
804
|
+
return "F-{:03d}".format(next_number)
|
|
805
|
+
|
|
806
|
+
|
|
807
|
+
def cmd_context(args):
|
|
808
|
+
"""Print bounded existing-list context for incremental planning."""
|
|
809
|
+
data, _, exit_code = _load_valid_existing(args.input)
|
|
810
|
+
if exit_code:
|
|
811
|
+
return exit_code
|
|
812
|
+
|
|
813
|
+
features = data["features"]
|
|
814
|
+
next_id = _next_top_level_id(features)
|
|
815
|
+
if next_id is None:
|
|
816
|
+
_err("Feature ID capacity exhausted at F-999")
|
|
817
|
+
return 1
|
|
818
|
+
|
|
819
|
+
context = {
|
|
820
|
+
"project_name": data.get("project_name"),
|
|
821
|
+
"project_description": data.get("project_description"),
|
|
822
|
+
"global_context": data.get("global_context") or {},
|
|
823
|
+
"task_count": len(features),
|
|
824
|
+
"next_id": next_id,
|
|
825
|
+
"recent_tasks": [
|
|
826
|
+
{"id": feature.get("id"), "description": feature.get("description")}
|
|
827
|
+
for feature in features[-5:]
|
|
828
|
+
],
|
|
829
|
+
}
|
|
830
|
+
print(json.dumps(context, indent=2, ensure_ascii=False))
|
|
831
|
+
return 0
|
|
832
|
+
|
|
833
|
+
|
|
834
|
+
def cmd_show(args):
|
|
835
|
+
"""Print one explicitly requested top-level feature."""
|
|
836
|
+
data, _, exit_code = _load_valid_existing(args.input)
|
|
837
|
+
if exit_code:
|
|
838
|
+
return exit_code
|
|
839
|
+
if not FEATURE_ID_RE.match(str(args.id)):
|
|
840
|
+
_err("Feature ID '{}' must match F-NNN or F-NNN-X".format(args.id))
|
|
841
|
+
return 1
|
|
842
|
+
|
|
843
|
+
for feature in data["features"]:
|
|
844
|
+
if feature.get("id") == args.id:
|
|
845
|
+
print(json.dumps(feature, indent=2, ensure_ascii=False))
|
|
846
|
+
return 0
|
|
847
|
+
_err("Feature '{}' not found".format(args.id))
|
|
848
|
+
return 1
|
|
849
|
+
|
|
850
|
+
|
|
851
|
+
def cmd_append(args):
|
|
852
|
+
"""Append a collection-only draft to an existing validated feature list."""
|
|
853
|
+
base, _, exit_code = _load_valid_existing(args.output)
|
|
854
|
+
if exit_code:
|
|
855
|
+
return exit_code
|
|
856
|
+
|
|
857
|
+
draft, load_err = _load_json(args.input)
|
|
858
|
+
if load_err:
|
|
859
|
+
_err(load_err)
|
|
860
|
+
return 2
|
|
861
|
+
if not isinstance(draft, dict) or set(draft.keys()) != {"features"}:
|
|
862
|
+
_err("Additions draft must be an object containing only 'features'")
|
|
863
|
+
return 1
|
|
864
|
+
additions = draft.get("features")
|
|
865
|
+
if not isinstance(additions, list) or not additions:
|
|
866
|
+
_err("Additions draft 'features' must be a non-empty array")
|
|
867
|
+
return 1
|
|
868
|
+
if not all(isinstance(feature, dict) for feature in additions):
|
|
869
|
+
_err("Every feature addition must be an object")
|
|
870
|
+
return 1
|
|
871
|
+
|
|
872
|
+
merge_base = copy.deepcopy(base)
|
|
873
|
+
if args.replace_tail:
|
|
874
|
+
addition_ids = [feature.get("id") for feature in additions]
|
|
875
|
+
tail_ids = [feature.get("id") for feature in base["features"][-len(additions):]]
|
|
876
|
+
if len(base["features"]) < len(additions) or tail_ids != addition_ids:
|
|
877
|
+
_err("--replace-tail requires additions IDs to match the existing final-list suffix exactly")
|
|
878
|
+
return 1
|
|
879
|
+
merge_base["features"] = merge_base["features"][:-len(additions)]
|
|
880
|
+
|
|
881
|
+
next_id = _next_top_level_id(merge_base["features"])
|
|
882
|
+
if next_id is None:
|
|
883
|
+
_err("Feature ID capacity exhausted at F-999")
|
|
884
|
+
return 1
|
|
885
|
+
start_number = int(next_id[2:])
|
|
886
|
+
prepared = copy.deepcopy(additions)
|
|
887
|
+
for offset, feature in enumerate(prepared):
|
|
888
|
+
expected_id = "F-{:03d}".format(start_number + offset)
|
|
889
|
+
if start_number + offset > 999:
|
|
890
|
+
_err("Feature ID capacity exhausted at F-999")
|
|
891
|
+
return 1
|
|
892
|
+
if feature.get("id") != expected_id:
|
|
893
|
+
_err("Feature addition {} must use next sequential ID '{}'".format(offset, expected_id))
|
|
894
|
+
return 1
|
|
895
|
+
feature.setdefault("status", "pending")
|
|
896
|
+
|
|
897
|
+
merged = copy.deepcopy(merge_base)
|
|
898
|
+
merged["features"].extend(prepared)
|
|
899
|
+
result = validate_feature_list(merged, is_new_plan=False)
|
|
900
|
+
result["appended_ids"] = [feature["id"] for feature in prepared]
|
|
901
|
+
print(json.dumps(result, indent=2, ensure_ascii=False))
|
|
902
|
+
if not result["valid"]:
|
|
903
|
+
_err("Merged feature list validation failed")
|
|
904
|
+
for error in result["errors"]:
|
|
905
|
+
_err(" " + error)
|
|
906
|
+
return 1
|
|
907
|
+
|
|
908
|
+
try:
|
|
909
|
+
_write_json_atomic(args.output, merged)
|
|
910
|
+
except Exception as exc:
|
|
911
|
+
_err("Failed to write merged feature list: {}".format(exc))
|
|
912
|
+
return 2
|
|
913
|
+
_info("Appended {} feature(s) to {}".format(len(prepared), args.output))
|
|
914
|
+
return 0
|
|
915
|
+
|
|
916
|
+
|
|
748
917
|
def cmd_generate(args):
|
|
749
918
|
"""Handle the 'generate' command.
|
|
750
919
|
|
|
@@ -943,6 +1112,9 @@ def main():
|
|
|
943
1112
|
" %(prog)s validate --input .prizmkit/plans/feature-list.json\n"
|
|
944
1113
|
" %(prog)s validate --input .prizmkit/plans/feature-list.json --output validated.json\n"
|
|
945
1114
|
" %(prog)s template --output .prizmkit/plans/feature-list.json\n"
|
|
1115
|
+
" %(prog)s context --input .prizmkit/plans/feature-list.json\n"
|
|
1116
|
+
" %(prog)s show --input .prizmkit/plans/feature-list.json --id F-001\n"
|
|
1117
|
+
" %(prog)s append --input additions.json --output .prizmkit/plans/feature-list.json\n"
|
|
946
1118
|
" %(prog)s generate --input draft.json --output .prizmkit/plans/feature-list.json\n"
|
|
947
1119
|
" %(prog)s summary --input .prizmkit/plans/feature-list.json\n"
|
|
948
1120
|
" %(prog)s summary --input .prizmkit/plans/feature-list.json --format json\n"
|
|
@@ -972,6 +1144,44 @@ def main():
|
|
|
972
1144
|
"--output", required=True, help="Path to write template file"
|
|
973
1145
|
)
|
|
974
1146
|
|
|
1147
|
+
# -- context --
|
|
1148
|
+
p_context = subparsers.add_parser(
|
|
1149
|
+
"context",
|
|
1150
|
+
help="Print root context and the five most recent feature id/description pairs",
|
|
1151
|
+
)
|
|
1152
|
+
p_context.add_argument(
|
|
1153
|
+
"--input", required=True, help="Path to existing .prizmkit/plans/feature-list.json"
|
|
1154
|
+
)
|
|
1155
|
+
|
|
1156
|
+
# -- show --
|
|
1157
|
+
p_show = subparsers.add_parser(
|
|
1158
|
+
"show",
|
|
1159
|
+
help="Print one explicitly requested top-level feature",
|
|
1160
|
+
)
|
|
1161
|
+
p_show.add_argument(
|
|
1162
|
+
"--input", required=True, help="Path to existing .prizmkit/plans/feature-list.json"
|
|
1163
|
+
)
|
|
1164
|
+
p_show.add_argument(
|
|
1165
|
+
"--id", required=True, help="Exact top-level feature ID"
|
|
1166
|
+
)
|
|
1167
|
+
|
|
1168
|
+
# -- append --
|
|
1169
|
+
p_append = subparsers.add_parser(
|
|
1170
|
+
"append",
|
|
1171
|
+
help="Append a features-only draft to an existing validated feature list",
|
|
1172
|
+
)
|
|
1173
|
+
p_append.add_argument(
|
|
1174
|
+
"--input", required=True, help="Path to additions-only draft JSON"
|
|
1175
|
+
)
|
|
1176
|
+
p_append.add_argument(
|
|
1177
|
+
"--output", required=True, help="Path to existing final feature-list.json"
|
|
1178
|
+
)
|
|
1179
|
+
p_append.add_argument(
|
|
1180
|
+
"--replace-tail",
|
|
1181
|
+
action="store_true",
|
|
1182
|
+
help="Replace the exact existing suffix with the same IDs after local review",
|
|
1183
|
+
)
|
|
1184
|
+
|
|
975
1185
|
# -- generate --
|
|
976
1186
|
p_generate = subparsers.add_parser(
|
|
977
1187
|
"generate",
|
|
@@ -1024,6 +1234,9 @@ def main():
|
|
|
1024
1234
|
dispatch = {
|
|
1025
1235
|
"validate": cmd_validate,
|
|
1026
1236
|
"template": cmd_template,
|
|
1237
|
+
"context": cmd_context,
|
|
1238
|
+
"show": cmd_show,
|
|
1239
|
+
"append": cmd_append,
|
|
1027
1240
|
"generate": cmd_generate,
|
|
1028
1241
|
"summary": cmd_summary,
|
|
1029
1242
|
"grade": cmd_grade,
|
|
@@ -142,7 +142,7 @@ Before questions, check optional context files (never block if absent):
|
|
|
142
142
|
- `.prizmkit/prizm-docs/root.prizm` (architecture/project context)
|
|
143
143
|
- `.prizmkit/config.json` (existing stack preferences and detected tech stack)
|
|
144
144
|
- Existing test suite (critical for behavior preservation assessment)
|
|
145
|
-
- Existing `.prizmkit/plans/refactor-list.json` (if appending additional items)
|
|
145
|
+
- Existing `.prizmkit/plans/refactor-list.json` (if appending additional items; inspect it only through the bounded commands below)
|
|
146
146
|
- If `.prizmkit/prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure:
|
|
147
147
|
```bash
|
|
148
148
|
find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
|
|
@@ -153,6 +153,28 @@ Before questions, check optional context files (never block if absent):
|
|
|
153
153
|
- If no test suite detected, WARN: "No test suite found. Behavior preservation will rely on manual verification. Consider writing tests before refactoring."
|
|
154
154
|
- Record test suite status in planning context for downstream use
|
|
155
155
|
|
|
156
|
+
## Bounded Existing-List Context (Hard Rule)
|
|
157
|
+
|
|
158
|
+
For any flow that appends to an existing `.prizmkit/plans/refactor-list.json`, NEVER read the complete historical list into AI context and NEVER perform default full-history keyword search.
|
|
159
|
+
|
|
160
|
+
1. Load only bounded project and recent-task context:
|
|
161
|
+
```bash
|
|
162
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py context --input .prizmkit/plans/refactor-list.json
|
|
163
|
+
```
|
|
164
|
+
Consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and exactly the five most recently appended top-level refactors as `{id, description}` pairs (or all available refactors when fewer than five exist).
|
|
165
|
+
2. Inspect those five 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.
|
|
166
|
+
3. When a material relationship exists, incorporate only the minimum exact information whose omission would make the new refactor's scope, behavior preservation, compatibility, acceptance criteria, or dependency ordering incorrect. Do not write vague text such as `related to R-123`, do not copy an entire historical description merely because it overlaps, and add an old ID to `dependencies` only when it is a real execution prerequisite.
|
|
167
|
+
4. Load a complete historical refactor only when the user explicitly identifies its ID for modification or detailed review, or a validation error identifies it:
|
|
168
|
+
```bash
|
|
169
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN
|
|
170
|
+
```
|
|
171
|
+
5. For append-only planning, write `.prizmkit/plans/refactor-list.draft.json` as an additions-only object with exactly one root field, `refactors`. The array must be non-empty; each item uses the unchanged final refactor-item schema, with required `id`, `title`, `description`, `scope`, `type`, `priority`, `complexity`, `behavior_preservation`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional refactor fields remain allowed. Do not copy root metadata or historical refactors into this draft.
|
|
172
|
+
6. Merge and validate outside AI context:
|
|
173
|
+
```bash
|
|
174
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
|
|
175
|
+
```
|
|
176
|
+
The command validates the existing base, sequential new IDs, dependencies, and the complete DAG before atomically replacing the final list. Existing `generate` behavior remains the full-draft path for a new list and explicit full-list rewrites.
|
|
177
|
+
|
|
156
178
|
## Operation Modes
|
|
157
179
|
|
|
158
180
|
### Mode A: Interactive (default)
|
|
@@ -293,12 +315,17 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
|
|
|
293
315
|
**Goal**: Produce `.prizmkit/plans/refactor-list.json` and validate it.
|
|
294
316
|
|
|
295
317
|
**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
|
|
296
|
-
1.
|
|
297
|
-
2.
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
318
|
+
1. For a new list, write the complete `.prizmkit/plans/refactor-list.draft.json`. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `refactors` object.
|
|
319
|
+
2. Use the matching deterministic writer:
|
|
320
|
+
- New list or explicit full-list rewrite:
|
|
321
|
+
```bash
|
|
322
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
|
|
323
|
+
```
|
|
324
|
+
- Ordinary existing-list append:
|
|
325
|
+
```bash
|
|
326
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
|
|
327
|
+
```
|
|
328
|
+
`generate` fills root defaults for a complete draft. `append` preserves root metadata and historical refactors, defaults missing new statuses, and writes only after the merged full list validates.
|
|
302
329
|
3. If validation fails -> fix the draft and retry (max 3 attempts)
|
|
303
330
|
4. If validation passes -> run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass
|
|
304
331
|
5. If review and validation pass -> present final summary
|
|
@@ -324,7 +351,7 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
|
|
|
324
351
|
|
|
325
352
|
Run this gate after `.prizmkit/plans/refactor-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final refactor entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
|
|
326
353
|
|
|
327
|
-
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final
|
|
354
|
+
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed refactor. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, rerun validation, and repeat local review until it returns `PASS` before reporting the result.
|
|
328
355
|
|
|
329
356
|
## Output Rules
|
|
330
357
|
|
|
@@ -10,7 +10,7 @@ For simple refactoring with minimal scope.
|
|
|
10
10
|
- Existing test coverage for target area
|
|
11
11
|
|
|
12
12
|
## Fast Path Workflow
|
|
13
|
-
1.
|
|
13
|
+
1. If `.prizmkit/plans/refactor-list.json` exists, run the parent Skill's bounded `context` command and consume only root context plus the five recent `{id, description}` pairs; never read the complete historical list or perform default keyword search. Then confirm refactoring scope with the user.
|
|
14
14
|
2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
|
|
15
15
|
|
|
16
16
|
```
|
|
@@ -31,12 +31,12 @@ For simple refactoring with minimal scope.
|
|
|
31
31
|
**NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
|
|
32
32
|
3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
|
|
33
33
|
4. Run the mandatory Phase 6 Headless Context Completeness Gate on every drafted item; repair the draft until each returns `PASS` without conversation history or `user_context`.
|
|
34
|
-
5. Write
|
|
34
|
+
5. Write `.prizmkit/plans/refactor-list.draft.json`. For a new list, use the complete final-list draft and `generate`; for an existing list, write only the additions-only `refactors` object and call:
|
|
35
35
|
```bash
|
|
36
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py
|
|
36
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
|
|
37
37
|
```
|
|
38
38
|
6. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill before summarizing or recommending `refactor-pipeline-launcher`.
|
|
39
|
-
7. If invalid -> apply fixes to the draft
|
|
39
|
+
7. If invalid -> apply fixes to the draft and re-run the same writer (`generate` for a new list, `append` for an existing list; max 2 attempts, then escalate to full workflow)
|
|
40
40
|
|
|
41
41
|
## When NOT to Use Fast Path
|
|
42
42
|
- More than 2 refactor items
|
|
@@ -8,22 +8,23 @@ Run only when the current `refactor-planner` session generated, appended, or rew
|
|
|
8
8
|
|
|
9
9
|
## Direct Artifact Reads
|
|
10
10
|
|
|
11
|
-
Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files
|
|
11
|
+
Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
|
|
12
12
|
|
|
13
|
-
- Final list: `.prizmkit/plans/refactor-list.json`
|
|
14
|
-
- Draft/source list when present: `.prizmkit/plans/refactor-list.draft.json`
|
|
15
|
-
- Pre-session final list snapshot if captured in memory before edits
|
|
13
|
+
- Final list: `.prizmkit/plans/refactor-list.json` — run the `context` command for root prose and recent IDs; do not load the complete historical list into AI context
|
|
14
|
+
- Draft/source list when present: `.prizmkit/plans/refactor-list.draft.json` — ordinary incremental flow contains only additions and may be read completely
|
|
15
|
+
- Pre-session final list snapshot if captured in memory before edits — retain only bounded root context, prior task count/next ID, and the five recent `{id, description}` pairs, not full history
|
|
16
16
|
- In-memory draft object if the session has not written a draft file yet
|
|
17
|
+
- Newly appended or explicitly modified final entries — load each known ID with `python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN`
|
|
17
18
|
|
|
18
19
|
Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whether planner output exists or changed. Do not invoke `/prizmkit-code-review` for this planner-output gate; `/prizmkit-code-review` remains the implementation/code-diff review gate after `/prizmkit-implement`.
|
|
19
20
|
|
|
20
21
|
## Review Scope
|
|
21
22
|
|
|
22
|
-
1.
|
|
23
|
-
2. Root project prose is reviewable content, not generator metadata.
|
|
24
|
-
3. Treat refactors as changed only when item fields changed; review newly added refactor IDs and changed refactor IDs
|
|
25
|
-
4. Preserve unchanged historical refactors.
|
|
26
|
-
5. If no snapshot exists, review all
|
|
23
|
+
1. For ordinary append flow, use the additions-only draft and the append result's stable refactor IDs (`R-*`) as the change set; do not compare complete pre/post historical arrays in AI context.
|
|
24
|
+
2. Root project prose is reviewable content, not generator metadata. Read it through `context`; review new or changed `project_description` and `global_context` even when no refactor item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
|
|
25
|
+
3. Treat refactors as changed only when item fields changed; load and review newly added refactor IDs and explicitly changed refactor IDs through `show`.
|
|
26
|
+
4. Preserve unchanged historical refactors. Do not load unchanged entries merely to establish review completeness. Use the full-list validator for dependency/DAG truth; use `show` for an old dependency or behavior-preservation interaction only when a specific reviewed refactor requires semantic inspection.
|
|
27
|
+
5. If no snapshot exists during initial generation, review all entries in that session's complete draft. Absence of a snapshot never authorizes loading unrelated history during append flow.
|
|
27
28
|
|
|
28
29
|
## Review Checklist
|
|
29
30
|
|
|
@@ -74,13 +75,21 @@ Do not add new JSON fields, context objects, schema versions, or pipeline runtim
|
|
|
74
75
|
1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
|
|
75
76
|
2. Accept only findings that improve planner correctness, completeness, or downstream behavior-preserving execution readiness.
|
|
76
77
|
3. Apply accepted fixes to `.prizmkit/plans/refactor-list.draft.json` or the in-memory draft object first.
|
|
77
|
-
4.
|
|
78
|
+
4. For an ordinary incremental additions-only draft, rerun the existing script's append command:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json --replace-tail
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`--replace-tail` is allowed only for the exact final-list suffix whose IDs match this session's additions, so accepted local-review fixes replace the current session's entries without duplicating or loading history. If the suffix does not match exactly, stop rather than rewriting another task.
|
|
85
|
+
|
|
86
|
+
For a new list or explicit full-list rewrite, regenerate through the existing script's complete-draft command:
|
|
78
87
|
|
|
79
88
|
```bash
|
|
80
89
|
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
|
|
81
90
|
```
|
|
82
91
|
|
|
83
|
-
5. Re-run
|
|
92
|
+
5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/refactor-list.json` as the source of truth.
|
|
84
93
|
6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
|
|
85
94
|
7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
|
|
86
95
|
|