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.
- package/README.md +61 -56
- package/bin/cli.js +270 -259
- package/package.json +32 -28
- package/template/.claude/agents/debugger.md +47 -47
- package/template/.claude/agents/e2e-runner.md +66 -66
- package/template/.claude/agents/implementer.md +79 -75
- package/template/.claude/agents/planner.md +93 -71
- package/template/.claude/agents/researcher.md +103 -103
- package/template/.claude/agents/synthesizer.md +78 -72
- package/template/.claude/agents/test-author.md +70 -70
- package/template/.claude/commands/change-request.md +53 -0
- package/template/.claude/commands/log-decision.md +33 -33
- package/template/.claude/commands/log-issue.md +28 -28
- package/template/.claude/commands/overview.md +114 -99
- package/template/.claude/commands/phase.md +230 -202
- package/template/.claude/commands/propose.md +71 -0
- package/template/.claude/commands/qa-audit.md +53 -0
- package/template/.claude/commands/quick.md +30 -30
- package/template/.claude/commands/replan.md +68 -63
- package/template/.claude/commands/security-audit.md +56 -0
- package/template/.claude/commands/store-wisdom.md +195 -195
- package/template/.claude/commands/synthesize.md +26 -26
- package/template/.claude/commands/ui-audit.md +54 -0
- package/template/.claude/commands/unstuck.md +40 -40
- package/template/.claude/hooks/pre-compact.js +42 -0
- package/template/.claude/hooks/session-start.js +137 -0
- package/template/.claude/hooks/subagent-stop.js +18 -0
- package/template/.claude/istartsoft-flow/METHODOLOGY.md +432 -229
- package/template/.claude/skills/caveman/SKILL.md +39 -39
- package/template/.claude/skills/code-standards/SKILL.md +61 -0
- package/template/.claude/skills/code-standards/references/architecture.md +61 -0
- package/template/.claude/skills/code-standards/references/naming.md +60 -0
- package/template/.claude/skills/grill-me/SKILL.md +31 -10
- package/template/.claude/skills/karpathy-guidelines/SKILL.md +34 -34
- package/template/.claude/skills/security/SKILL.md +70 -0
- package/template/.claude/skills/security/references/pentest-checklist.md +46 -0
- package/template/.claude/skills/security/references/secure-coding.md +50 -0
- package/template/.claude/skills/security/references/standards.md +60 -0
- package/template/.claude/skills/security/references/threat-modeling.md +36 -0
- package/template/.claude/skills/ux-design/SKILL.md +117 -99
- package/template/.claude/skills/ux-design/{wireframe-template.md → references/wireframe-template.md} +95 -95
- package/template/.claude/templates/proposal.html +126 -0
- package/template/.claude/hooks/pre-compact.sh +0 -25
- package/template/.claude/hooks/session-start.sh +0 -120
- 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
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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.
|