prizmkit 1.1.174 → 1.1.176
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/rules/prizm/prizm-commit-workflow.md +3 -3
- package/bundled/skills/_metadata.json +1 -1
- package/bundled/skills/bug-planner/SKILL.md +46 -43
- package/bundled/skills/bug-planner/references/error-recovery.md +24 -24
- package/bundled/skills/bug-planner/references/generated-plan-review.md +24 -11
- package/bundled/skills/bug-planner/scripts/validate-bug-list.py +216 -1
- package/bundled/skills/feature-planner/SKILL.md +39 -30
- package/bundled/skills/feature-planner/references/error-recovery.md +25 -15
- package/bundled/skills/feature-planner/references/generated-plan-review.md +24 -11
- package/bundled/skills/feature-planner/references/incremental-feature-planning.md +85 -70
- package/bundled/skills/feature-planner/references/new-project-planning.md +7 -4
- package/bundled/skills/feature-planner/scripts/validate-and-generate.py +213 -0
- package/bundled/skills/prizmkit/SKILL.md +5 -5
- package/bundled/skills/prizmkit-committer/SKILL.md +21 -24
- package/bundled/skills/prizmkit-workflow/SKILL.md +8 -8
- package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +5 -5
- package/bundled/skills/refactor-planner/SKILL.md +47 -14
- package/bundled/skills/refactor-planner/references/error-recovery.md +16 -8
- package/bundled/skills/refactor-planner/references/fast-path.md +6 -5
- package/bundled/skills/refactor-planner/references/generated-plan-review.md +24 -11
- package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +213 -0
- package/package.json +1 -1
|
@@ -5,10 +5,16 @@ for the dev-pipeline system.
|
|
|
5
5
|
|
|
6
6
|
Commands:
|
|
7
7
|
validate Validate an existing bug-fix-list.json
|
|
8
|
+
context Print bounded project context plus the five most recent bugs
|
|
9
|
+
show Print one explicitly requested bug
|
|
10
|
+
append Merge an additions-only draft into an existing validated list
|
|
8
11
|
generate Validate a draft JSON and generate final bug-fix-list.json with defaults
|
|
9
12
|
|
|
10
13
|
Usage:
|
|
11
14
|
python3 validate-bug-list.py validate .prizmkit/plans/bug-fix-list.json [--feature-list .prizmkit/plans/feature-list.json]
|
|
15
|
+
python3 validate-bug-list.py context --input .prizmkit/plans/bug-fix-list.json
|
|
16
|
+
python3 validate-bug-list.py show --input .prizmkit/plans/bug-fix-list.json --id B-001
|
|
17
|
+
python3 validate-bug-list.py append --input additions.json --output .prizmkit/plans/bug-fix-list.json
|
|
12
18
|
python3 validate-bug-list.py generate --input draft.json --output .prizmkit/plans/bug-fix-list.json
|
|
13
19
|
|
|
14
20
|
Exit codes:
|
|
@@ -20,10 +26,12 @@ Python 3.6+ required. No external dependencies.
|
|
|
20
26
|
"""
|
|
21
27
|
|
|
22
28
|
import argparse
|
|
29
|
+
import copy
|
|
23
30
|
import json
|
|
24
31
|
import sys
|
|
25
32
|
import os
|
|
26
33
|
import re
|
|
34
|
+
import tempfile
|
|
27
35
|
from datetime import datetime, timezone
|
|
28
36
|
|
|
29
37
|
VALID_SEVERITIES = {"critical", "high", "medium", "low"}
|
|
@@ -120,6 +128,25 @@ def _write_json(path, data):
|
|
|
120
128
|
f.write("\n")
|
|
121
129
|
|
|
122
130
|
|
|
131
|
+
def _write_json_atomic(path, data):
|
|
132
|
+
"""Atomically replace *path* with pretty-printed JSON data."""
|
|
133
|
+
parent = os.path.dirname(os.path.abspath(path))
|
|
134
|
+
if parent and not os.path.isdir(parent):
|
|
135
|
+
os.makedirs(parent, exist_ok=True)
|
|
136
|
+
fd, temp_path = tempfile.mkstemp(prefix=".bug-fix-list-", suffix=".tmp", dir=parent)
|
|
137
|
+
try:
|
|
138
|
+
with os.fdopen(fd, "w", encoding="utf-8") as f:
|
|
139
|
+
json.dump(data, f, indent=2, ensure_ascii=False)
|
|
140
|
+
f.write("\n")
|
|
141
|
+
os.replace(temp_path, path)
|
|
142
|
+
except Exception:
|
|
143
|
+
try:
|
|
144
|
+
os.unlink(temp_path)
|
|
145
|
+
except OSError:
|
|
146
|
+
pass
|
|
147
|
+
raise
|
|
148
|
+
|
|
149
|
+
|
|
123
150
|
def validate(data, feature_ids=None):
|
|
124
151
|
"""Validate a parsed bug-fix-list data structure.
|
|
125
152
|
|
|
@@ -317,6 +344,148 @@ def cmd_validate(args):
|
|
|
317
344
|
return 1
|
|
318
345
|
|
|
319
346
|
|
|
347
|
+
def _load_valid_existing(path):
|
|
348
|
+
"""Load and validate one existing bug list."""
|
|
349
|
+
data, load_err = _load_json(path)
|
|
350
|
+
if load_err:
|
|
351
|
+
_err(load_err)
|
|
352
|
+
return None, None, 2
|
|
353
|
+
if not isinstance(data, dict):
|
|
354
|
+
_err("Bug list root must be an object")
|
|
355
|
+
return None, None, 1
|
|
356
|
+
|
|
357
|
+
result = validate(data)
|
|
358
|
+
if not result["valid"]:
|
|
359
|
+
_err("Existing bug list is invalid")
|
|
360
|
+
for error in result["errors"]:
|
|
361
|
+
_err(" " + error)
|
|
362
|
+
return None, result, 1
|
|
363
|
+
return data, result, 0
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
def _next_top_level_id(bugs):
|
|
367
|
+
"""Return the next B-NNN ID, or None when numeric capacity is exhausted."""
|
|
368
|
+
numbers = []
|
|
369
|
+
for bug in bugs:
|
|
370
|
+
match = BUG_ID_PATTERN.match(str(bug.get("id", "")))
|
|
371
|
+
if match:
|
|
372
|
+
numbers.append(int(str(bug["id"])[2:]))
|
|
373
|
+
next_number = max(numbers, default=0) + 1
|
|
374
|
+
if next_number > 999:
|
|
375
|
+
return None
|
|
376
|
+
return "B-{:03d}".format(next_number)
|
|
377
|
+
|
|
378
|
+
|
|
379
|
+
def cmd_context(args):
|
|
380
|
+
"""Print bounded existing-list context for incremental planning."""
|
|
381
|
+
data, _, exit_code = _load_valid_existing(args.input)
|
|
382
|
+
if exit_code:
|
|
383
|
+
return exit_code
|
|
384
|
+
|
|
385
|
+
bugs = data["bugs"]
|
|
386
|
+
next_id = _next_top_level_id(bugs)
|
|
387
|
+
if next_id is None:
|
|
388
|
+
_err("Bug ID capacity exhausted at B-999")
|
|
389
|
+
return 1
|
|
390
|
+
|
|
391
|
+
context = {
|
|
392
|
+
"project_name": data.get("project_name"),
|
|
393
|
+
"project_description": data.get("project_description"),
|
|
394
|
+
"global_context": data.get("global_context") or {},
|
|
395
|
+
"task_count": len(bugs),
|
|
396
|
+
"next_id": next_id,
|
|
397
|
+
"recent_tasks": [
|
|
398
|
+
{"id": bug.get("id"), "description": bug.get("description")}
|
|
399
|
+
for bug in bugs[-5:]
|
|
400
|
+
],
|
|
401
|
+
}
|
|
402
|
+
print(json.dumps(context, indent=2, ensure_ascii=False))
|
|
403
|
+
return 0
|
|
404
|
+
|
|
405
|
+
|
|
406
|
+
def cmd_show(args):
|
|
407
|
+
"""Print one explicitly requested top-level bug."""
|
|
408
|
+
data, _, exit_code = _load_valid_existing(args.input)
|
|
409
|
+
if exit_code:
|
|
410
|
+
return exit_code
|
|
411
|
+
if not BUG_ID_PATTERN.match(str(args.id)):
|
|
412
|
+
_err("Bug ID '{}' must match B-NNN".format(args.id))
|
|
413
|
+
return 1
|
|
414
|
+
|
|
415
|
+
for bug in data["bugs"]:
|
|
416
|
+
if bug.get("id") == args.id:
|
|
417
|
+
print(json.dumps(bug, indent=2, ensure_ascii=False))
|
|
418
|
+
return 0
|
|
419
|
+
_err("Bug '{}' not found".format(args.id))
|
|
420
|
+
return 1
|
|
421
|
+
|
|
422
|
+
|
|
423
|
+
def cmd_append(args):
|
|
424
|
+
"""Append a collection-only draft to an existing validated bug list."""
|
|
425
|
+
base, _, exit_code = _load_valid_existing(args.output)
|
|
426
|
+
if exit_code:
|
|
427
|
+
return exit_code
|
|
428
|
+
|
|
429
|
+
draft, load_err = _load_json(args.input)
|
|
430
|
+
if load_err:
|
|
431
|
+
_err(load_err)
|
|
432
|
+
return 2
|
|
433
|
+
if not isinstance(draft, dict) or set(draft.keys()) != {"bugs"}:
|
|
434
|
+
_err("Additions draft must be an object containing only 'bugs'")
|
|
435
|
+
return 1
|
|
436
|
+
additions = draft.get("bugs")
|
|
437
|
+
if not isinstance(additions, list) or not additions:
|
|
438
|
+
_err("Additions draft 'bugs' must be a non-empty array")
|
|
439
|
+
return 1
|
|
440
|
+
if not all(isinstance(bug, dict) for bug in additions):
|
|
441
|
+
_err("Every bug addition must be an object")
|
|
442
|
+
return 1
|
|
443
|
+
|
|
444
|
+
merge_base = copy.deepcopy(base)
|
|
445
|
+
if args.replace_tail:
|
|
446
|
+
addition_ids = [bug.get("id") for bug in additions]
|
|
447
|
+
tail_ids = [bug.get("id") for bug in base["bugs"][-len(additions):]]
|
|
448
|
+
if len(base["bugs"]) < len(additions) or tail_ids != addition_ids:
|
|
449
|
+
_err("--replace-tail requires additions IDs to match the existing final-list suffix exactly")
|
|
450
|
+
return 1
|
|
451
|
+
merge_base["bugs"] = merge_base["bugs"][:-len(additions)]
|
|
452
|
+
|
|
453
|
+
next_id = _next_top_level_id(merge_base["bugs"])
|
|
454
|
+
if next_id is None:
|
|
455
|
+
_err("Bug ID capacity exhausted at B-999")
|
|
456
|
+
return 1
|
|
457
|
+
start_number = int(next_id[2:])
|
|
458
|
+
prepared = copy.deepcopy(additions)
|
|
459
|
+
for offset, bug in enumerate(prepared):
|
|
460
|
+
expected_id = "B-{:03d}".format(start_number + offset)
|
|
461
|
+
if start_number + offset > 999:
|
|
462
|
+
_err("Bug ID capacity exhausted at B-999")
|
|
463
|
+
return 1
|
|
464
|
+
if bug.get("id") != expected_id:
|
|
465
|
+
_err("Bug addition {} must use next sequential ID '{}'".format(offset, expected_id))
|
|
466
|
+
return 1
|
|
467
|
+
bug.setdefault("status", "pending")
|
|
468
|
+
|
|
469
|
+
merged = copy.deepcopy(merge_base)
|
|
470
|
+
merged["bugs"].extend(prepared)
|
|
471
|
+
result = validate(merged)
|
|
472
|
+
result["appended_ids"] = [bug["id"] for bug in prepared]
|
|
473
|
+
print(json.dumps(result, indent=2, ensure_ascii=False))
|
|
474
|
+
if not result["valid"]:
|
|
475
|
+
_err("Merged bug list validation failed")
|
|
476
|
+
for error in result["errors"]:
|
|
477
|
+
_err(" " + error)
|
|
478
|
+
return 1
|
|
479
|
+
|
|
480
|
+
try:
|
|
481
|
+
_write_json_atomic(args.output, merged)
|
|
482
|
+
except Exception as exc:
|
|
483
|
+
_err("Failed to write merged bug list: {}".format(exc))
|
|
484
|
+
return 2
|
|
485
|
+
_info("Appended {} bug(s) to {}".format(len(prepared), args.output))
|
|
486
|
+
return 0
|
|
487
|
+
|
|
488
|
+
|
|
320
489
|
def cmd_generate(args):
|
|
321
490
|
"""Handle the 'generate' command.
|
|
322
491
|
|
|
@@ -366,7 +535,9 @@ def cmd_generate(args):
|
|
|
366
535
|
def main():
|
|
367
536
|
# Backward compatibility: if first arg is a file path (not a subcommand),
|
|
368
537
|
# treat it as 'validate' command
|
|
369
|
-
if len(sys.argv) > 1 and not sys.argv[1].startswith("-") and sys.argv[1] not in (
|
|
538
|
+
if len(sys.argv) > 1 and not sys.argv[1].startswith("-") and sys.argv[1] not in (
|
|
539
|
+
"validate", "context", "show", "append", "generate"
|
|
540
|
+
):
|
|
370
541
|
sys.argv.insert(1, "validate")
|
|
371
542
|
|
|
372
543
|
parser = argparse.ArgumentParser(
|
|
@@ -376,6 +547,9 @@ def main():
|
|
|
376
547
|
"Examples:\n"
|
|
377
548
|
" %(prog)s validate .prizmkit/plans/bug-fix-list.json\n"
|
|
378
549
|
" %(prog)s validate .prizmkit/plans/bug-fix-list.json --feature-list .prizmkit/plans/feature-list.json\n"
|
|
550
|
+
" %(prog)s context --input .prizmkit/plans/bug-fix-list.json\n"
|
|
551
|
+
" %(prog)s show --input .prizmkit/plans/bug-fix-list.json --id B-001\n"
|
|
552
|
+
" %(prog)s append --input additions.json --output .prizmkit/plans/bug-fix-list.json\n"
|
|
379
553
|
" %(prog)s generate --input draft.json --output .prizmkit/plans/bug-fix-list.json\n"
|
|
380
554
|
),
|
|
381
555
|
)
|
|
@@ -394,6 +568,44 @@ def main():
|
|
|
394
568
|
"--feature-list", default=None, help="Path to feature-list.json for cross-reference"
|
|
395
569
|
)
|
|
396
570
|
|
|
571
|
+
# -- context --
|
|
572
|
+
p_context = subparsers.add_parser(
|
|
573
|
+
"context",
|
|
574
|
+
help="Print root context and the five most recent bug id/description pairs",
|
|
575
|
+
)
|
|
576
|
+
p_context.add_argument(
|
|
577
|
+
"--input", required=True, help="Path to existing .prizmkit/plans/bug-fix-list.json"
|
|
578
|
+
)
|
|
579
|
+
|
|
580
|
+
# -- show --
|
|
581
|
+
p_show = subparsers.add_parser(
|
|
582
|
+
"show",
|
|
583
|
+
help="Print one explicitly requested top-level bug",
|
|
584
|
+
)
|
|
585
|
+
p_show.add_argument(
|
|
586
|
+
"--input", required=True, help="Path to existing .prizmkit/plans/bug-fix-list.json"
|
|
587
|
+
)
|
|
588
|
+
p_show.add_argument(
|
|
589
|
+
"--id", required=True, help="Exact top-level bug ID"
|
|
590
|
+
)
|
|
591
|
+
|
|
592
|
+
# -- append --
|
|
593
|
+
p_append = subparsers.add_parser(
|
|
594
|
+
"append",
|
|
595
|
+
help="Append a bugs-only draft to an existing validated bug list",
|
|
596
|
+
)
|
|
597
|
+
p_append.add_argument(
|
|
598
|
+
"--input", required=True, help="Path to additions-only draft JSON"
|
|
599
|
+
)
|
|
600
|
+
p_append.add_argument(
|
|
601
|
+
"--output", required=True, help="Path to existing final bug-fix-list.json"
|
|
602
|
+
)
|
|
603
|
+
p_append.add_argument(
|
|
604
|
+
"--replace-tail",
|
|
605
|
+
action="store_true",
|
|
606
|
+
help="Replace the exact existing suffix with the same IDs after local review",
|
|
607
|
+
)
|
|
608
|
+
|
|
397
609
|
# -- generate --
|
|
398
610
|
p_generate = subparsers.add_parser(
|
|
399
611
|
"generate",
|
|
@@ -414,6 +626,9 @@ def main():
|
|
|
414
626
|
|
|
415
627
|
dispatch = {
|
|
416
628
|
"validate": cmd_validate,
|
|
629
|
+
"context": cmd_context,
|
|
630
|
+
"show": cmd_show,
|
|
631
|
+
"append": cmd_append,
|
|
417
632
|
"generate": cmd_generate,
|
|
418
633
|
}
|
|
419
634
|
|
|
@@ -48,7 +48,7 @@ The user chose this skill intentionally. Respect that choice.
|
|
|
48
48
|
|
|
49
49
|
**Your ONLY writable outputs are:**
|
|
50
50
|
1. `.prizmkit/plans/feature-list.json` (`.prizmkit/plans/`)
|
|
51
|
-
2.
|
|
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
|
|
52
52
|
|
|
53
53
|
**After planning is complete**, you MUST:
|
|
54
54
|
1. Present the summary and recommended next step (invoking `feature-pipeline-launcher` )
|
|
@@ -57,6 +57,10 @@ The user chose this skill intentionally. Respect that choice.
|
|
|
57
57
|
4. **NEVER auto-execute** the pipeline, launcher, composite workflow, or any implementation step
|
|
58
58
|
5. Return the validated list to the caller; only `feature-pipeline-launcher` prepares the runtime command
|
|
59
59
|
|
|
60
|
+
## Draft Lifecycle (Hard Rule)
|
|
61
|
+
|
|
62
|
+
In an ordinary successful flow, `.prizmkit/plans/feature-list.draft.json` is internal writer/review input, not a user approval artifact or separate deliverable. Keep it through `generate`/`append`, validation, and the complete Local Generated-Plan Review fix loop. After the Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. Report `Draft cleanup: removed`. Present the final written result. Retain the draft only for explicit draft-save, interruption or blocking before terminal gates, or cleanup failure; report its path and reason. Cleanup failure does not invalidate an already reviewed and validated final list, but makes the file stale recovery state. Never delete explicit recovery state merely because an older valid final exists. For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; ordinary appends must preserve the exact current suffix and use `append --replace-tail` without loading unrelated history.
|
|
63
|
+
|
|
60
64
|
## Fresh-Session Task Contract (Hard Rule)
|
|
61
65
|
|
|
62
66
|
Every new or changed feature is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
|
|
@@ -149,7 +153,7 @@ Before questions, check optional context files (never block if absent):
|
|
|
149
153
|
- `.prizmkit/prizm-docs/root.prizm` (architecture/project context — typically created by app-planner with captured decisions)
|
|
150
154
|
- `.prizmkit/config.json` (existing stack preferences and detected tech stack)
|
|
151
155
|
- `.prizmkit/plans/project-brief.md` (project context from app-planner, if available)
|
|
152
|
-
- existing `.prizmkit/plans/feature-list.json` (required for incremental mode)
|
|
156
|
+
- existing `.prizmkit/plans/feature-list.json` (required for incremental mode; inspect it only through the bounded commands below)
|
|
153
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, `claude` → `CLAUDE.md`, `codebuddy` → `CODEBUDDY.md`, `all` → read every matching file). Legacy manifests may contain `both`; treat it as read-only compatibility and read `CLAUDE.md` plus `CODEBUDDY.md` only when encountered.
|
|
154
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:
|
|
155
159
|
```bash
|
|
@@ -231,11 +235,16 @@ F-003 | Tooltip copy update | low | Cosmetic clarity only |
|
|
|
231
235
|
|
|
232
236
|
Anti-pattern rule: do not assign every generated item `Priority: high` and `Complexity: high` unless each item independently satisfies the documented high criteria and its rationale names those criteria. In feature JSON this means `estimated_complexity: high`; in user-facing review summaries label the column `Complexity`.
|
|
233
237
|
|
|
234
|
-
|
|
235
238
|
---
|
|
236
|
-
|
|
239
|
+
## 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 internal transport/recovery state, not a user approval artifact. 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, immediately run `append`: `python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json`. Do not ask for separate user approval merely to promote the draft into the final list. The command validates the base, IDs, dependencies, and complete DAG before atomic replacement. Apply review fixes only to the bounded additions and rerun `append --replace-tail` for the exact current suffix, then follow §Draft Lifecycle before presenting the final written result. `generate` remains the initial-plan/full-rewrite path.
|
|
237
247
|
## Scenario Routing
|
|
238
|
-
|
|
239
248
|
Classify user intent first:
|
|
240
249
|
|
|
241
250
|
### Route A: Initial Feature Set for Existing/App-Planned Project
|
|
@@ -251,9 +260,9 @@ Use when user already has a `.prizmkit/plans/feature-list.json` and wants to add
|
|
|
251
260
|
|
|
252
261
|
Actions:
|
|
253
262
|
1. Load `${SKILL_DIR}/references/incremental-feature-planning.md`
|
|
254
|
-
2.
|
|
255
|
-
3. Append features with next sequential `F-NNN` IDs
|
|
256
|
-
4. Preserve
|
|
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
|
|
257
266
|
|
|
258
267
|
### Route C: Validate Existing Plan
|
|
259
268
|
Use when the user asks to check or validate an existing plan without adding or changing features.
|
|
@@ -305,8 +314,8 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
|
|
|
305
314
|
7. Build or append `.prizmkit/plans/feature-list.json`
|
|
306
315
|
8. Apply default testing strategy (see §Testing Defaults below)
|
|
307
316
|
9. Validate and fix until pass
|
|
308
|
-
10. 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
|
|
309
|
-
11. Summarize final feature table with local review result and
|
|
317
|
+
10. 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, then complete §Draft Lifecycle cleanup
|
|
318
|
+
11. Summarize final feature table with local review result, validation outcome, and draft cleanup result
|
|
310
319
|
|
|
311
320
|
### Checkpoints (Mandatory Gates)
|
|
312
321
|
|
|
@@ -322,7 +331,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
|
|
|
322
331
|
| **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 |
|
|
323
332
|
| **CP-FP-4** | `.prizmkit/plans/feature-list.json` Generated | Schema validates, all required keys present | 7-8 |
|
|
324
333
|
| **CP-FP-5** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 9 |
|
|
325
|
-
| **CP-FP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed feature entries, applied accepted fixes through draft/source data, regenerated, and
|
|
334
|
+
| **CP-FP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed feature entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained | 10-11 |
|
|
326
335
|
|
|
327
336
|
**Resume Detection**: If existing artifacts are found, read `${SKILL_DIR}/references/error-recovery.md` §Resume Support for checkpoint-based resumption.
|
|
328
337
|
|
|
@@ -347,7 +356,7 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
|
|
|
347
356
|
- **No architectural changes** to existing tech stack
|
|
348
357
|
|
|
349
358
|
### Fast Path Workflow
|
|
350
|
-
1.
|
|
359
|
+
1. Run the bounded `context` command from §Bounded Existing-List Context and confirm scope without reading the complete historical list
|
|
351
360
|
2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
|
|
352
361
|
|
|
353
362
|
```
|
|
@@ -369,12 +378,12 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
|
|
|
369
378
|
3. Generate next sequential feature IDs
|
|
370
379
|
4. Draft features (title + description + acceptance_criteria + dependencies)
|
|
371
380
|
5. Run the mandatory pre-generation Headless Context Completeness Gate from Phase 6 on every drafted feature; repair the draft until each returns `PASS`.
|
|
372
|
-
6. Write
|
|
381
|
+
6. Write the additions-only draft as internal input and immediately call the append command without a second draft-approval pause:
|
|
373
382
|
```bash
|
|
374
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate.py
|
|
383
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
375
384
|
```
|
|
376
|
-
7. If valid → run the mandatory Local Generated-Plan Review Gate, then
|
|
377
|
-
8. If invalid → apply fixes to the draft, re-run
|
|
385
|
+
7. If valid → run the mandatory Local Generated-Plan Review Gate, complete §Draft Lifecycle cleanup, then present the final written result and recommend the next step
|
|
386
|
+
8. If invalid → apply fixes to the additions-only draft, re-run `append` (max 2 attempts, then escalate to full workflow)
|
|
378
387
|
|
|
379
388
|
## Browser Interaction Planning
|
|
380
389
|
|
|
@@ -415,18 +424,22 @@ Key requirements:
|
|
|
415
424
|
- `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.
|
|
416
425
|
|
|
417
426
|
**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
427
|
+
- Initial plan or explicit full-list rewrite: write the complete draft and use `generate`:
|
|
428
|
+
```bash
|
|
429
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
430
|
+
```
|
|
431
|
+
- Ordinary incremental append: follow §Bounded Existing-List Context, write only the additions-only `features` object, and use `append`:
|
|
432
|
+
```bash
|
|
433
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
`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, call `append` immediately after semantic gates; the draft is not a second approval checkpoint. If either command fails, fix its source draft and retry. Do not delete the draft until the Local Generated-Plan Review and final validation pass; then follow §Draft Lifecycle.
|
|
424
437
|
|
|
425
438
|
## Local Generated-Plan Review Gate
|
|
426
439
|
|
|
427
440
|
Run this gate after `.prizmkit/plans/feature-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final feature entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
|
|
428
441
|
|
|
429
|
-
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final
|
|
442
|
+
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 feature. Keep the review planning-only, apply accepted findings to the draft/source representation, update ordinary appended entries through `append --replace-tail`, rerun validation, and repeat the local review until it returns `PASS`. Complete §Draft Lifecycle cleanup before reporting the final written result.
|
|
430
443
|
|
|
431
444
|
## Testing Defaults (Phase 8)
|
|
432
445
|
|
|
@@ -450,11 +463,7 @@ Recommend invoking `feature-pipeline-launcher` to configure and launch the dev-p
|
|
|
450
463
|
|
|
451
464
|
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.
|
|
452
465
|
|
|
453
|
-
Key behaviors:
|
|
454
|
-
- Warnings only → proceed with user approval
|
|
455
|
-
- Critical errors → group by type, auto-fix where possible, max 3 total attempts
|
|
456
|
-
- Interrupted session → detect checkpoint from existing artifacts, offer resume or restart
|
|
457
|
-
- `.prizmkit/plans/feature-list.json` MUST be written to `.prizmkit/plans/` (project root level: `./{root}/.prizmkit/plans/feature-list.json`)
|
|
466
|
+
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`.
|
|
458
467
|
|
|
459
468
|
## Session Exit Gate
|
|
460
469
|
|
|
@@ -471,7 +480,7 @@ When the session appears to be ending:
|
|
|
471
480
|
1. **Remind**: "You set out to produce `.prizmkit/plans/feature-list.json` but we haven't completed it yet."
|
|
472
481
|
2. Use `AskUserQuestion` with one question:
|
|
473
482
|
- **Continue to completion (Recommended)** — resume from current phase
|
|
474
|
-
- **Save draft & exit** — write current progress as `.prizmkit/plans/feature-list.draft.json`
|
|
483
|
+
- **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
|
|
475
484
|
- **Abandon** — exit without saving
|
|
476
485
|
|
|
477
486
|
## Handoff Message Template
|
|
@@ -480,7 +489,7 @@ After successful validation and the Local Generated-Plan Review Gate, report:
|
|
|
480
489
|
1. Output file path
|
|
481
490
|
2. Total features + newly added features
|
|
482
491
|
3. Dependency and priority highlights
|
|
483
|
-
4. Local generated-plan review result: verdict, reviewed feature IDs plus reviewed root prose when applicable, accepted fixes (or "none"),
|
|
492
|
+
4. Local generated-plan review result: verdict, reviewed feature IDs plus reviewed root prose when applicable, accepted fixes (or "none"), final validation result, and draft cleanup result (`removed` or retained path/reason)
|
|
484
493
|
5. Recommended next action: `feature-pipeline-launcher`
|
|
485
494
|
|
|
486
495
|
Then apply the post-planning handoff in §Scope Boundary (ask before proceeding; never auto-execute).
|
|
@@ -12,8 +12,8 @@ Script returns JSON with `"valid": false`, `"errors": [...]`, `"warnings": [...]
|
|
|
12
12
|
### Decision Tree
|
|
13
13
|
|
|
14
14
|
**if `error_count == 0` (warnings only):**
|
|
15
|
-
-
|
|
16
|
-
-
|
|
15
|
+
- Continue the deterministic writer/review flow when warnings are informational
|
|
16
|
+
- Ask the user only when a warning exposes a consequential product, scope, compatibility, or verification decision; do not add a generic draft-promotion approval
|
|
17
17
|
|
|
18
18
|
**elif `error_count > 0` (critical errors):**
|
|
19
19
|
|
|
@@ -34,15 +34,14 @@ Group errors by type and apply targeted fixes:
|
|
|
34
34
|
```
|
|
35
35
|
For auto-fixable errors:
|
|
36
36
|
1. Show summary: "Found N schema/ID/format issues"
|
|
37
|
-
2.
|
|
38
|
-
3.
|
|
39
|
-
4.
|
|
40
|
-
5. If new errors → loop (max 2 more attempts)
|
|
37
|
+
2. Apply unambiguous mechanical fixes to the planner-owned draft
|
|
38
|
+
3. Re-run the matching deterministic writer and validation
|
|
39
|
+
4. If new errors → loop (max 2 more attempts)
|
|
41
40
|
|
|
42
|
-
For
|
|
43
|
-
1.
|
|
44
|
-
2.
|
|
45
|
-
3.
|
|
41
|
+
For semantic fixes (dependencies, acceptance-criteria content):
|
|
42
|
+
1. Ask only for the consequential missing decision
|
|
43
|
+
2. Apply the confirmed correction to the planner-owned draft, never directly to the final list
|
|
44
|
+
3. Re-run the matching writer and validation (max 2 more attempts)
|
|
46
45
|
|
|
47
46
|
if all_retries_exceeded:
|
|
48
47
|
→ Escalate: "After 3 attempts, validation still fails.
|
|
@@ -61,13 +60,16 @@ Check for artifact files in `.prizmkit/plans/`:
|
|
|
61
60
|
| Artifacts Found | Resume Action |
|
|
62
61
|
|-----------------|---------------|
|
|
63
62
|
| None | Start fresh planning (Phase 1) |
|
|
64
|
-
| `feature-list.json` exists but not validated |
|
|
65
|
-
| `feature-list.json`
|
|
66
|
-
| `feature-list.draft.json` only | Resume interactive planning from
|
|
63
|
+
| `feature-list.json` exists but not validated | Resume writer/validation repair through the source draft |
|
|
64
|
+
| Valid `feature-list.json` only | Offer handoff to `feature-pipeline-launcher` |
|
|
65
|
+
| `feature-list.draft.json` only | Resume interactive planning from the draft's actual completeness |
|
|
66
|
+
| Valid `feature-list.json` plus `feature-list.draft.json` | Treat as interrupted review or cleanup-failure state; inspect the draft and offer to resume review, discard it, or start a new increment rather than assuming either artifact wins |
|
|
67
67
|
|
|
68
|
-
When
|
|
68
|
+
When only a valid final list is detected, suggest:
|
|
69
69
|
> "Existing plan found with N features. Resume incremental planning? (Y/n)"
|
|
70
70
|
|
|
71
|
+
When final and draft both exist, identify the two artifacts explicitly and ask whether to resume the unfinished review/recovery state or discard it before starting a new increment.
|
|
72
|
+
|
|
71
73
|
### Incremental Mode Abort
|
|
72
74
|
|
|
73
75
|
If in Incremental mode but existing `feature-list.json` not found:
|
|
@@ -84,8 +86,16 @@ Before writing, verify the directory exists: `mkdir -p .prizmkit/plans`
|
|
|
84
86
|
<project-root>/
|
|
85
87
|
└── .prizmkit/plans/
|
|
86
88
|
├── feature-list.json # Primary output
|
|
87
|
-
├── feature-list.draft.json #
|
|
89
|
+
├── feature-list.draft.json # Temporary writer/review input or explicit recovery state
|
|
88
90
|
└── <ISO-timestamp>.backup.json # Optional incremental backups
|
|
89
91
|
```
|
|
90
92
|
|
|
93
|
+
## Draft Management
|
|
94
|
+
|
|
95
|
+
- An ordinary writer draft must remain available while generation, append, validation, or Local Generated-Plan Review repair is incomplete.
|
|
96
|
+
- After Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before handoff.
|
|
97
|
+
- Retain a draft only after explicit **Save draft & exit**, interruption or blocking before terminal gates, or cleanup failure. Report its path and reason.
|
|
98
|
+
- Cleanup failure does not invalidate a reviewed and validated final list, but the retained file is stale recovery state and must be surfaced.
|
|
99
|
+
- If both final and draft exist on resume, do not delete or promote the draft blindly. Determine whether review was interrupted or cleanup failed from the artifacts and available session evidence; ask the user when that outcome remains ambiguous.
|
|
100
|
+
|
|
91
101
|
> **Note**: For cross-session workflow recovery (e.g., interrupted pipeline execution, branch-level state detection), use `recovery-workflow` instead. This error-recovery reference handles only within-session validation retries and checkpoint resumption.
|
|
@@ -6,24 +6,27 @@ Use this local review loop after `.prizmkit/plans/feature-list.json` has been ge
|
|
|
6
6
|
|
|
7
7
|
Run only when the current `feature-planner` session generated, appended, or rewrote final feature planning content. For validate-only, summary-only, or draft-save flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
|
|
8
8
|
|
|
9
|
+
In ordinary incremental flow, the additions draft is internal transport/recovery state. After consequential decisions and the pre-generation gate pass, immediately run `append`; do not ask for separate user approval merely to promote the draft into the final list. Keep the draft through the bounded review/fix loop, then delete the ordinary internal draft before final handoff only after this review returns `PASS` and final validation passes.
|
|
10
|
+
|
|
9
11
|
## Direct Artifact Reads
|
|
10
12
|
|
|
11
|
-
Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files
|
|
13
|
+
Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
|
|
12
14
|
|
|
13
|
-
- Final list: `.prizmkit/plans/feature-list.json`
|
|
14
|
-
- Draft/source list when present: `.prizmkit/plans/feature-list.draft.json`
|
|
15
|
-
- Pre-session final list snapshot if captured in memory before edits
|
|
15
|
+
- Final list: `.prizmkit/plans/feature-list.json` — run the `context` command for root prose and recent IDs; do not load the complete historical list into AI context
|
|
16
|
+
- Draft/source list when present: `.prizmkit/plans/feature-list.draft.json` — ordinary incremental flow contains only additions and may be read completely
|
|
17
|
+
- 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
18
|
- In-memory draft object if the session has not written a draft file yet
|
|
19
|
+
- Newly appended or explicitly modified final entries — load each known ID with `python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-NNN`
|
|
17
20
|
|
|
18
21
|
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
22
|
|
|
20
23
|
## Review Scope
|
|
21
24
|
|
|
22
|
-
1.
|
|
23
|
-
2. Root project prose is reviewable content, not generator metadata.
|
|
24
|
-
3. Treat features as changed only when item fields changed; review newly added feature IDs and changed feature IDs
|
|
25
|
-
4. Preserve unchanged historical features.
|
|
26
|
-
5. If no snapshot exists, review all
|
|
25
|
+
1. For ordinary append flow, use the additions-only draft and the append result's stable feature IDs (`F-*`) as the change set; do not compare complete pre/post historical arrays in AI context.
|
|
26
|
+
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 feature item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
|
|
27
|
+
3. Treat features as changed only when item fields changed; load and review newly added feature IDs and explicitly changed feature IDs through `show`.
|
|
28
|
+
4. Preserve unchanged historical features. 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 only when a specific reviewed feature requires semantic inspection of that prerequisite.
|
|
29
|
+
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
30
|
|
|
28
31
|
## Review Checklist
|
|
29
32
|
|
|
@@ -75,15 +78,24 @@ Do not add new JSON fields, context objects, schema versions, or pipeline runtim
|
|
|
75
78
|
1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
|
|
76
79
|
2. Accept only findings that improve planner correctness, completeness, or downstream execution readiness.
|
|
77
80
|
3. Apply accepted fixes to `.prizmkit/plans/feature-list.draft.json` or the in-memory draft object first.
|
|
78
|
-
4.
|
|
81
|
+
4. For an ordinary incremental additions-only draft, rerun the existing script's append command:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --replace-tail
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`--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.
|
|
88
|
+
|
|
89
|
+
For an initial plan or explicit full-list rewrite, regenerate through the existing script's complete-draft command:
|
|
79
90
|
|
|
80
91
|
```bash
|
|
81
92
|
python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
82
93
|
```
|
|
83
94
|
|
|
84
|
-
5. Re-run
|
|
95
|
+
5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/feature-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
|
|
85
96
|
6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
|
|
86
97
|
7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
|
|
98
|
+
8. After `PASS`, delete `.prizmkit/plans/feature-list.draft.json` before final handoff when it is an ordinary internal draft. Retain it only for explicit draft-save, interruption or blocking before the terminal gates, or cleanup failure; report the retained path and reason. Cleanup failure leaves the reviewed final list valid but must be reported as stale recovery state.
|
|
87
99
|
|
|
88
100
|
## Report Format
|
|
89
101
|
|
|
@@ -93,4 +105,5 @@ Report in the final handoff summary:
|
|
|
93
105
|
- Reviewed feature IDs and reviewed root prose (`project_description` / `global_context`) when applicable
|
|
94
106
|
- Accepted fixes, or `none`
|
|
95
107
|
- Final validation result
|
|
108
|
+
- Draft cleanup result: `removed`, or retained path and recovery reason
|
|
96
109
|
- Note when review was not applicable because no new final planning content was written
|