prizmkit 1.1.173 → 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/prizmkit-deploy/SKILL.md +9 -0
- package/bundled/skills/prizmkit-deploy/references/capability-contract.md +2 -2
- package/bundled/skills/prizmkit-deploy/references/fast-path-selection.md +6 -0
- package/bundled/skills/prizmkit-deploy/references/playbook-remote-runtime.md +30 -2
- package/bundled/skills/prizmkit-deploy/references/playbook-repository-hosted.md +1 -1
- package/bundled/skills/prizmkit-deploy/references/policy-and-execution.md +4 -2
- 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,
|
|
@@ -20,6 +20,8 @@ Use this Skill for:
|
|
|
20
20
|
|
|
21
21
|
Do not use it for unrelated application implementation, general server administration, or resources outside the selected environment and its necessary deployment dependencies. If the user says only “ship it” without explicitly invoking this Skill, clarify commit versus deploy; explicit invocation means deploy.
|
|
22
22
|
|
|
23
|
+
Deployment verification is Release-and-target convergence, not a generic software-development lifecycle. A caller cannot add hidden planning, review, commit, or exhaustive unit/integration/contract/browser test prerequisites. Run only checks required by the selected project-native deployment/preflight controller or by target-appropriate deployment verification, unless the user separately requests broader development work. A selected immutable worktree Release does not require creating a Git commit.
|
|
24
|
+
|
|
23
25
|
## Invocation and Authority
|
|
24
26
|
|
|
25
27
|
```text
|
|
@@ -36,6 +38,8 @@ User intent controls optional confirmation and backup policy for the selected op
|
|
|
36
38
|
|
|
37
39
|
An explicit no-confirmation instruction satisfies any confirmation or effect decision already identified within the user's established authority; do not ask again. An explicit no-backup instruction creates no new data backup, snapshot, or retained application rollback copy for this operation. Preserve current live only until the desired candidate is proven, then retire exact superseded runtime after handoff. Leave unrelated pre-existing backups untouched unless the user explicitly requests their deletion. These instructions do not invent missing facts, choose whether uncommitted code is deployed, make unknown effects bounded, bypass target identity, or establish ownership the user has not demonstrated.
|
|
38
40
|
|
|
41
|
+
Explicit permission to use local SSH credentials authorizes target-scoped use of configured SSH aliases, agent identities, and key files through the installed `ssh` executable. Do not ask whether to use them again. Let SSH consume the credential; do not read, copy, print, upload, or request the private-key value. This permission does not identify a missing destination, accept an unverified or changed host key, or authorize unrelated hosts.
|
|
42
|
+
|
|
39
43
|
Do not ask for a second complete-plan confirmation for standard actions. Before returning `WAITING_USER`, exhaust bounded read-only discovery, unambiguous target resolution, configured non-interactive authentication, and every safe bounded forward action. Pause only when no safe automatic continuation remains and the next action requires:
|
|
40
44
|
|
|
41
45
|
1. a release-source choice because tracked or untracked worktree changes exist;
|
|
@@ -46,6 +50,8 @@ Do not ask for a second complete-plan confirmation for standard actions. Before
|
|
|
46
50
|
|
|
47
51
|
A missing Profile record, ordinary first deployment, selected-target connection, known bounded downtime, material work inside the standard envelope, or missing rollback mechanism does not create a confirmation. Disclose relevant effects while continuing. Privileged or global work outside the selected environment's established target boundary is an authorization/ownership decision and pauses before execution.
|
|
48
52
|
|
|
53
|
+
When SSH still cannot connect after bounded target-scoped discovery and use of authorized local credentials, diagnose the observed failure class before pausing. Report why connection failed, which non-sensitive binding was attempted, and exactly which destination, username, port, proxy/VPN, trusted host-key fingerprint, public-key registration, network rule, SSH service, or remote permission fact must change for future automatic access. Return one connection-enablement action, then retry and perform the server work yourself. Never ask the user to log into the server and run deployment commands on this Skill's behalf.
|
|
54
|
+
|
|
49
55
|
## Managed Artifacts
|
|
50
56
|
|
|
51
57
|
Prefer project-native deployment configuration. PrizmKit owns only:
|
|
@@ -81,6 +87,8 @@ Read `${SKILL_DIR}/references/fast-path-selection.md` after resolving the operat
|
|
|
81
87
|
|
|
82
88
|
Products and tools are evidence examples, not protocol identifiers. Existing project-native coordination decides whether multiple units deploy together or independently.
|
|
83
89
|
|
|
90
|
+
A cloud server, virtual machine, or directly managed host remains a direct remote-runtime target when project evidence establishes shell access. On that path, use the installed `ssh` executable as the default connection transport. A provider dashboard does not reclassify the machine as repository-hosted deployment. Do not use browser automation or a web terminal as a substitute for SSH to transfer a Release, execute deployment commands, or inspect runtime state. Browser automation is eligible only for an exact authoritative control-plane operation when no project-native command, API, CLI, or SSH path can perform that operation; it never bypasses identity or authentication boundaries.
|
|
91
|
+
|
|
84
92
|
## AutoDeploy Workflow
|
|
85
93
|
|
|
86
94
|
### 1. Resolve Unit and Environment
|
|
@@ -166,6 +174,7 @@ Report:
|
|
|
166
174
|
|
|
167
175
|
- terminal status and operation;
|
|
168
176
|
- selected environment and target reference, plus the internal Profile record result when one exists;
|
|
177
|
+
- for failed SSH access, the observed failure class, attempted non-sensitive binding, exact missing connection fact or durable server/cloud configuration change, and one retry action;
|
|
169
178
|
- desired and actual live release;
|
|
170
179
|
- concise verification observations and residual resources;
|
|
171
180
|
- rollback availability without treating it as required approval;
|
|
@@ -31,7 +31,7 @@ A maintained recipe is reusable only while its project, tool, target, artifact,
|
|
|
31
31
|
|
|
32
32
|
Select concrete controller guidance through `${SKILL_DIR}/references/fast-path-selection.md` and its matching playbook before deriving a material action. The playbook supplies observed command knowledge; this contract still owns semantic action fields, evidence, effects, Gates, and verification.
|
|
33
33
|
|
|
34
|
-
For a direct remote target, load `${SKILL_DIR}/references/playbook-remote-runtime.md`. A remote playbook cannot bypass target identity, host-key, authentication, ownership, or unknown-outcome boundaries.
|
|
34
|
+
For a direct remote target, load `${SKILL_DIR}/references/playbook-remote-runtime.md`. When that target exposes shell access, the installed `ssh` executable is the default implementation of semantic `connect`; a browser dashboard or web terminal is not an equivalent transport. Explicit permission to use local SSH credentials resolves the credential-use decision: allow SSH to use the selected target's configured alias, agent, and key files without another question, while never reading or exposing private-key material. Browser automation is considered only for an exact authoritative control-plane operation with no supported project-native command, API, CLI, or SSH path. An SSH authentication failure does not authorize a silent transport change. A remote playbook cannot bypass target identity, host-key, authentication, ownership, or unknown-outcome boundaries.
|
|
35
35
|
|
|
36
36
|
## Base Action Contract
|
|
37
37
|
|
|
@@ -56,7 +56,7 @@ Before creating a Human Checkpoint:
|
|
|
56
56
|
3. try established non-interactive authentication;
|
|
57
57
|
4. honor an explicit decision already made for the exact identified effect.
|
|
58
58
|
|
|
59
|
-
Return one human action only when identity, target, irreversible or unbounded data effect, or shared ownership still requires a person. Missing facts and unproven ownership remain information boundaries because user intent cannot make them known. When no safe action can be established, report the missing evidence or unsupported capability instead of fabricating a command.
|
|
59
|
+
Return one human action only when identity, target, irreversible or unbounded data effect, or shared ownership still requires a person. For failed SSH access, classify the observed resolver, network, host-key, authentication, service, or remote-authorization failure and request only the missing durable connection fact or configuration change; never delegate the deployment commands to the user. Missing facts and unproven ownership remain information boundaries because user intent cannot make them known. When no safe action can be established, report the missing evidence or unsupported capability instead of fabricating a command.
|
|
60
60
|
|
|
61
61
|
Evidence derivation basis such as maintained recipe or current dynamic derivation is internal provenance, not a user-visible deployment status and not a risk classification.
|
|
62
62
|
|
|
@@ -28,6 +28,12 @@ Select the smallest authoritative controller in this order:
|
|
|
28
28
|
|
|
29
29
|
The presence of several configuration files does not mean every controller should run. Resolve conflicts through current live state and one bounded read-only observation.
|
|
30
30
|
|
|
31
|
+
## Connection Transport Precedence
|
|
32
|
+
|
|
33
|
+
Controller selection and connection transport are separate decisions. A project-native controller may remain authoritative when it internally owns transport. Otherwise, when a directly managed machine exposes or is configured for shell access, use the installed `ssh` executable and the verified SSH binding as the default transport for observation, transfer, execution, and verification. When the user authorizes local SSH credentials, resolve only the selected target's alias/configuration and let SSH try its configured agent and key files without another permission question; do not enumerate unrelated hosts or reveal key material.
|
|
34
|
+
|
|
35
|
+
A cloud provider dashboard does not make a server a repository-hosted deployment target. Browser automation—for example, a browser-driving test tool—is a last-resort control-plane adapter, not a remote-shell transport. Use it only when the exact authoritative operation has no supported project-native command, API, CLI, or SSH path. Never type deployment commands into a web terminal or upload a Release through a dashboard when an SSH binding exists or can be established. If SSH reaches a user-only authentication boundary, diagnose it and return one exact durable connection-enablement action instead of silently switching to a browser console or asking the user to execute the deployment remotely.
|
|
36
|
+
|
|
31
37
|
## Conditional Playbook Loading
|
|
32
38
|
|
|
33
39
|
- project-native controller → `playbook-project-native.md`
|
|
@@ -4,9 +4,37 @@ Use this playbook when the selected environment is a directly managed remote mac
|
|
|
4
4
|
|
|
5
5
|
## Connection
|
|
6
6
|
|
|
7
|
-
Use the installed `ssh` executable as the default implementation of semantic `connect` when the target exposes shell access. Derive the destination from an explicit target, project evidence, or an observed/user-supplied SSH config alias. Reuse its user, port, proxy, agent/key, and host-verification settings.
|
|
7
|
+
Use the installed `ssh` executable as the default implementation of semantic `connect` when the target exposes shell access. This includes a cloud server, virtual machine, or directly managed host even when its provider also offers a dashboard. Derive the destination from an explicit target, project evidence, or an observed/user-supplied SSH config alias. Reuse its user, port, proxy, agent/key, and host-verification settings.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
A provider dashboard or browser-accessible terminal does not outrank SSH. Do not use browser automation to type into a web shell, upload the application, execute deployment commands, or inspect ordinary runtime state when the verified SSH binding can perform the operation. Browser automation—for example, a Playwright-driven dashboard—is eligible only for an exact provider control-plane operation that has no supported project-native command, API, CLI, or SSH path.
|
|
10
|
+
|
|
11
|
+
### Authorized Local Credential Path
|
|
12
|
+
|
|
13
|
+
When the user authorizes local SSH credential use, proceed without another key-use question:
|
|
14
|
+
|
|
15
|
+
1. Resolve only the selected destination's effective configuration with the installed SSH client, such as `ssh -G <verified-destination>`; do not enumerate unrelated aliases.
|
|
16
|
+
2. When relevant, inspect only public agent fingerprints through `ssh-add -l`. Let SSH use the configured agent and `IdentityFile` paths; never read, copy, print, or upload private-key contents.
|
|
17
|
+
3. Attempt one bounded non-interactive probe through the resolved binding, equivalent to `ssh -o BatchMode=yes -o ConnectTimeout=<bounded-seconds> <verified-destination> true`. Preserve ordinary host-key checking and bounded diagnostics.
|
|
18
|
+
4. Continue immediately through the same binding when the probe succeeds. Do not ask the user to confirm SSH again.
|
|
19
|
+
|
|
20
|
+
Do not guess host, user, port, key path, bastion, or fingerprint, and do not bypass host-key verification. Use a project-native controller instead when the target exposes no shell or defines another authoritative path.
|
|
21
|
+
|
|
22
|
+
### Connection Failure Diagnosis
|
|
23
|
+
|
|
24
|
+
Diagnose a failed probe before returning `WAITING_USER`:
|
|
25
|
+
|
|
26
|
+
| Observed failure | Durable information or configuration needed |
|
|
27
|
+
|---|---|
|
|
28
|
+
| destination absent or name resolution failed | SSH alias or hostname/IP, login user, port, and any required proxy, bastion, VPN, or private-network route |
|
|
29
|
+
| timeout or no route | reachable address/network path and the cloud security-group or firewall inbound rule for the selected SSH port and trusted source |
|
|
30
|
+
| connection refused | correct SSH port plus an enabled/listening SSH service and non-rejecting host firewall |
|
|
31
|
+
| unknown or changed host key | trusted expected host-key fingerprint, or verified key-rotation evidence before updating local trust |
|
|
32
|
+
| no usable local identity or encrypted key unavailable | target-specific SSH `IdentityFile`/agent configuration or a locally unlocked agent identity; never request the private key or passphrase in chat |
|
|
33
|
+
| public-key authentication denied | correct login user and registration of the matching local public-key fingerprint in the account's authorized-key or cloud-managed SSH-key configuration, with public-key authentication enabled |
|
|
34
|
+
| connected user lacks project access | deploy username, project-owned remote directory, and the minimum durable file/runtime/supervisor permission or bounded privilege policy |
|
|
35
|
+
| target intentionally exposes no shell | the authoritative project-native API, CLI, or controller binding instead of browser-emulated shell access |
|
|
36
|
+
|
|
37
|
+
Return exactly one connection-enablement action containing only the applicable missing facts or configuration changes and the instruction to retry. Explain the observed failure safely, but do not ask the user to log into the server and run deployment commands; after access is enabled, this Skill reconnects and performs those operations itself. Do not switch to a browser console merely because SSH authentication or reachability failed.
|
|
10
38
|
|
|
11
39
|
## Build, Transfer, and Runtime
|
|
12
40
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Repository-Hosted Deployment Playbook
|
|
2
2
|
|
|
3
|
-
Use this playbook when an observed hosting control plane owns build, release, promotion, traffic, or runtime operations and the project contains matching native configuration or binding evidence.
|
|
3
|
+
Use this playbook when an observed hosting control plane owns build, release, promotion, traffic, or runtime operations and the project contains matching native configuration or binding evidence. A cloud server or virtual machine does not match merely because its provider has a web dashboard; when the project directly owns the machine and shell access is established, use the remote-runtime playbook and SSH.
|
|
4
4
|
|
|
5
5
|
## Discovery
|
|
6
6
|
|
|
@@ -10,7 +10,7 @@ An explicit deploy invocation authorizes the selected Profile's standard deploym
|
|
|
10
10
|
|
|
11
11
|
The standard envelope covers project-owned, bounded actions needed to build/package, resolve project-declared dependencies, apply non-destructive native migrations, create a candidate, start/restart, hand off live traffic, verify, retain bounded rollback when not explicitly declined, retire exact old runtime resources, clean failed/temporary resources, and update the selected Profile record.
|
|
12
12
|
|
|
13
|
-
For a selected directly managed remote machine, connecting and running bounded project-scoped actions through the established SSH destination are part of that standard envelope. Do not ask for another confirmation merely because the next executable is `ssh`; use established non-interactive credentials first. A missing Profile record or ordinary first deployment also does not create a checkpoint when one non-conflicting target resolves from current evidence.
|
|
13
|
+
For a selected directly managed remote machine, connecting and running bounded project-scoped actions through the established SSH destination are part of that standard envelope. Do not ask for another confirmation merely because the next executable is `ssh`; use established non-interactive credentials first. Explicit permission to use local SSH credentials authorizes the installed SSH client to consume the selected target's configured alias, agent, and key files without another question, but never authorizes reading or exposing private-key values. A missing Profile record or ordinary first deployment also does not create a checkpoint when one non-conflicting target resolves from current evidence.
|
|
14
14
|
|
|
15
15
|
### User Intent and Fast Completion
|
|
16
16
|
|
|
@@ -51,7 +51,9 @@ Do not run a material producer when current project-native evidence already cove
|
|
|
51
51
|
|
|
52
52
|
For each selected SSH action, preserve the verified destination, authentication identity, proxy path, host-key evidence, and project-owned working boundary used during discovery. Execute the smallest exact remote command needed for the current difference, with bounded connection/action time and output. Reuse one proven connection binding across observation, transfer, write, and verification instead of silently changing users or endpoints between steps.
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
When local credential use is authorized, perform target-scoped discovery through the SSH client: resolve the selected destination's effective configuration, inspect available agent public-key fingerprints when relevant, and let SSH select its configured key files. Do not open private-key files to obtain their contents, enumerate unrelated host aliases or keys, or print local credential paths in the result.
|
|
55
|
+
|
|
56
|
+
Do not pass Secret values in command arguments, print private-key material, start a broad remote inventory, or bypass host-key verification. Attempt one bounded non-interactive connection with the established SSH configuration before deciding authentication cannot complete; continue immediately when it succeeds. If it fails, preserve bounded safe diagnostics and classify whether the cause is unresolved destination, name resolution, timeout/no route, connection refusal, host-key trust/conflict, unavailable local key/agent, public-key denial, SSH service policy, or connected-user authorization. Only then return one exact `WAITING_USER` connection-enablement action when user input is unavoidable. State the exact missing server fact or cloud/server configuration change needed for durable automatic access, then retry and perform the server work through SSH; never ask the user to log in and run deployment commands. If the target key or destination differs from established evidence, treat it as an identity conflict rather than a transient retry. After a disconnect during a possible write, use the same verified SSH destination to inspect actual state before considering replay.
|
|
55
57
|
|
|
56
58
|
## Current → Desired Loop
|
|
57
59
|
|