create-issflow 1.0.3 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +61 -56
  2. package/bin/cli.js +270 -259
  3. package/package.json +32 -28
  4. package/template/.claude/agents/debugger.md +47 -47
  5. package/template/.claude/agents/e2e-runner.md +66 -66
  6. package/template/.claude/agents/implementer.md +79 -75
  7. package/template/.claude/agents/planner.md +93 -71
  8. package/template/.claude/agents/researcher.md +103 -103
  9. package/template/.claude/agents/synthesizer.md +78 -72
  10. package/template/.claude/agents/test-author.md +70 -70
  11. package/template/.claude/commands/change-request.md +53 -0
  12. package/template/.claude/commands/log-decision.md +33 -33
  13. package/template/.claude/commands/log-issue.md +28 -28
  14. package/template/.claude/commands/overview.md +114 -99
  15. package/template/.claude/commands/phase.md +230 -202
  16. package/template/.claude/commands/propose.md +71 -0
  17. package/template/.claude/commands/qa-audit.md +53 -0
  18. package/template/.claude/commands/quick.md +30 -30
  19. package/template/.claude/commands/replan.md +68 -63
  20. package/template/.claude/commands/security-audit.md +56 -0
  21. package/template/.claude/commands/store-wisdom.md +195 -195
  22. package/template/.claude/commands/synthesize.md +26 -26
  23. package/template/.claude/commands/ui-audit.md +54 -0
  24. package/template/.claude/commands/unstuck.md +40 -40
  25. package/template/.claude/hooks/pre-compact.js +42 -0
  26. package/template/.claude/hooks/session-start.js +137 -0
  27. package/template/.claude/hooks/subagent-stop.js +18 -0
  28. package/template/.claude/istartsoft-flow/METHODOLOGY.md +432 -229
  29. package/template/.claude/skills/caveman/SKILL.md +39 -39
  30. package/template/.claude/skills/code-standards/SKILL.md +61 -0
  31. package/template/.claude/skills/code-standards/references/architecture.md +61 -0
  32. package/template/.claude/skills/code-standards/references/naming.md +60 -0
  33. package/template/.claude/skills/grill-me/SKILL.md +31 -10
  34. package/template/.claude/skills/karpathy-guidelines/SKILL.md +34 -34
  35. package/template/.claude/skills/security/SKILL.md +70 -0
  36. package/template/.claude/skills/security/references/pentest-checklist.md +46 -0
  37. package/template/.claude/skills/security/references/secure-coding.md +50 -0
  38. package/template/.claude/skills/security/references/standards.md +60 -0
  39. package/template/.claude/skills/security/references/threat-modeling.md +36 -0
  40. package/template/.claude/skills/ux-design/SKILL.md +117 -99
  41. package/template/.claude/skills/ux-design/{wireframe-template.md → references/wireframe-template.md} +95 -95
  42. package/template/.claude/templates/proposal.html +126 -0
  43. package/template/.claude/hooks/pre-compact.sh +0 -25
  44. package/template/.claude/hooks/session-start.sh +0 -120
  45. package/template/.claude/hooks/subagent-stop.sh +0 -11
@@ -1,63 +1,68 @@
1
- ---
2
- description: Revise docs/PLAN.md when it no longer matches reality — add, cut, split, merge, or reorder phases.
3
- argument-hint: [what changed about the plan]
4
- ---
5
-
6
- Caveman ULTRA mode.
7
-
8
- Recommended: run from plan mode (Shift+Tab). Optional; the command stops for
9
- your approval regardless.
10
-
11
- Use when PLAN.md no longer matches reality. Change: $ARGUMENTS
12
-
13
- ---
14
-
15
- ## Steps
16
-
17
- 1. PRE-FLIGHT. Read docs/STATE.md and docs/PLAN.md.
18
- - Phase in progress -> tell me which. Ask: revise around it, or is it the
19
- thing being changed? Do not silently rewrite a mid-execution phase.
20
- - Done phases are FROZEN. /replan never edits or reorders done phases.
21
- - Phase 0 (infra), if present, is frozen once done.
22
-
23
- 2. DESIGN RESEARCH CHECK. Scan $ARGUMENTS for signals that design research
24
- is warranted before re-planning:
25
- - The change involves architecture (a new integration pattern, auth change, etc.)
26
- - A service tier or quota change is implied
27
-
28
- If ANY of these signals are present: dispatch `researcher` in DESIGN mode
29
- with the specific new service/pattern as the DESIGN TOPICS list. Show me the
30
- key findings before proceeding to step 3.
31
-
32
- If none: proceed directly to step 3 (impl-research may still be dispatched
33
- in step 3 for non-trivial changes per the original logic).
34
-
35
- 3. IMPL RESEARCH if needed. If the change is non-trivial but design research
36
- was not needed, dispatch `researcher` in IMPL mode to ground the re-plan
37
- in facts.
38
-
39
- 4. RE-PLAN. Dispatch `planner` with the change + current PLAN.md. It must:
40
- - Keep done phases untouched.
41
- - Insert / cut / split / merge / reorder only PENDING phases.
42
- - Place new phases in correct DEPENDENCY order.
43
- - Keep every phase a vertical slice with its own acceptance spec.
44
- - Ensure the LAST pending phase still contains the deploy task block.
45
- - Renumber pending phases if needed; update STATE.md `phase:` pointer.
46
-
47
- 5. RECONCILE THE REGRESSION CORPUS (scoped to `tests/regression/`):
48
- - A CUT phase -> retire its regression tests.
49
- - A MERGE -> consolidate the merged phases' regression tests.
50
- - A REORDER -> keep the tests as-is (contracts are phase-independent).
51
- Do NOT touch phase-local `tests/phase-<n>/` here beyond renumbering dirs.
52
- After reconciling, run `scripts/regression.sh --real` to confirm the
53
- reconciled corpus still passes against live services. A failure -> surface it
54
- and stop before approval.
55
-
56
- 6. SHOW ME the revised phase list + the regression-corpus changes, and STOP for
57
- approval.
58
-
59
- 7. ARCHITECTURE SELF-CHECK: re-planning is not normally a kit-architecture
60
- change. Only run /log-decision if the workflow itself changed (rare).
61
-
62
- Report what changed: phases added / cut / split / reordered, and regression
63
- tests retired / consolidated.
1
+ ---
2
+ description: Revise docs/PLAN.md when it no longer matches reality — add, cut, split, merge, or reorder phases.
3
+ argument-hint: [what changed about the plan]
4
+ ---
5
+
6
+ Caveman ULTRA mode.
7
+
8
+ Recommended: run from plan mode (Shift+Tab). Optional; the command stops for
9
+ your approval regardless.
10
+
11
+ Use when PLAN.md no longer matches reality. Change: $ARGUMENTS
12
+
13
+ NOTE: if the change alters SCOPE after a proposal is approved (cost/timeline impact),
14
+ run `/change-request` instead — it does the impact analysis + re-estimate + change
15
+ order, then calls this command. `/replan` is for plan-shape changes with no
16
+ commercial impact (split/merge/reorder, a discovered technical re-slice).
17
+
18
+ ---
19
+
20
+ ## Steps
21
+
22
+ 1. PRE-FLIGHT. Read docs/STATE.md and docs/PLAN.md.
23
+ - Phase in progress -> tell me which. Ask: revise around it, or is it the
24
+ thing being changed? Do not silently rewrite a mid-execution phase.
25
+ - Done phases are FROZEN. /replan never edits or reorders done phases.
26
+ - Phase 0 (infra), if present, is frozen once done.
27
+
28
+ 2. DESIGN RESEARCH CHECK. Scan $ARGUMENTS for signals that design research
29
+ is warranted before re-planning:
30
+ - The change involves architecture (a new integration pattern, auth change, etc.)
31
+ - A service tier or quota change is implied
32
+
33
+ If ANY of these signals are present: dispatch `researcher` in DESIGN mode
34
+ with the specific new service/pattern as the DESIGN TOPICS list. Show me the
35
+ key findings before proceeding to step 3.
36
+
37
+ If none: proceed directly to step 3 (impl-research may still be dispatched
38
+ in step 3 for non-trivial changes per the original logic).
39
+
40
+ 3. IMPL RESEARCH if needed. If the change is non-trivial but design research
41
+ was not needed, dispatch `researcher` in IMPL mode to ground the re-plan
42
+ in facts.
43
+
44
+ 4. RE-PLAN. Dispatch `planner` with the change + current PLAN.md. It must:
45
+ - Keep done phases untouched.
46
+ - Insert / cut / split / merge / reorder only PENDING phases.
47
+ - Place new phases in correct DEPENDENCY order.
48
+ - Keep every phase a vertical slice with its own acceptance spec.
49
+ - Ensure the LAST pending phase still contains the deploy task block.
50
+ - Renumber pending phases if needed; update STATE.md `phase:` pointer.
51
+
52
+ 5. RECONCILE THE REGRESSION CORPUS (scoped to `tests/regression/`):
53
+ - A CUT phase -> retire its regression tests.
54
+ - A MERGE -> consolidate the merged phases' regression tests.
55
+ - A REORDER -> keep the tests as-is (contracts are phase-independent).
56
+ Do NOT touch phase-local `tests/phase-<n>/` here beyond renumbering dirs.
57
+ After reconciling, run `scripts/regression.sh --real` to confirm the
58
+ reconciled corpus still passes against live services. A failure -> surface it
59
+ and stop before approval.
60
+
61
+ 6. SHOW ME the revised phase list + the regression-corpus changes, and STOP for
62
+ approval.
63
+
64
+ 7. ARCHITECTURE SELF-CHECK: re-planning is not normally a kit-architecture
65
+ change. Only run /log-decision if the workflow itself changed (rare).
66
+
67
+ Report what changed: phases added / cut / split / reordered, and regression
68
+ tests retired / consolidated.
@@ -0,0 +1,56 @@
1
+ ---
2
+ description: Holistic security audit — sweep the WHOLE product against the security cookbook (OWASP Top 10 / ASVS / WSTG / secrets / SCA / SAST / supply chain), score it, and produce a prioritized findings report. On-demand or before a release. NOT the per-phase gate — rule 11 checks one phase while coding; this audits the whole attack surface.
3
+ argument-hint: [optional scope]
4
+ ---
5
+
6
+ Caveman ULTRA mode. You are the ORCHESTRATOR.
7
+
8
+ Purpose: a whole-product SECURITY audit — the security counterpart of `/ui-audit`
9
+ and `/qa-audit`. The per-phase gate (rule 11) checks secrets/SCA/SAST + secure coding
10
+ on ONE phase; this audit sweeps the ENTIRE attack surface and the product's security
11
+ posture. Run before a release, after auth/data changes, or on request — and before
12
+ the pre-deploy pentest, not instead of it.
13
+
14
+ Security = "is it SAFE?" — a different axis from QA ("does it work?") and UI
15
+ ("does it look right?"). Passing those never implies this.
16
+
17
+ ## PRE-FLIGHT
18
+ Read the rubric: `.claude/skills/security/SKILL.md` (the Secure SDLC cookbook) and
19
+ its `references/` (OWASP Top 10 / ASVS / WSTG / ISO 27001 / SLSA). The cookbook IS the
20
+ checklist — audit against it; don't invent criteria.
21
+
22
+ ## STEP 1 — INVENTORY (attack surface)
23
+ Map it from `docs/ENDPOINTS.md` + the code: entry points (routes, inputs, file
24
+ uploads, webhooks), trust boundaries, auth/session, data stores + PII, secrets,
25
+ third-party deps, and outbound calls.
26
+
27
+ ## STEP 2 — SWEEP (dispatch a worker to keep context lean)
28
+ - **OWASP Top 10** — broken access control, crypto failures, injection (SQLi/XSS/
29
+ cmd), insecure design, misconfiguration, vulnerable components, auth failures,
30
+ integrity failures, logging/monitoring gaps, SSRF.
31
+ - **AuthN / AuthZ** — every protected route enforces it; no IDOR; least privilege.
32
+ - **Secrets** — none in code/history/config/prompts (run gitleaks/trufflehog if present).
33
+ - **Dependencies (SCA)** — known CVEs (run `npm audit` / `pip-audit` / `osv-scanner`).
34
+ - **SAST** — run semgrep / CodeQL if present; review hotspots otherwise.
35
+ - **Input validation + output encoding** at every boundary; safe file handling.
36
+ - **Crypto** — strong algorithms, no hardcoded keys, secrets at rest/in transit.
37
+ - **Supply chain (SLSA)** — pinned deps, build integrity, no untrusted scripts.
38
+ - **Logging / monitoring** — security events logged; no sensitive data in logs.
39
+ - **Threat-model coverage** — were the design-stage abuse cases actually tested?
40
+
41
+ ## STEP 3 — SCORE + FINDINGS
42
+ Rate each area PASS / WARN / FAIL. Per finding:
43
+ - **severity**: CRITICAL · HIGH · MEDIUM · LOW (map to CVSS where it helps)
44
+ - **location**: endpoint / file / dependency
45
+ - **issue** + the OWASP/ASVS reference it breaks + **fix**
46
+
47
+ ## STEP 4 — REPORT
48
+ Write `docs/security-audit-<YYYY-MM-DD>.md`: attack-surface map · per-area scoreboard ·
49
+ findings sorted by severity · prioritized remediation. Log HIGH/CRITICAL to
50
+ `docs/ISSUES.md`.
51
+ **VERDICT: SHIP | FIX-FIRST** — never ship with an open HIGH or CRITICAL.
52
+
53
+ ## STEP 5 — REMEDIATE
54
+ A security fix is security-sensitive (autonomy hard-stop): in AUTO, fix and re-audit
55
+ but SURFACE the change for human sign-off before it lands. Park what's blocked +
56
+ report. A clean `/security-audit` is a precondition for the pre-deploy pentest gate.
@@ -1,195 +1,195 @@
1
- ---
2
- description: Promote resolved issues and research findings from this project to the shared istartsoft-flow-kb repo. Analyzes, proposes candidates for your review, then pushes approved entries.
3
- ---
4
-
5
- Caveman ULTRA mode. You are the ORCHESTRATOR.
6
-
7
- Purpose: share what this project learned with all future projects.
8
- Only resolved issues and completed research qualify. Open issues do NOT.
9
-
10
- ---
11
-
12
- ## PRE-FLIGHT
13
-
14
- 1. Read `.claude/kb-config.json`.
15
- - Not found -> STOP. Tell me: "KB not configured. Create `.claude/kb-config.json`
16
- with `kb_path` + `kb_remote` pointing at the shared KB repo, then retry /store-wisdom."
17
- - Found -> extract `kb_path` and `kb_remote`.
18
-
19
- 2. Expand `kb_path` (resolve `~` to home directory).
20
- Verify the path exists and is a git repo (`git -C <path> status`).
21
- - Fails -> STOP. Tell me the path is broken and to fix `kb_path` in
22
- `.claude/kb-config.json`.
23
-
24
- ---
25
-
26
- ## STEP 1 — PULL LATEST KB
27
-
28
- Run: `git -C <kb_path> pull --ff-only`
29
-
30
- - Success -> continue.
31
- - Conflict or diverged -> STOP. Tell me:
32
- "KB has a conflict. Resolve manually in <kb_path>, then retry /store-wisdom."
33
- - Offline (no network) -> WARN me, ask: "KB pull failed (offline?). Continue
34
- with local KB copy, or abort?" Wait for answer.
35
-
36
- ---
37
-
38
- ## STEP 2 — ANALYZE LOCAL PROJECT
39
-
40
- Scan this project for promotion candidates:
41
-
42
- ### From docs/ISSUES.md — resolved issues only
43
- - Read all entries marked `- [x] resolved`.
44
- - Exclude: entries with no root cause filled in, entries without a solution.
45
- - For each qualifying entry, note: title, symptom, root cause, solution,
46
- failed attempts.
47
-
48
- ### From docs/research/ — completed research files
49
- - Read docs/research/INDEX.md. For each entry:
50
- - Read the corresponding file.
51
- - A research entry qualifies if: it documents an external service behavior,
52
- API contract, SDK gotcha, architectural constraint, or cost finding that
53
- would be useful in a different project.
54
- - A research entry does NOT qualify if: it is a project-specific config
55
- finding, a one-off trace with no generalizable conclusion, or a debug
56
- trace (`debug-*.md`).
57
- - Note: research entries get a `created:` timestamp (today's date if not
58
- already present in the file). Staleness is measured from this date.
59
-
60
- ### Cross-check against KB
61
- - Read `<kb_path>/INDEX.md` (if it exists).
62
- - For each candidate: does a matching slug already exist in the KB?
63
- - YES, fresh entry: skip (already in KB, not stale).
64
- - YES, stale entry (marked [STALE] in the snapshot): flag as REWRITE candidate.
65
- - NO: flag as NEW candidate.
66
-
67
- ---
68
-
69
- ## STEP 3 — PROPOSE CANDIDATES
70
-
71
- Present candidates one at a time. For each:
72
- ```
73
-
74
- [N of M] <type: NEW | REWRITE> — <slug>
75
- Tags: <tag1, tag2, tag3>
76
- Action: <“new entry” | “replaces stale entry from YYYY-MM-DD”>
77
-
78
- ## Preview:
79
-
80
- ## [<slug>]
81
-
82
- ## created: <YYYY-MM-DD>
83
- tags: <tags>
84
- symptom/context: <…>
85
- root-cause / finding: <…>
86
- fix / recommendation: <…>
87
-
88
- [APPROVE / EDIT / SKIP]
89
-
90
- ```
91
- - APPROVE: add to approved list.
92
- - EDIT: ask me for the edit, apply it, re-show, wait for APPROVE or SKIP.
93
- - SKIP: discard this candidate.
94
-
95
- After all candidates: show me the summary:
96
- ```
97
-
98
- Approved: <N> entries
99
- Skipped: <M> entries
100
- Domains to write: <list>
101
- New domain folders to create: <list or “none”>
102
- Proceed? [yes / abort]
103
-
104
- ```
105
- Wait for "yes" before writing anything.
106
-
107
- ---
108
-
109
- ## STEP 4 — WRITE TO KB
110
-
111
- For each approved entry:
112
-
113
- 1. Determine the domain file path: `<kb_path>/<domain>/<file>.md`
114
- - If the directory does not exist: create it.
115
- - If the file does not exist: create it with a `# <domain> — <file>` header.
116
-
117
- 2. REWRITE candidates: find the existing `## [<slug>]` block in the file and
118
- replace it entirely with the new entry.
119
-
120
- 3. NEW candidates: append the entry to the end of the domain file.
121
-
122
- 4. Update `<kb_path>/INDEX.md`:
123
- - For NEW entries: append a line:
124
- `YYYY-MM-DD | <domain>/<file> | <slug> | <one-sentence summary>`
125
- - For REWRITE entries: update the existing line in-place (new date, same slug).
126
-
127
- 5. If this is the first `/store-wisdom` run (no INDEX.md existed):
128
- Also create `<kb_path>/KB_GUIDE.md` with the entry format reference:
129
-
130
- ```markdown
131
- # istartsoft-flow-kb — guide
132
-
133
- This repo accumulates resolved issues and research findings from iStartSoftFlow projects.
134
- Populated by `/store-wisdom`. Read by the iStartSoftFlow `researcher` agent at session start.
135
-
136
- ## Entry format — issues
137
- ## [slug]
138
- created: YYYY-MM-DD
139
- tags: tag1, tag2
140
- symptom: what was observed
141
- root-cause: the real underlying cause
142
- fix: exact solution
143
- failed-attempts: what did not work
144
-
145
- ## Entry format — research
146
- ## [slug]
147
- created: YYYY-MM-DD
148
- tags: tag1, tag2
149
- symptom/context: what prompted the research
150
- finding: what was discovered
151
- recommendation: what to do
152
-
153
- ## INDEX.md format
154
- YYYY-MM-DD | domain/file | slug | one-sentence summary
155
-
156
- ## Staleness
157
- Research entries older than 6 months are flagged [STALE] at session load.
158
- Stale entries are re-researched locally and rewritten via /store-wisdom.
159
- Issue entries never go stale.
160
- ```
161
-
162
- -----
163
-
164
- ## STEP 5 — COMMIT AND PUSH
165
-
166
- Run from `<kb_path>`:
167
-
168
- ```bash
169
- git add -A
170
- git commit -m "store-wisdom: <N> entries from <project-name> (<YYYY-MM-DD>)"
171
- git push
172
- ```
173
-
174
- - Push success -> tell me:
175
-
176
- ```
177
- KB updated.
178
- - entries written: <N> (<list of slugs>)
179
- - domains touched: <list>
180
- - new domains created: <list or "none">
181
- - pushed to: <kb_remote>
182
- ```
183
- - Push fails -> tell me the push failed, show the git error.
184
- The entries ARE written locally — tell me to push manually:
185
- `git -C <kb_path> push`
186
-
187
- -----
188
-
189
- ## NOTES
190
-
191
- - `/store-wisdom` never modifies docs/ISSUES.md or docs/research/ in this project.
192
- It reads them; it does not change them.
193
- - If there are no qualifying candidates, tell me so and stop. Do not push an empty commit.
194
- - The KB is append-only except for REWRITE of stale research entries.
195
- Issue entries are never deleted or overwritten — they are facts.
1
+ ---
2
+ description: Promote resolved issues and research findings from this project to the shared istartsoft-flow-kb repo. Analyzes, proposes candidates for your review, then pushes approved entries.
3
+ ---
4
+
5
+ Caveman ULTRA mode. You are the ORCHESTRATOR.
6
+
7
+ Purpose: share what this project learned with all future projects.
8
+ Only resolved issues and completed research qualify. Open issues do NOT.
9
+
10
+ ---
11
+
12
+ ## PRE-FLIGHT
13
+
14
+ 1. Read `.claude/kb-config.json`.
15
+ - Not found -> STOP. Tell me: "KB not configured. Create `.claude/kb-config.json`
16
+ with `kb_path` + `kb_remote` pointing at the shared KB repo, then retry /store-wisdom."
17
+ - Found -> extract `kb_path` and `kb_remote`.
18
+
19
+ 2. Expand `kb_path` (resolve `~` to home directory).
20
+ Verify the path exists and is a git repo (`git -C <path> status`).
21
+ - Fails -> STOP. Tell me the path is broken and to fix `kb_path` in
22
+ `.claude/kb-config.json`.
23
+
24
+ ---
25
+
26
+ ## STEP 1 — PULL LATEST KB
27
+
28
+ Run: `git -C <kb_path> pull --ff-only`
29
+
30
+ - Success -> continue.
31
+ - Conflict or diverged -> STOP. Tell me:
32
+ "KB has a conflict. Resolve manually in <kb_path>, then retry /store-wisdom."
33
+ - Offline (no network) -> WARN me, ask: "KB pull failed (offline?). Continue
34
+ with local KB copy, or abort?" Wait for answer.
35
+
36
+ ---
37
+
38
+ ## STEP 2 — ANALYZE LOCAL PROJECT
39
+
40
+ Scan this project for promotion candidates:
41
+
42
+ ### From docs/ISSUES.md — resolved issues only
43
+ - Read all entries marked `- [x] resolved`.
44
+ - Exclude: entries with no root cause filled in, entries without a solution.
45
+ - For each qualifying entry, note: title, symptom, root cause, solution,
46
+ failed attempts.
47
+
48
+ ### From docs/research/ — completed research files
49
+ - Read docs/research/INDEX.md. For each entry:
50
+ - Read the corresponding file.
51
+ - A research entry qualifies if: it documents an external service behavior,
52
+ API contract, SDK gotcha, architectural constraint, or cost finding that
53
+ would be useful in a different project.
54
+ - A research entry does NOT qualify if: it is a project-specific config
55
+ finding, a one-off trace with no generalizable conclusion, or a debug
56
+ trace (`debug-*.md`).
57
+ - Note: research entries get a `created:` timestamp (today's date if not
58
+ already present in the file). Staleness is measured from this date.
59
+
60
+ ### Cross-check against KB
61
+ - Read `<kb_path>/INDEX.md` (if it exists).
62
+ - For each candidate: does a matching slug already exist in the KB?
63
+ - YES, fresh entry: skip (already in KB, not stale).
64
+ - YES, stale entry (marked [STALE] in the snapshot): flag as REWRITE candidate.
65
+ - NO: flag as NEW candidate.
66
+
67
+ ---
68
+
69
+ ## STEP 3 — PROPOSE CANDIDATES
70
+
71
+ Present candidates one at a time. For each:
72
+ ```
73
+
74
+ [N of M] <type: NEW | REWRITE> — <slug>
75
+ Tags: <tag1, tag2, tag3>
76
+ Action: <“new entry” | “replaces stale entry from YYYY-MM-DD”>
77
+
78
+ ## Preview:
79
+
80
+ ## [<slug>]
81
+
82
+ ## created: <YYYY-MM-DD>
83
+ tags: <tags>
84
+ symptom/context: <…>
85
+ root-cause / finding: <…>
86
+ fix / recommendation: <…>
87
+
88
+ [APPROVE / EDIT / SKIP]
89
+
90
+ ```
91
+ - APPROVE: add to approved list.
92
+ - EDIT: ask me for the edit, apply it, re-show, wait for APPROVE or SKIP.
93
+ - SKIP: discard this candidate.
94
+
95
+ After all candidates: show me the summary:
96
+ ```
97
+
98
+ Approved: <N> entries
99
+ Skipped: <M> entries
100
+ Domains to write: <list>
101
+ New domain folders to create: <list or “none”>
102
+ Proceed? [yes / abort]
103
+
104
+ ```
105
+ Wait for "yes" before writing anything.
106
+
107
+ ---
108
+
109
+ ## STEP 4 — WRITE TO KB
110
+
111
+ For each approved entry:
112
+
113
+ 1. Determine the domain file path: `<kb_path>/<domain>/<file>.md`
114
+ - If the directory does not exist: create it.
115
+ - If the file does not exist: create it with a `# <domain> — <file>` header.
116
+
117
+ 2. REWRITE candidates: find the existing `## [<slug>]` block in the file and
118
+ replace it entirely with the new entry.
119
+
120
+ 3. NEW candidates: append the entry to the end of the domain file.
121
+
122
+ 4. Update `<kb_path>/INDEX.md`:
123
+ - For NEW entries: append a line:
124
+ `YYYY-MM-DD | <domain>/<file> | <slug> | <one-sentence summary>`
125
+ - For REWRITE entries: update the existing line in-place (new date, same slug).
126
+
127
+ 5. If this is the first `/store-wisdom` run (no INDEX.md existed):
128
+ Also create `<kb_path>/KB_GUIDE.md` with the entry format reference:
129
+
130
+ ```markdown
131
+ # istartsoft-flow-kb — guide
132
+
133
+ This repo accumulates resolved issues and research findings from iStartSoftFlow projects.
134
+ Populated by `/store-wisdom`. Read by the iStartSoftFlow `researcher` agent at session start.
135
+
136
+ ## Entry format — issues
137
+ ## [slug]
138
+ created: YYYY-MM-DD
139
+ tags: tag1, tag2
140
+ symptom: what was observed
141
+ root-cause: the real underlying cause
142
+ fix: exact solution
143
+ failed-attempts: what did not work
144
+
145
+ ## Entry format — research
146
+ ## [slug]
147
+ created: YYYY-MM-DD
148
+ tags: tag1, tag2
149
+ symptom/context: what prompted the research
150
+ finding: what was discovered
151
+ recommendation: what to do
152
+
153
+ ## INDEX.md format
154
+ YYYY-MM-DD | domain/file | slug | one-sentence summary
155
+
156
+ ## Staleness
157
+ Research entries older than 6 months are flagged [STALE] at session load.
158
+ Stale entries are re-researched locally and rewritten via /store-wisdom.
159
+ Issue entries never go stale.
160
+ ```
161
+
162
+ -----
163
+
164
+ ## STEP 5 — COMMIT AND PUSH
165
+
166
+ Run from `<kb_path>`:
167
+
168
+ ```bash
169
+ git add -A
170
+ git commit -m "store-wisdom: <N> entries from <project-name> (<YYYY-MM-DD>)"
171
+ git push
172
+ ```
173
+
174
+ - Push success -> tell me:
175
+
176
+ ```
177
+ KB updated.
178
+ - entries written: <N> (<list of slugs>)
179
+ - domains touched: <list>
180
+ - new domains created: <list or "none">
181
+ - pushed to: <kb_remote>
182
+ ```
183
+ - Push fails -> tell me the push failed, show the git error.
184
+ The entries ARE written locally — tell me to push manually:
185
+ `git -C <kb_path> push`
186
+
187
+ -----
188
+
189
+ ## NOTES
190
+
191
+ - `/store-wisdom` never modifies docs/ISSUES.md or docs/research/ in this project.
192
+ It reads them; it does not change them.
193
+ - If there are no qualifying candidates, tell me so and stop. Do not push an empty commit.
194
+ - The KB is append-only except for REWRITE of stale research entries.
195
+ Issue entries are never deleted or overwritten — they are facts.
@@ -1,26 +1,26 @@
1
- ---
2
- description: Compress handoff docs, dedup the issue log, prune snapshots. Run before /clear.
3
- ---
4
-
5
- Caveman ULTRA mode.
6
-
7
- Trigger: end of a phase, or any time STATE.md / ISSUES.md feel bloated.
8
-
9
- Dispatch the `synthesizer` subagent.
10
-
11
- For a normal phase: it rewrites STATE.md, dedups ISSUES.md, prunes snapshots,
12
- appends to HISTORY.md.
13
-
14
- For the FINAL phase (no further pending phases): also pass the signal
15
- "FINAL PHASE" so the synthesizer runs the extended pass — updating OVERVIEW.md
16
- and README.md to reflect the completed project state.
17
-
18
- To determine if this is the final phase: read docs/PLAN.md. If no phases remain
19
- with status "pending" after the current one, it is the final phase.
20
-
21
- When synthesizer returns "safe to /clear: yes", tell me:
22
- - before/after line counts
23
- - whether the final-pass ran
24
- - that I can now run /clear (or proceed to the endpoint summary if final phase)
25
-
26
- If it returns anything unsafe, show me what and stop.
1
+ ---
2
+ description: Compress handoff docs, dedup the issue log, prune snapshots. Run before /clear.
3
+ ---
4
+
5
+ Caveman ULTRA mode.
6
+
7
+ Trigger: end of a phase, or any time STATE.md / ISSUES.md feel bloated.
8
+
9
+ Dispatch the `synthesizer` subagent.
10
+
11
+ For a normal phase: it rewrites STATE.md, dedups ISSUES.md, prunes snapshots,
12
+ appends to HISTORY.md.
13
+
14
+ For the FINAL phase (no further pending phases): also pass the signal
15
+ "FINAL PHASE" so the synthesizer runs the extended pass — updating OVERVIEW.md
16
+ and README.md to reflect the completed project state.
17
+
18
+ To determine if this is the final phase: read docs/PLAN.md. If no phases remain
19
+ with status "pending" after the current one, it is the final phase.
20
+
21
+ When synthesizer returns "safe to /clear: yes", tell me:
22
+ - before/after line counts
23
+ - whether the final-pass ran
24
+ - that I can now run /clear (or proceed to the endpoint summary if final phase)
25
+
26
+ If it returns anything unsafe, show me what and stop.