@codewizard-dt/bootstrap 2.10.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/.github/workflows/build.yml +88 -0
- package/.github/workflows/security.yml +24 -0
- package/.gitleaks.toml +15 -0
- package/README.md +472 -0
- package/bin/cli.js +47 -0
- package/lib/README.md +27 -0
- package/lib/hooks/README.md +316 -0
- package/lib/hooks/env-file-guard.js +45 -0
- package/lib/hooks/git-protected-ops-block.js +77 -0
- package/lib/hooks/lib/serena-languages.js +158 -0
- package/lib/hooks/lib/serena.js +787 -0
- package/lib/hooks/mv-absolute-path-block.js +53 -0
- package/lib/hooks/serena-bash-grep-block.js +501 -0
- package/lib/hooks/serena-edit-guard.js +74 -0
- package/lib/hooks/serena-first-glob-guard.js +94 -0
- package/lib/hooks/serena-first-guard.js +74 -0
- package/lib/hooks/serena-first-read-guard.js +167 -0
- package/lib/hooks/serena-pre-delegation.js +117 -0
- package/lib/hooks/serena-session-reset.js +45 -0
- package/lib/hooks/serena-usage-tracker.js +186 -0
- package/lib/hooks/serena-write-guard.js +58 -0
- package/lib/prompts/README.md +16 -0
- package/lib/prompts/migrate-wiki.md +111 -0
- package/lib/prompts/setup-deployment.md +322 -0
- package/lib/prompts/setup-design-system.md +162 -0
- package/lib/prompts/setup-strict-typechecks.md +139 -0
- package/lib/scripts/README.md +49 -0
- package/lib/scripts/bootstrap-serena.sh +145 -0
- package/lib/scripts/build-mcp-guide.sh +108 -0
- package/lib/scripts/install-global.sh +78 -0
- package/lib/scripts/install-mcps.sh +131 -0
- package/lib/scripts/lib.sh +154 -0
- package/lib/scripts/merge-gitignore.sh +65 -0
- package/lib/scripts/migrate-project.sh +273 -0
- package/lib/scripts/setup-deployment.sh +104 -0
- package/lib/scripts/setup-project.sh +55 -0
- package/lib/scripts/setup-runner.sh +99 -0
- package/lib/scripts/setup-strict-typechecks.sh +29 -0
- package/lib/scripts/startup.sh +42 -0
- package/lib/scripts/sync-wiki-scaffold.sh +104 -0
- package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
- package/lib/scripts/templates/gitignore +136 -0
- package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
- package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
- package/lib/scripts/templates/guides/stubs/context7.md +26 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
- package/lib/scripts/templates/guides/stubs/serena.md +219 -0
- package/lib/scripts/templates/wiki/conventions.md +100 -0
- package/lib/scripts/templates/wiki/dashboard.html +1733 -0
- package/lib/scripts/templates/wiki/hot.md +21 -0
- package/lib/scripts/templates/wiki/index.md +46 -0
- package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/log.md +14 -0
- package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
- package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
- package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
- package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
- package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
- package/lib/scripts/update-project.sh +75 -0
- package/lib/scripts/wiki-dashboard-server.js +146 -0
- package/lib/skills/README.md +146 -0
- package/lib/skills/anti-slop/SKILL.md +183 -0
- package/lib/skills/bug-close/SKILL.md +136 -0
- package/lib/skills/bug-file/SKILL.md +114 -0
- package/lib/skills/bug-triage/SKILL.md +140 -0
- package/lib/skills/company-align/SKILL.md +203 -0
- package/lib/skills/debug-logs/SKILL.md +129 -0
- package/lib/skills/decision-create/SKILL.md +220 -0
- package/lib/skills/decision-finalize/SKILL.md +181 -0
- package/lib/skills/decision-next/SKILL.md +129 -0
- package/lib/skills/decision-walkthrough/SKILL.md +169 -0
- package/lib/skills/demo/SKILL.md +183 -0
- package/lib/skills/elevator-pitch/SKILL.md +125 -0
- package/lib/skills/eval-create/SKILL.md +344 -0
- package/lib/skills/eval-gap/SKILL.md +150 -0
- package/lib/skills/eval-run/SKILL.md +214 -0
- package/lib/skills/extract-feature/SKILL.md +344 -0
- package/lib/skills/flashcard/SKILL.md +513 -0
- package/lib/skills/frontend-taste/SKILL.md +184 -0
- package/lib/skills/gap-assess/SKILL.md +97 -0
- package/lib/skills/git-commit/SKILL.md +164 -0
- package/lib/skills/lint/SKILL.md +99 -0
- package/lib/skills/marp-slideshow/SKILL.md +212 -0
- package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
- package/lib/skills/now/SKILL.md +36 -0
- package/lib/skills/port-feature/SKILL.md +315 -0
- package/lib/skills/power-mode/SKILL.md +184 -0
- package/lib/skills/primer/SKILL.md +84 -0
- package/lib/skills/project-readme/SKILL.md +166 -0
- package/lib/skills/req-compile/SKILL.md +131 -0
- package/lib/skills/req-create/SKILL.md +124 -0
- package/lib/skills/req-extract-decisions/SKILL.md +241 -0
- package/lib/skills/req-finalize/SKILL.md +251 -0
- package/lib/skills/req-retire/SKILL.md +185 -0
- package/lib/skills/req-update/SKILL.md +265 -0
- package/lib/skills/research/SKILL.md +250 -0
- package/lib/skills/research-company/SKILL.md +345 -0
- package/lib/skills/roadmap-add/SKILL.md +238 -0
- package/lib/skills/roadmap-create/SKILL.md +223 -0
- package/lib/skills/roadmap-next/SKILL.md +132 -0
- package/lib/skills/security-audit/SKILL.md +246 -0
- package/lib/skills/serena-config/SKILL.md +92 -0
- package/lib/skills/simplify/SKILL.md +227 -0
- package/lib/skills/tackle/SKILL.md +156 -0
- package/lib/skills/task-add/SKILL.md +208 -0
- package/lib/skills/task-audit/SKILL.md +294 -0
- package/lib/skills/task-trash/SKILL.md +115 -0
- package/lib/skills/task-update/SKILL.md +136 -0
- package/lib/skills/uat-auto/SKILL.md +69 -0
- package/lib/skills/uat-auto-plus/SKILL.md +115 -0
- package/lib/skills/uat-generate/SKILL.md +289 -0
- package/lib/skills/uat-skip/SKILL.md +169 -0
- package/lib/skills/uat-walk/SKILL.md +164 -0
- package/lib/skills/uat-walk/UAT-CORE.md +140 -0
- package/lib/skills/update-docs/SKILL.md +75 -0
- package/lib/skills/wiki-archive/SKILL.md +96 -0
- package/lib/skills/wiki-ingest/SKILL.md +139 -0
- package/lib/skills/wiki-lint/SKILL.md +131 -0
- package/lib/skills/wiki-query/SKILL.md +71 -0
- package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
- package/lib/skills/wiki-tidy/SKILL.md +107 -0
- package/package.json +32 -0
- package/raw/.gitkeep +0 -0
- package/raw/design-principles.md +65 -0
- package/raw/guides/command-anti-patterns.md +79 -0
- package/raw/guides/deployment-strategy.md +448 -0
- package/raw/guides/evals-framework.md +452 -0
- package/raw/guides/mcp-tools.md +335 -0
- package/raw/guides/task-spec.md +79 -0
- package/raw/guides/type-checking-templates/README.md +112 -0
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
- package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
- package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
- package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
- package/raw/harness-notes.md +20 -0
- package/raw/house-style/components/Badge.tsx +16 -0
- package/raw/house-style/components/Button.tsx +32 -0
- package/raw/house-style/components/Card.tsx +26 -0
- package/raw/house-style/components/Chip.tsx +57 -0
- package/raw/house-style/components/IconButton.tsx +67 -0
- package/raw/house-style/components/Modal.tsx +18 -0
- package/raw/house-style/components/Stepper.tsx +141 -0
- package/raw/house-style/components/icons.tsx +128 -0
- package/raw/house-style/preview/src/index.css +46 -0
- package/raw/house-style/tokens/tailwind.preset.ts +49 -0
- package/raw/house-style/tokens/tokens.json +62 -0
- package/raw/llm-wiki-2.md +162 -0
- package/raw/llm-wiki.md +75 -0
- package/raw/research/dark-mode-theme/index.md +85 -0
- package/raw/research/dark-mode-theme/sources.md +49 -0
- package/raw/research/serena-mcp-disconnect/index.md +81 -0
- package/raw/research/serena-mcp-disconnect/sources.md +87 -0
- package/raw/research/wiki-tooling-improvements/index.md +126 -0
- package/raw/research/wiki-tooling-improvements/sources.md +73 -0
- package/raw/software-factory-case-study.pdf +0 -0
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: decision-walkthrough
|
|
3
|
+
description: Walk through a decision file decision-by-decision, presenting each architecture choice and confirming it with the user via Q&A
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: <path/to/decision.md, NNNN-slug, or NNNN>
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
# Walkthrough Decision
|
|
14
|
+
|
|
15
|
+
Systematically walk through every decision block in a decision file. For each decision, present a compact summary of drivers, options, the recommended choice, and trade-offs, then ask the user via `AskUserQuestion` to **confirm**, **change**, **defer**, or **skip**. Sibling decisions are treated independently; the file's other blocks are never touched while one block is being discussed.
|
|
16
|
+
|
|
17
|
+
This skill is a **review pass**, not a finalizer. It does **not** flip status to `accepted` — that responsibility belongs to `/decision-finalize <file>#<DM>`, which runs the full E-C-A-D-R audit and supersession check. Use this command when you want a low-friction walkthrough to ratify (or revise) the architecture choices in a draft decision file before sending each decision through `/decision-finalize`.
|
|
18
|
+
|
|
19
|
+
**Read `wiki/work/decisions/lifecycle.md` first.** It defines the Decision Group model and the per-decision rules this command must respect (especially: siblings are inviolate; per-decision metadata is mandatory; tables not bullets; mermaid for flows).
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
**Target Decision**: $ARGUMENTS
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Pipeline Context
|
|
28
|
+
|
|
29
|
+
`/decision-create` → **`/decision-walkthrough`** → `/decision-finalize <file>#<DM>` (per decision) → `/task-add` → `/tackle`
|
|
30
|
+
|
|
31
|
+
The walkthrough is optional — `/decision-finalize` alone is sufficient when only one decision needs ratifying. Use `/decision-walkthrough` when a decision file has 2+ proposed decisions and you want a single guided pass to align on every choice before finalizing each.
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Instructions
|
|
36
|
+
|
|
37
|
+
### Step 1: Locate the decision file
|
|
38
|
+
|
|
39
|
+
Parse `$ARGUMENTS` to identify the file:
|
|
40
|
+
|
|
41
|
+
| Input form | Resolution |
|
|
42
|
+
|------------|------------|
|
|
43
|
+
| `<path>` (e.g. `wiki/work/decisions/DEC-0007-session.md`) | Use as-is |
|
|
44
|
+
| `<NNNN-slug>` (e.g. `0007-session`) | Search `wiki/work/decisions/` for `NNNN-slug.md` |
|
|
45
|
+
| `<NNNN>` (e.g. `7` or `0007`) | Pad to 4 digits; `mcp__serena__find_file` with mask `NNNN-*.md` |
|
|
46
|
+
| Empty / missing | List every decision file in `wiki/work/decisions/` with at least one `proposed` decision; ask the user via `AskUserQuestion` to pick |
|
|
47
|
+
|
|
48
|
+
If the file cannot be located, **stop** and report — do not invent or create.
|
|
49
|
+
|
|
50
|
+
### Step 2: Read and enumerate decisions
|
|
51
|
+
|
|
52
|
+
1. **Read** the decision file with `Read`.
|
|
53
|
+
2. **Enumerate every `## D*` H2 block** in file order. For each, capture:
|
|
54
|
+
- Decision ID (`D1`, `D2`, …)
|
|
55
|
+
- Sub-title
|
|
56
|
+
- `Status` (from the metadata bullets)
|
|
57
|
+
- `Tags`
|
|
58
|
+
- Whether `### Decision Outcome` already names a bolded chosen option
|
|
59
|
+
3. **Build the walkthrough roster** as a single table presented to the user:
|
|
60
|
+
|
|
61
|
+
| # | Decision | Title | Status | Chosen Option | Tags |
|
|
62
|
+
|---|----------|-------|--------|---------------|------|
|
|
63
|
+
| 1 | D1 | Storage backend | accepted | **Redis** | session, cache |
|
|
64
|
+
| 2 | D2 | Session lifetime | proposed | (none yet) | session, lifetime |
|
|
65
|
+
| 3 | D3 | Invalidation trigger | proposed | **Webhook** | session, invalidation |
|
|
66
|
+
|
|
67
|
+
4. **Classify per status:**
|
|
68
|
+
|
|
69
|
+
| Status | Walkthrough behavior |
|
|
70
|
+
|--------|---------------------|
|
|
71
|
+
| `proposed` | **In scope** — runs the full Q&A confirm/change loop in Step 3 |
|
|
72
|
+
| `accepted` | **Informational only** — print a one-line summary; skip Q&A (decision is immutable) |
|
|
73
|
+
| `deprecated` | **Informational only** — print summary; skip Q&A |
|
|
74
|
+
| `superseded by DEC-X#DY` | **Informational only** — print summary with the supersession target; skip Q&A |
|
|
75
|
+
|
|
76
|
+
If **no** decisions are `proposed`, print the roster, note that nothing requires confirmation, and stop.
|
|
77
|
+
|
|
78
|
+
### Step 3: Walk each proposed decision (one at a time)
|
|
79
|
+
|
|
80
|
+
For each `proposed` decision in roster order:
|
|
81
|
+
|
|
82
|
+
1. **Present the decision summary** as tables (never bullets):
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
─── DEC-NNNN#DM — <title> ───────────────────────────────────────
|
|
86
|
+
Status: proposed Tags: <list> Date: <YYYY-MM-DD or blank>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Followed by these tables, copied verbatim from the decision block (no rewriting):
|
|
90
|
+
|
|
91
|
+
- **Decision Drivers** (full table from `### Decision Drivers`)
|
|
92
|
+
- **Considered Options** (one-line summaries from `### Considered Options`)
|
|
93
|
+
- **Option Comparison** matrix from `### Option Comparison`
|
|
94
|
+
- **Currently chosen option** (the bolded option in `### Decision Outcome`, or `(none yet)` if absent)
|
|
95
|
+
- **Top 2 trade-off rows** for the chosen option from `### Trade-off Detail per Option` (Pros + Cons)
|
|
96
|
+
|
|
97
|
+
Cap the summary at ~25 lines. If a section is missing or all-placeholder, mark it `⚠️ gap — surface at finalize time`. **Do not edit gaps here** — that is `/decision-finalize`'s job.
|
|
98
|
+
|
|
99
|
+
2. **Ask the user via `AskUserQuestion`** with these four options:
|
|
100
|
+
|
|
101
|
+
| Verdict | Meaning | Effect |
|
|
102
|
+
|---------|---------|--------|
|
|
103
|
+
| **Confirm** | The currently chosen option is correct; proceed | Record confirmation; no edit unless the chosen option is unbolded (then bold it) |
|
|
104
|
+
| **Change** | A different option is the right choice | Ask follow-up to pick the new option, then update `### Decision Outcome` to bold the new option and rewrite the one-sentence justification |
|
|
105
|
+
| **Defer** | Not ready to confirm; keep `proposed`, revisit later | No edit; skip to next decision |
|
|
106
|
+
| **Skip** | Walk past without recording (e.g., the wrong reviewer) | No edit; no record |
|
|
107
|
+
|
|
108
|
+
If the decision has **no** chosen option yet, replace `Confirm` with `Choose` (same Change-flow follow-up).
|
|
109
|
+
|
|
110
|
+
3. **Apply edits only when the verdict is Confirm-without-bold or Change.** Use `Edit` (never `sed`/`echo`). Constrain `old_string` to text unique within the target block to avoid touching siblings.
|
|
111
|
+
|
|
112
|
+
| Trigger | Edit |
|
|
113
|
+
|---------|------|
|
|
114
|
+
| Confirm, but `### Decision Outcome` lacks a bolded option | Bold the chosen option; add a one-sentence justification anchored to the highest-priority driver |
|
|
115
|
+
| Change | Unbold the previous option; bold the new one; rewrite the justification; if user volunteers replacement context for `### Consequences` or `### Validation`, capture only what they explicitly state — never fabricate |
|
|
116
|
+
| Any verdict | **Never** flip `Status` to `accepted` (that is `/decision-finalize`'s gate); **never** edit sibling decision blocks; **never** edit the index or relationship graph |
|
|
117
|
+
|
|
118
|
+
4. **Record the per-decision verdict** in working memory for the Step 5 report.
|
|
119
|
+
|
|
120
|
+
### Step 4: Optional — light metadata fixes (only on explicit user request)
|
|
121
|
+
|
|
122
|
+
After Step 3 completes for every proposed decision, ask once via `AskUserQuestion` whether the user wants to fix any obviously-empty per-decision metadata (`Date`, `Deciders`, `Tags`) on decisions that were confirmed or changed.
|
|
123
|
+
|
|
124
|
+
| Field | Allowed fix |
|
|
125
|
+
|-------|-------------|
|
|
126
|
+
| `Date` | Today's date (`YYYY-MM-DD`) — only if the existing value is blank or the literal placeholder |
|
|
127
|
+
| `Deciders` | Names/roles supplied by the user — only if blank |
|
|
128
|
+
| `Tags` | 1–3 short tags supplied by the user — only if blank |
|
|
129
|
+
|
|
130
|
+
Anything beyond these three fields, or any change requiring research (drivers, consequences, validation thresholds), is **out of scope** — defer to `/decision-finalize` and report it in Step 5.
|
|
131
|
+
|
|
132
|
+
### Step 5: Report and recommend next steps
|
|
133
|
+
|
|
134
|
+
Print a single tabular completion report:
|
|
135
|
+
|
|
136
|
+
| Decision | Title | Pre-walkthrough status | Verdict | Edits applied | Next step |
|
|
137
|
+
|----------|-------|------------------------|---------|---------------|-----------|
|
|
138
|
+
| D1 | Storage backend | accepted | (informational) | none | n/a — already accepted |
|
|
139
|
+
| D2 | Session lifetime | proposed | Confirmed | bolded chosen option | `/decision-finalize 0007-session#D2` |
|
|
140
|
+
| D3 | Invalidation trigger | proposed | Changed (Webhook → Polling) | rewrote outcome | `/decision-finalize 0007-session#D3` |
|
|
141
|
+
|
|
142
|
+
Append:
|
|
143
|
+
|
|
144
|
+
- **Confirmed proposed decisions** — list `/decision-finalize <file>#<DM>` commands the user can run next (one per confirmed decision).
|
|
145
|
+
- **Deferred decisions** — list IDs the user chose to revisit; suggest re-running `/decision-walkthrough` later.
|
|
146
|
+
- **Gaps surfaced but not fixed** (placeholders, missing mermaid, asymmetric tables, etc.) — flag explicitly so the user knows `/decision-finalize` will pick them up.
|
|
147
|
+
- **Sibling status confirmation** — restate which decisions in the file were left byte-for-byte unchanged.
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Output Formatting Rules (mandatory)
|
|
152
|
+
|
|
153
|
+
1. **Tables not bullets** for the roster, the per-decision summary, and the completion report.
|
|
154
|
+
2. **One decision at a time** — present, ask, edit, then move on. Never bundle Q&A across multiple decisions in one `AskUserQuestion`.
|
|
155
|
+
3. **Surgical edits only** — `Edit` calls are scoped to the target decision block. Anchor `old_string` with text from that block (e.g., the `## DM. <title>` line plus a few characters) to guarantee no sibling drift.
|
|
156
|
+
4. **Present tense, full sentences** when rewriting a Decision Outcome justification.
|
|
157
|
+
5. **Never invent content** — if the user picks a new option that lacks a comparison row, do **not** synthesize one; flag it and recommend `/decision-finalize` (which will demand the research).
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## CRITICAL Rules
|
|
162
|
+
|
|
163
|
+
1. **No status flips** — this command never writes `Status: accepted`, `Status: deprecated`, or `Status: superseded by …`. Those transitions belong to `/decision-finalize` (and to the supersession path `/decision-finalize` enforces).
|
|
164
|
+
2. **Per-decision scope** — only the currently-discussed block changes. All other `D*` blocks must be byte-for-byte unchanged at end-of-run; verify before reporting.
|
|
165
|
+
3. **No supersession work** — supersession detection and the two-block cross-reference rule are `/decision-finalize`'s job. Do not search other decision files; do not edit the index or relationship graph.
|
|
166
|
+
4. **Refuse on missing-`Tags` write requests** — if the user asks to confirm a decision whose `Tags` line is empty and they decline to fill it in Step 4, leave the block as-is and tell them `/decision-finalize` will block on it.
|
|
167
|
+
5. **Never use `sed`/`awk`/`echo >>`/`cat <<EOF`** — always `Edit`.
|
|
168
|
+
6. **Maximum 3 sub-processes at a time** if delegating reads.
|
|
169
|
+
7. **Always terminate processes when done.**
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: demo
|
|
3
|
+
description: Audit all project functionality at a high level and produce a 2-3 minute demo run book plus a Marp slideshow
|
|
4
|
+
category: executing
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: "[path to project directory (defaults to cwd)] [custom instructions]"
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
|
+
|
|
12
|
+
# Demo
|
|
13
|
+
|
|
14
|
+
Audit the project's features, produce a **2-3 minute demo run book** at `.docs/demo/runbook.md`, then generate a **Marp slideshow** from it at `.docs/demo/runbook.slides.md`.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
**Arguments**: `$ARGUMENTS`
|
|
19
|
+
|
|
20
|
+
- If the first token is an existing directory path, treat it as the project root; otherwise use the current working directory.
|
|
21
|
+
- Everything else is custom instruction — audience, focus area, tone, anything you want to adjust.
|
|
22
|
+
- If `$ARGUMENTS` is empty: root = cwd, no custom instructions.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Phase 1 — Discovery
|
|
27
|
+
|
|
28
|
+
Use Serena MCP to explore the project. Never use `bash` commands for file exploration.
|
|
29
|
+
|
|
30
|
+
Start by reading Serena memories and the project's README, manifest, and any planning docs in `.docs/`. Then browse the source tree and use `mcp__serena__get_symbols_overview` on key files to discover what the project actually does — routes, commands, exported functions, UI entry points.
|
|
31
|
+
|
|
32
|
+
Compile a **feature inventory** — a flat list of distinct, user-visible capabilities. For each feature note what it does and how to trigger it (a click path, a command, or a code example). Aim for around a dozen features; collapse trivial variations into a single entry.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Phase 2 — Requirements Inventory
|
|
37
|
+
|
|
38
|
+
Before designing the narrative, collect every stated requirement so the demo can be checked against them.
|
|
39
|
+
|
|
40
|
+
**Check for requirements documents in this order:**
|
|
41
|
+
|
|
42
|
+
1. `wiki/work/requirements/` — read every non-retired PRD file (skip `archive/`). Extract:
|
|
43
|
+
- User stories / personas
|
|
44
|
+
- Functional requirements
|
|
45
|
+
- Success metrics / acceptance criteria
|
|
46
|
+
- Non-goals (so you don't inadvertently demo them)
|
|
47
|
+
|
|
48
|
+
2. `wiki/work/decisions/` — scan accepted ADR decisions for capabilities they mandate or prohibit.
|
|
49
|
+
|
|
50
|
+
3. Any other requirements files in `.docs/` (e.g. `requirements.md`, `spec.md`, `brief.md`).
|
|
51
|
+
|
|
52
|
+
Produce a **requirements checklist** — a flat list of discrete, testable requirements drawn from those sources. Each entry should be one line, e.g. `REQ-01: User can sign up with email and password`. If no requirements documents exist, note that explicitly and continue.
|
|
53
|
+
|
|
54
|
+
Cross-reference the requirements checklist against the feature inventory from Phase 1:
|
|
55
|
+
|
|
56
|
+
- **Covered** — a feature in the inventory maps to this requirement.
|
|
57
|
+
- **Gap** — no feature maps to this requirement; flag it.
|
|
58
|
+
- **Undocumented** — a feature exists in code but has no corresponding requirement.
|
|
59
|
+
|
|
60
|
+
You do not need to invent demo steps for gaps — just flag them in Phase 6. The goal is an honest coverage report, not a padded demo.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Phase 3 — Demo Narrative
|
|
65
|
+
|
|
66
|
+
Design a narrative arc that fits roughly two to three minutes of live demo time. A good arc moves from problem to solution to the "wow" moment:
|
|
67
|
+
|
|
68
|
+
- **Hook** — one sentence on the problem this project solves
|
|
69
|
+
- **Core flow** — the primary happy path, end to end, each step showing something visible
|
|
70
|
+
- **Power feature** — one non-obvious capability that makes the project stand out
|
|
71
|
+
|
|
72
|
+
End with a single closing sentence pointing to next steps or where to learn more. Apply any custom instructions from `$ARGUMENTS` to shape the narrative.
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Phase 4 — Write the Run Book
|
|
77
|
+
|
|
78
|
+
Create `.docs/demo/` if it doesn't exist. Write `.docs/demo/runbook.md` using this template:
|
|
79
|
+
|
|
80
|
+
```markdown
|
|
81
|
+
# Demo Run Book — {Project Name}
|
|
82
|
+
|
|
83
|
+
**Audience**: {who this demo is for}
|
|
84
|
+
**Duration**: 2–3 minutes
|
|
85
|
+
**Last updated**: {YYYY-MM-DD}
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Setup (pre-demo, do not narrate)
|
|
90
|
+
|
|
91
|
+
- [ ] {prerequisite — e.g., "Start server: `npm run dev`"}
|
|
92
|
+
- [ ] {prerequisite — e.g., "Open browser to http://localhost:3000"}
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Script
|
|
97
|
+
|
|
98
|
+
### Hook *(~15 s)*
|
|
99
|
+
|
|
100
|
+
> {Spoken line. Keep it to one or two sentences.}
|
|
101
|
+
|
|
102
|
+
### Step 1 — {Feature Name} *(~20 s)*
|
|
103
|
+
|
|
104
|
+
**Action**: {Exact click path, command, or code to run}
|
|
105
|
+
|
|
106
|
+
> {Spoken talking point. One short paragraph max.}
|
|
107
|
+
|
|
108
|
+
**Expected result**: {What the audience sees}
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
*(Repeat the step pattern for each step)*
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
### Wrap *(~15 s)*
|
|
117
|
+
|
|
118
|
+
> {Spoken closing line. Point to docs, repo, or next steps.}
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## Timing Guide
|
|
123
|
+
|
|
124
|
+
| Section | Target |
|
|
125
|
+
|---------|--------|
|
|
126
|
+
| Hook | 15 s |
|
|
127
|
+
| Core flow | ~{N × 15–20} s |
|
|
128
|
+
| Power feature | 30 s |
|
|
129
|
+
| Wrap | 15 s |
|
|
130
|
+
| **Total** | **~{total} s** |
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## Contingency Notes
|
|
135
|
+
|
|
136
|
+
- **If {thing} breaks**: {fallback}
|
|
137
|
+
- **If asked about {topic}**: {one-line deflection}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Fill every placeholder with real project content. The run book must be self-contained — anyone on the team should be able to deliver the demo cold.
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## Phase 5 — Generate the Marp Slideshow
|
|
145
|
+
|
|
146
|
+
Invoke the `marp-slideshow` skill on the run book you just wrote:
|
|
147
|
+
|
|
148
|
+
> **Delegate to `/marp-slideshow .docs/demo/runbook.md .docs/demo/`**
|
|
149
|
+
|
|
150
|
+
The deck must use a **GitHub dark style** — set the front-matter to a dark background (`#0d1117`) with light text (`#c9d1d9`) and accent color (`#58a6ff`). Write every slide as if you are speaking directly to a stakeholder: tell the story, don't transcribe the run book. One clear idea per slide; no bullet dumps. Speaker notes contain the verbatim spoken line from the run book.
|
|
151
|
+
|
|
152
|
+
If the `marp-slideshow` skill is not available, write the deck directly: use `marp: true`, `paginate: true`, `size: 16:9`; apply the GitHub dark style via a `style:` block; use `_class: lead` on the title slide; one slide per demo step.
|
|
153
|
+
|
|
154
|
+
**Architecture diagrams**: If the project has a meaningful architecture worth showing (layered systems, data flows, service dependencies), follow this two-track approach — one format per destination:
|
|
155
|
+
|
|
156
|
+
- **Run book (Markdown)** — embed a fenced `mermaid` block directly in `.docs/demo/runbook.md` at the appropriate section. Keep each diagram small — no more than six or seven nodes. One layer per diagram.
|
|
157
|
+
- **Slides (SVG image)** — never embed a raw Mermaid code block in the slides. Instead:
|
|
158
|
+
1. Write the raw Mermaid source (no markdown wrapper) to `.docs/demo/<name>.mmd` (e.g. `architecture.mmd`, `data-flow.mmd`).
|
|
159
|
+
2. Render it to SVG via Bash: `npx @mermaid-js/mermaid-cli mmdc -i .docs/demo/<name>.mmd -o .docs/demo/<name>.svg`
|
|
160
|
+
3. Reference the rendered SVG in the slide: ``
|
|
161
|
+
|
|
162
|
+
One diagram per slide. Name `.mmd` files after their content (e.g. `system-overview.mmd`, `data-flow.mmd`).
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## Phase 6 — Confirm
|
|
167
|
+
|
|
168
|
+
Print a short summary to the user:
|
|
169
|
+
|
|
170
|
+
- **Run book** — path, word count, and step count
|
|
171
|
+
- **Slideshow** — path, slide count, and render command (`npx @marp-team/marp-cli@latest .docs/demo/runbook.slides.md`)
|
|
172
|
+
- **Requirements coverage** — table of all requirements, each marked Covered / Gap / Undocumented
|
|
173
|
+
- **Gaps** — requirements with no demo step, and features that exist but couldn't be cleanly demo'd
|
|
174
|
+
|
|
175
|
+
If any requirements are Gaps, call them out explicitly so the user knows the demo does not cover them.
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Rules
|
|
180
|
+
|
|
181
|
+
- Use **Serena** for all code exploration — never `bash` on source files.
|
|
182
|
+
- Never modify source code — read only.
|
|
183
|
+
- Do not invent features not evidenced in the codebase; mark unclear features `[UNVERIFIED]`.
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: elevator-pitch
|
|
3
|
+
description: Generate a short, punchy elevator pitch for a project
|
|
4
|
+
category: executing
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: "[path to project directory (defaults to cwd)] [custom instructions to alter the output]"
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
Generate a **short elevator pitch** for this project — the kind you'd give to a smart stranger at a conference who asks "what are you building?" It should make the project sound genuinely exciting, brag shamelessly about the best features with the specifics to back it up, and land in under a minute of reading.
|
|
11
|
+
|
|
12
|
+
## Arguments: $ARGUMENTS
|
|
13
|
+
|
|
14
|
+
`$ARGUMENTS` may contain two kinds of input, in either order, and either may be absent:
|
|
15
|
+
|
|
16
|
+
1. **A target path** — an existing directory (absolute or relative). If present, treat it as the project root. If absent, use the current working directory.
|
|
17
|
+
2. **Custom instructions** — free-form guidance. Examples:
|
|
18
|
+
- "target a non-technical audience"
|
|
19
|
+
- "emphasize the AI angle"
|
|
20
|
+
- "write it as a tweet thread"
|
|
21
|
+
- "focus on the developer experience, not the end user"
|
|
22
|
+
|
|
23
|
+
If the first whitespace-delimited token resolves to an existing directory, treat that token as the target path and the rest as custom instructions. Otherwise treat the entire string as custom instructions and default the target to cwd.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Instructions
|
|
28
|
+
|
|
29
|
+
### 1. Discover what makes this project worth talking about
|
|
30
|
+
|
|
31
|
+
Use Serena MCP tools to explore the target project. You are looking for the story, not the spec. Find:
|
|
32
|
+
|
|
33
|
+
- **The core problem** — what pain does this solve? Be concrete.
|
|
34
|
+
- **The insight** — what's the key idea that makes this approach work? (A clever abstraction, an unusual combination of tools, a workflow nobody had automated before, etc.)
|
|
35
|
+
- **The audience** — who benefits and how does their life improve?
|
|
36
|
+
- **The best features** — identify the 2-3 features that are most impressive, most useful, or most surprising. Look for things with real numbers (command counts, time saved, steps eliminated), elegant abstractions, or capabilities that competitors don't have. These are the things you'd demo first to a skeptic.
|
|
37
|
+
- **The best part** — something that makes a developer or user think "oh that's clever."
|
|
38
|
+
|
|
39
|
+
Check: `package.json` (name, description), existing `README.md`, the top-level directory structure, and any `.docs/` or `CLAUDE.md` files for stated goals.
|
|
40
|
+
|
|
41
|
+
### 2. Write the pitch
|
|
42
|
+
|
|
43
|
+
Produce a markdown snippet with this structure — tight, concrete, no filler:
|
|
44
|
+
|
|
45
|
+
```markdown
|
|
46
|
+
## {Project Name}
|
|
47
|
+
|
|
48
|
+
{One punchy sentence that names the problem and the solution. No jargon. No "leveraging". No "seamlessly".}
|
|
49
|
+
|
|
50
|
+
### Why it's interesting
|
|
51
|
+
|
|
52
|
+
{2-3 sentences on the insight or approach. What makes this different from the obvious solution? What would a smart developer find elegant or surprising about it?}
|
|
53
|
+
|
|
54
|
+
### Who it's for
|
|
55
|
+
|
|
56
|
+
{One sentence naming the target user and the specific pain they stop feeling.}
|
|
57
|
+
|
|
58
|
+
### The best features
|
|
59
|
+
|
|
60
|
+
{2-3 bullets, each one bragging specifically about a standout feature. Lead with the most impressive one. Be concrete: name the feature, say what it does, include a number or comparison if one exists. This is where you sell it — but sell with facts, not adjectives.}
|
|
61
|
+
|
|
62
|
+
### The best part
|
|
63
|
+
|
|
64
|
+
{One sentence on the single most surprising or clever thing about it.}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### 3. Quality bar
|
|
68
|
+
|
|
69
|
+
- **Brag with specifics.** The "best features" section should be the loudest part of the pitch, but every claim must be backed by something real in the codebase — a number, a named command, a concrete capability. "47 slash commands covering the full dev lifecycle" is bragging. "A lot of useful commands" is not.
|
|
70
|
+
- **Concrete over abstract.** "Cuts deploy setup from 4 hours to one command" beats "streamlines deployment workflows."
|
|
71
|
+
- **Honest.** Only claim what the codebase actually does. Do not invent capabilities.
|
|
72
|
+
- **Voice.** Write like an engineer who built it and is genuinely proud — not like a press release or a landing page hero section.
|
|
73
|
+
- **Length.** The full output should fit comfortably in a Slack message. Under 275 words total.
|
|
74
|
+
|
|
75
|
+
### 4. Anti-slop pass
|
|
76
|
+
|
|
77
|
+
After writing the draft pitch, rewrite it applying every constraint below. This block must be applied last — after all other instructions — which is why it appears here rather than at the top.
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
No emojis. Avoid using em dashes; use commas or periods instead. Do not use any
|
|
81
|
+
of the following words or any derivatives: unlock, leverage, harness, insights,
|
|
82
|
+
democratize, explore, discover, dive in, elevate, enhance, witness, revolutionize,
|
|
83
|
+
transform, embrace, unleash, dive, indulge, actionable, reveal, unmatched, delve,
|
|
84
|
+
era, collaboration, cutting-edge, matters, impact, fusion, advancing, navigate,
|
|
85
|
+
drive, problem solver, changemaker, game changer, ensure, transformational,
|
|
86
|
+
powerful, derailed, delighted, cheat code.
|
|
87
|
+
|
|
88
|
+
If there are titles or headers, write them as direct one-liners under 10 words
|
|
89
|
+
based on the actual insight, not the topic category. Titles can be informal but
|
|
90
|
+
they need to say something specific.
|
|
91
|
+
|
|
92
|
+
Avoid contrastive negation, antithesis, and rhetorical contrast. No "X, not Y"
|
|
93
|
+
constructions. Write in a natural, conversational tone.
|
|
94
|
+
|
|
95
|
+
Avoid sentence fragments, anaphora, and asyndeton. Do not use short standalone
|
|
96
|
+
phrases or stacked clauses without conjunctions. Write in complete, naturally
|
|
97
|
+
flowing sentences.
|
|
98
|
+
|
|
99
|
+
Avoid repeated sentence openings across multiple sentences and vary sentence
|
|
100
|
+
structure so the same word or phrase does not begin consecutive sentences.
|
|
101
|
+
|
|
102
|
+
Do not structure paragraphs around rhythmic rhetorical patterns that sound like
|
|
103
|
+
speeches or persuasion frameworks. Prioritize clarity over dramatic phrasing.
|
|
104
|
+
|
|
105
|
+
Avoid colon-based dual clause titles or headings that try to simulate depth.
|
|
106
|
+
Write titles that describe the idea directly.
|
|
107
|
+
|
|
108
|
+
Remove buzzwords, hype language, and filler adjectives. Replace vague
|
|
109
|
+
marketing-style phrasing with clear descriptions of what actually happens.
|
|
110
|
+
|
|
111
|
+
Avoid vague claims and include concrete examples, numbers, tools, constraints,
|
|
112
|
+
or specific situations whenever possible so the writing contains real information.
|
|
113
|
+
|
|
114
|
+
Prefer straightforward explanation over rhetorical emphasis. Write sentences
|
|
115
|
+
that sound like a thoughtful person explaining an idea, not a motivational post
|
|
116
|
+
or keynote speech.
|
|
117
|
+
|
|
118
|
+
When editing text, simplify sentences that sound formulaic or generic and replace
|
|
119
|
+
abstract language with precise wording that reflects a real observation or
|
|
120
|
+
experience.
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### 5. Output
|
|
124
|
+
|
|
125
|
+
Write the final rewritten pitch to `ELEVATOR-PITCH.md` in the target project's root directory, overwriting any existing file. Then print the content to the conversation so the user can review it.
|