@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.
Files changed (186) hide show
  1. package/.github/workflows/build.yml +88 -0
  2. package/.github/workflows/security.yml +24 -0
  3. package/.gitleaks.toml +15 -0
  4. package/README.md +472 -0
  5. package/bin/cli.js +47 -0
  6. package/lib/README.md +27 -0
  7. package/lib/hooks/README.md +316 -0
  8. package/lib/hooks/env-file-guard.js +45 -0
  9. package/lib/hooks/git-protected-ops-block.js +77 -0
  10. package/lib/hooks/lib/serena-languages.js +158 -0
  11. package/lib/hooks/lib/serena.js +787 -0
  12. package/lib/hooks/mv-absolute-path-block.js +53 -0
  13. package/lib/hooks/serena-bash-grep-block.js +501 -0
  14. package/lib/hooks/serena-edit-guard.js +74 -0
  15. package/lib/hooks/serena-first-glob-guard.js +94 -0
  16. package/lib/hooks/serena-first-guard.js +74 -0
  17. package/lib/hooks/serena-first-read-guard.js +167 -0
  18. package/lib/hooks/serena-pre-delegation.js +117 -0
  19. package/lib/hooks/serena-session-reset.js +45 -0
  20. package/lib/hooks/serena-usage-tracker.js +186 -0
  21. package/lib/hooks/serena-write-guard.js +58 -0
  22. package/lib/prompts/README.md +16 -0
  23. package/lib/prompts/migrate-wiki.md +111 -0
  24. package/lib/prompts/setup-deployment.md +322 -0
  25. package/lib/prompts/setup-design-system.md +162 -0
  26. package/lib/prompts/setup-strict-typechecks.md +139 -0
  27. package/lib/scripts/README.md +49 -0
  28. package/lib/scripts/bootstrap-serena.sh +145 -0
  29. package/lib/scripts/build-mcp-guide.sh +108 -0
  30. package/lib/scripts/install-global.sh +78 -0
  31. package/lib/scripts/install-mcps.sh +131 -0
  32. package/lib/scripts/lib.sh +154 -0
  33. package/lib/scripts/merge-gitignore.sh +65 -0
  34. package/lib/scripts/migrate-project.sh +273 -0
  35. package/lib/scripts/setup-deployment.sh +104 -0
  36. package/lib/scripts/setup-project.sh +55 -0
  37. package/lib/scripts/setup-runner.sh +99 -0
  38. package/lib/scripts/setup-strict-typechecks.sh +29 -0
  39. package/lib/scripts/startup.sh +42 -0
  40. package/lib/scripts/sync-wiki-scaffold.sh +104 -0
  41. package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
  42. package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
  43. package/lib/scripts/templates/gitignore +136 -0
  44. package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
  45. package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
  46. package/lib/scripts/templates/guides/stubs/context7.md +26 -0
  47. package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
  48. package/lib/scripts/templates/guides/stubs/serena.md +219 -0
  49. package/lib/scripts/templates/wiki/conventions.md +100 -0
  50. package/lib/scripts/templates/wiki/dashboard.html +1733 -0
  51. package/lib/scripts/templates/wiki/hot.md +21 -0
  52. package/lib/scripts/templates/wiki/index.md +46 -0
  53. package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
  54. package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
  55. package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
  56. package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
  57. package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
  58. package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
  59. package/lib/scripts/templates/wiki/log.md +14 -0
  60. package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
  61. package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
  62. package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
  63. package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
  64. package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
  65. package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
  66. package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
  67. package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
  68. package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
  69. package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
  70. package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
  71. package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
  72. package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
  73. package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
  74. package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
  75. package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
  76. package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
  77. package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
  78. package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
  79. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
  80. package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
  81. package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
  82. package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
  83. package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
  84. package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
  85. package/lib/scripts/update-project.sh +75 -0
  86. package/lib/scripts/wiki-dashboard-server.js +146 -0
  87. package/lib/skills/README.md +146 -0
  88. package/lib/skills/anti-slop/SKILL.md +183 -0
  89. package/lib/skills/bug-close/SKILL.md +136 -0
  90. package/lib/skills/bug-file/SKILL.md +114 -0
  91. package/lib/skills/bug-triage/SKILL.md +140 -0
  92. package/lib/skills/company-align/SKILL.md +203 -0
  93. package/lib/skills/debug-logs/SKILL.md +129 -0
  94. package/lib/skills/decision-create/SKILL.md +220 -0
  95. package/lib/skills/decision-finalize/SKILL.md +181 -0
  96. package/lib/skills/decision-next/SKILL.md +129 -0
  97. package/lib/skills/decision-walkthrough/SKILL.md +169 -0
  98. package/lib/skills/demo/SKILL.md +183 -0
  99. package/lib/skills/elevator-pitch/SKILL.md +125 -0
  100. package/lib/skills/eval-create/SKILL.md +344 -0
  101. package/lib/skills/eval-gap/SKILL.md +150 -0
  102. package/lib/skills/eval-run/SKILL.md +214 -0
  103. package/lib/skills/extract-feature/SKILL.md +344 -0
  104. package/lib/skills/flashcard/SKILL.md +513 -0
  105. package/lib/skills/frontend-taste/SKILL.md +184 -0
  106. package/lib/skills/gap-assess/SKILL.md +97 -0
  107. package/lib/skills/git-commit/SKILL.md +164 -0
  108. package/lib/skills/lint/SKILL.md +99 -0
  109. package/lib/skills/marp-slideshow/SKILL.md +212 -0
  110. package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
  111. package/lib/skills/now/SKILL.md +36 -0
  112. package/lib/skills/port-feature/SKILL.md +315 -0
  113. package/lib/skills/power-mode/SKILL.md +184 -0
  114. package/lib/skills/primer/SKILL.md +84 -0
  115. package/lib/skills/project-readme/SKILL.md +166 -0
  116. package/lib/skills/req-compile/SKILL.md +131 -0
  117. package/lib/skills/req-create/SKILL.md +124 -0
  118. package/lib/skills/req-extract-decisions/SKILL.md +241 -0
  119. package/lib/skills/req-finalize/SKILL.md +251 -0
  120. package/lib/skills/req-retire/SKILL.md +185 -0
  121. package/lib/skills/req-update/SKILL.md +265 -0
  122. package/lib/skills/research/SKILL.md +250 -0
  123. package/lib/skills/research-company/SKILL.md +345 -0
  124. package/lib/skills/roadmap-add/SKILL.md +238 -0
  125. package/lib/skills/roadmap-create/SKILL.md +223 -0
  126. package/lib/skills/roadmap-next/SKILL.md +132 -0
  127. package/lib/skills/security-audit/SKILL.md +246 -0
  128. package/lib/skills/serena-config/SKILL.md +92 -0
  129. package/lib/skills/simplify/SKILL.md +227 -0
  130. package/lib/skills/tackle/SKILL.md +156 -0
  131. package/lib/skills/task-add/SKILL.md +208 -0
  132. package/lib/skills/task-audit/SKILL.md +294 -0
  133. package/lib/skills/task-trash/SKILL.md +115 -0
  134. package/lib/skills/task-update/SKILL.md +136 -0
  135. package/lib/skills/uat-auto/SKILL.md +69 -0
  136. package/lib/skills/uat-auto-plus/SKILL.md +115 -0
  137. package/lib/skills/uat-generate/SKILL.md +289 -0
  138. package/lib/skills/uat-skip/SKILL.md +169 -0
  139. package/lib/skills/uat-walk/SKILL.md +164 -0
  140. package/lib/skills/uat-walk/UAT-CORE.md +140 -0
  141. package/lib/skills/update-docs/SKILL.md +75 -0
  142. package/lib/skills/wiki-archive/SKILL.md +96 -0
  143. package/lib/skills/wiki-ingest/SKILL.md +139 -0
  144. package/lib/skills/wiki-lint/SKILL.md +131 -0
  145. package/lib/skills/wiki-query/SKILL.md +71 -0
  146. package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
  147. package/lib/skills/wiki-tidy/SKILL.md +107 -0
  148. package/package.json +32 -0
  149. package/raw/.gitkeep +0 -0
  150. package/raw/design-principles.md +65 -0
  151. package/raw/guides/command-anti-patterns.md +79 -0
  152. package/raw/guides/deployment-strategy.md +448 -0
  153. package/raw/guides/evals-framework.md +452 -0
  154. package/raw/guides/mcp-tools.md +335 -0
  155. package/raw/guides/task-spec.md +79 -0
  156. package/raw/guides/type-checking-templates/README.md +112 -0
  157. package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
  158. package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
  159. package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
  160. package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
  161. package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
  162. package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
  163. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
  164. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
  165. package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
  166. package/raw/harness-notes.md +20 -0
  167. package/raw/house-style/components/Badge.tsx +16 -0
  168. package/raw/house-style/components/Button.tsx +32 -0
  169. package/raw/house-style/components/Card.tsx +26 -0
  170. package/raw/house-style/components/Chip.tsx +57 -0
  171. package/raw/house-style/components/IconButton.tsx +67 -0
  172. package/raw/house-style/components/Modal.tsx +18 -0
  173. package/raw/house-style/components/Stepper.tsx +141 -0
  174. package/raw/house-style/components/icons.tsx +128 -0
  175. package/raw/house-style/preview/src/index.css +46 -0
  176. package/raw/house-style/tokens/tailwind.preset.ts +49 -0
  177. package/raw/house-style/tokens/tokens.json +62 -0
  178. package/raw/llm-wiki-2.md +162 -0
  179. package/raw/llm-wiki.md +75 -0
  180. package/raw/research/dark-mode-theme/index.md +85 -0
  181. package/raw/research/dark-mode-theme/sources.md +49 -0
  182. package/raw/research/serena-mcp-disconnect/index.md +81 -0
  183. package/raw/research/serena-mcp-disconnect/sources.md +87 -0
  184. package/raw/research/wiki-tooling-improvements/index.md +126 -0
  185. package/raw/research/wiki-tooling-improvements/sources.md +73 -0
  186. package/raw/software-factory-case-study.pdf +0 -0
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: gap-assess
3
+ description: Audit the current app's functionality against expected functionality and produce a gap assessment as an approvable plan (runs in plan mode, delegates to subagents)
4
+ category: researching
5
+ model: claude-opus-4-8
6
+ effort: high
7
+ argument-hint: <expected functionality — inline description or path to a requirements/spec file>
8
+ disable-model-invocation: false
9
+ user-invocable: true
10
+ ---
11
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
12
+
13
+ # Gap Assess
14
+
15
+ Audit what the current app **actually does**, compare it against the **expected functionality** supplied in `$ARGUMENTS`, and present a **gap assessment plus a remediation plan**.
16
+
17
+ **This skill runs in plan mode.** Enter plan mode at the start, do all work read-only, and deliver the gap assessment and remediation steps as the plan you submit for approval via `ExitPlanMode`. Do not modify source code.
18
+
19
+ ---
20
+
21
+ **Expected functionality**: `$ARGUMENTS`
22
+
23
+ - If `$ARGUMENTS` is (or starts with) an existing file path, read that file as the expected-functionality spec (PRD, requirements doc, brief, checklist).
24
+ - Otherwise treat the text as an inline description of expected functionality.
25
+ - If `$ARGUMENTS` is empty, fall back to requirements docs in `wiki/work/requirements/` and `wiki/work/decisions/`; if none exist, ask the user to specify the expected functionality before continuing.
26
+
27
+ ---
28
+
29
+ ## Phase 0 — Enter plan mode
30
+
31
+ Enter plan mode immediately (`EnterPlanMode`). Everything that follows is analysis only — no edits, no writes to source.
32
+
33
+ ---
34
+
35
+ ## Phase 1 — Context
36
+
37
+ 1. Summarize the expected functionality from `$ARGUMENTS` in your own words. Resolve whether it is inline text or a file path and load accordingly.
38
+ 2. Identify which parts of the codebase are relevant to that expected functionality.
39
+
40
+ ---
41
+
42
+ ## Phase 2 — Recall Serena memories
43
+
44
+ Before auditing, check for relevant project knowledge:
45
+
46
+ - `mcp__serena__list_memories` → scan for memories related to the feature area.
47
+ - `mcp__serena__read_memory` → read any relevant memories (architecture decisions, known gotchas, integration patterns) to inform the audit.
48
+
49
+ ---
50
+
51
+ ## Phase 3 — Audit current functionality
52
+
53
+ Use **Serena MCP** for all code exploration — never `bash` commands like `ls`, `cat`, `find`, or `grep` on source files.
54
+
55
+ Delegate the audit to subagents (**absolute maximum of 3 concurrent**). Split the relevant codebase by area (e.g. routes/commands, services, data layer, UI). Each subagent uses `mcp__serena__get_symbols_overview` and `find_symbol` to discover what the code actually does.
56
+
57
+ Compile a **functionality inventory** — a flat list of distinct, user-visible capabilities the app currently has. For each: what it does and how it's triggered (click path, command, or code entry point). Mark anything you cannot verify in code as `[UNVERIFIED]`.
58
+
59
+ ---
60
+
61
+ ## Phase 4 — Build the expected-functionality checklist
62
+
63
+ Turn the expected functionality from `$ARGUMENTS` into a flat list of discrete, testable requirements, one line each, e.g. `EXP-01: User can reset their password via email`. If the spec is a file, extract user stories, functional requirements, and acceptance criteria. Note explicit non-goals so you don't flag them as gaps.
64
+
65
+ ---
66
+
67
+ ## Phase 5 — Gap analysis
68
+
69
+ Cross-reference the expected checklist against the current functionality inventory. Classify each expected item:
70
+
71
+ - **✅ Covered** — implemented and verifiable in code.
72
+ - **🟡 Partial** — partially implemented, or implemented but with caveats (incomplete edge cases, missing validation, stubbed).
73
+ - **🔴 Gap** — no implementation found.
74
+ - **➕ Undocumented** — a capability exists in code but is not in the expected spec (surface for awareness, not as a defect).
75
+
76
+ For each Partial and Gap, note the evidence (file/symbol references) and a rough effort/complexity estimate.
77
+
78
+ ---
79
+
80
+ ## Phase 6 — Present the gap assessment (plan)
81
+
82
+ Submit the following as the plan via `ExitPlanMode`:
83
+
84
+ 1. **Coverage table** — every expected item with its status (Covered / Partial / Gap / Undocumented) and a one-line note with `file:symbol` evidence.
85
+ 2. **Summary** — counts per status and the headline finding (e.g. "7/10 covered, 2 partial, 1 gap").
86
+ 3. **Remediation plan** — ordered, concrete steps to close the Partial and Gap items, each scoped as a deliverable a subagent could execute, with dependencies and rough effort. This is what the user approves.
87
+
88
+ Keep claims grounded in code evidence. Do not invent functionality not found in the codebase or implied by the spec.
89
+
90
+ ---
91
+
92
+ ## CRITICAL rules
93
+
94
+ 1. **Plan mode only** — no source edits; the deliverable is the gap assessment + remediation plan submitted via `ExitPlanMode`.
95
+ 2. **Absolute maximum of 3 sub-processes at a time.**
96
+ 3. **Always terminate any processes you start** (dev servers, type checkers, long-running commands).
97
+ 4. **Serena for all code exploration** — never `bash` file commands on source.
@@ -0,0 +1,164 @@
1
+ ---
2
+ name: git-commit
3
+ description: Stage all changed files and create a commit with an auto-generated message, including semver version bump
4
+ category: executing
5
+ model: claude-haiku-4-5-20251001
6
+ disable-model-invocation: true
7
+ user-invocable: true
8
+ ---
9
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`.
10
+
11
+ # git-commit
12
+
13
+ ## Step 1: Run Lint Fix Cycles
14
+
15
+ Before committing, run the `/lint` workflow to catch and fix any diagnostics:
16
+
17
+ 1. Execute the full `/lint` command (all cycles until clean or issues are skipped)
18
+ 2. If any fixes were applied, they will be included in the commit automatically
19
+ 3. If any issues were skipped (unfixable), warn the user before proceeding
20
+
21
+ ## Step 2: Assess Changes
22
+
23
+ **Always run all three commands fresh.** Do not rely on session context, prior output, or anything produced earlier in the conversation — those reflect only a subset of what may have changed. The commit message must be based on the complete current working-tree state.
24
+
25
+ Run all three in parallel:
26
+
27
+ - `git status` — see all modified/untracked files
28
+ - `git diff HEAD` — see exact diffs for ALL staged and unstaged changes
29
+ - `git log --oneline -10` — see recent commit history for context
30
+
31
+ ## Step 3: Summarize Changes and Recommend Semver Bump
32
+
33
+ Before touching any files or committing, output a summary block like this:
34
+
35
+ ---
36
+
37
+ **Changes being committed:**
38
+ - <bullet list of what changed and why, derived from the diff>
39
+
40
+ **Suggested version bump: PATCH / MINOR / MAJOR**
41
+
42
+ **Why:** <one or two sentences explaining which semver rule applies>
43
+
44
+ ---
45
+
46
+ Use these semver rules to determine the bump:
47
+
48
+ | Bump | When to use |
49
+ |------|-------------|
50
+ | **patch** | Bug fixes, typos, docs updates, refactors with no behavior change, dependency updates with no API change |
51
+ | **minor** | New features or capabilities that are backward-compatible; new commands, skills, config options, or APIs added without breaking existing ones |
52
+ | **major** | Breaking changes — removed or renamed commands/APIs/config keys, changed behavior that callers must update for, deleted files that others depend on |
53
+
54
+ Print the summary, then **proceed immediately** with the suggested bump — no user confirmation needed.
55
+
56
+ ## Step 4: Bump Version in Project Files
57
+
58
+ Find and update version numbers in project files.
59
+
60
+ ### Detection
61
+
62
+ Run this command to find all manifest files anywhere in the repo (excluding `node_modules` and hidden dirs):
63
+
64
+ ```bash
65
+ find . \( -name node_modules -o -name .git \) -prune -o \
66
+ \( -name "package.json" -o -name "pyproject.toml" -o -name "Cargo.toml" \
67
+ -o -name "setup.cfg" -o -name "VERSION" -o -name "version.txt" \) \
68
+ -print
69
+ ```
70
+
71
+ Filter results:
72
+ - For `package.json`: only include files that contain a `"version"` field (skip `node_modules` entries even if the prune missed them)
73
+ - For `pyproject.toml` / `Cargo.toml` / `setup.cfg`: only include files with an actual `version =` line under a recognized section
74
+
75
+ **There is no "root only" rule.** A manifest anywhere in the tree counts. Monorepo layouts with no root-level manifest are normal — update every package found.
76
+
77
+ If **no files with a version field** are found anywhere in the repo, skip this step entirely and proceed to Step 5.
78
+
79
+ ### Bumping rules
80
+
81
+ Given the current version string (e.g. `1.2.3`):
82
+
83
+ | Bump | Result |
84
+ |------|--------|
85
+ | patch | `1.2.3` → `1.2.4` |
86
+ | minor | `1.2.3` → `1.3.0` |
87
+ | major | `1.2.3` → `2.0.0` |
88
+
89
+ Pre-release tags (e.g. `1.0.0-beta.1`) — strip the pre-release suffix and apply the bump normally.
90
+
91
+ Edit **every file** that contains a version using the Edit tool — do not stop at one. Then include all version-bump edits in the commit automatically (no separate commit needed).
92
+
93
+ ## Step 5: Commit
94
+
95
+ ### ⛔ Never create a branch — commit on the current branch
96
+
97
+ **NEVER run `git branch`, `git checkout -b`, `git switch -c`, or any other branch-creating or branch-switching command.** Commit onto whatever branch is currently checked out, even if that is `main` or `master`. Creating or switching branches is out of scope for this skill and is explicitly forbidden — if you think a branch is warranted, stop and tell the user rather than doing it yourself.
98
+
99
+ - `git-commit` is a bash alias for `git add . && git commit -m`
100
+ - **ALWAYS use the `git-commit` bash alias.** Never use `git add` or `git commit` directly.
101
+ - Always commit ALL files unless they are in `.gitignore`
102
+ - Consider an appropriate commit message, let's call it `$message`
103
+ - Prefix the subject with the bump type in brackets: `[patch]`, `[minor]`, or `[major]`
104
+ - Run: `git-commit "$message"`
105
+
106
+ ### ⛔ Commit-message format rules — STRICT
107
+
108
+ The commit message MUST be a **single-line, single-quoted-argument string**. Subject only, no body. This is a hard rule because anything else triggers a Bash approval prompt and slows you down.
109
+
110
+ **Required form:**
111
+
112
+ ```bash
113
+ git-commit "[patch] Single-line subject describing the change"
114
+ ```
115
+
116
+ That's it. One pair of double quotes. One line. One argument.
117
+
118
+ **❌ Forbidden — every one of these patterns triggers an approval prompt:**
119
+
120
+ ```bash
121
+ # WRONG — heredoc / command substitution
122
+ git-commit "$(cat <<'EOF'
123
+ Some subject
124
+
125
+ Some body line.
126
+ EOF
127
+ )"
128
+
129
+ # WRONG — printf
130
+ git-commit "$(printf 'subject\n\nbody')"
131
+
132
+ # WRONG — ANSI-C quoted string with embedded newlines
133
+ git-commit $'subject\n\nbody'
134
+
135
+ # WRONG — actual newlines inside the quoted string
136
+ git-commit "subject
137
+
138
+ body"
139
+
140
+ # WRONG — multiple -m flags or any extra args (the alias hardcodes one -m)
141
+ git-commit "subject" "-m" "body"
142
+
143
+ # WRONG — piping or chaining
144
+ echo "subject" | git-commit -F -
145
+ ```
146
+
147
+ **✅ Correct — always:**
148
+
149
+ ```bash
150
+ git-commit "[patch] Fix UAT verdict logic for edge-case test skips"
151
+ git-commit "[minor] Add /task-audit skill with dependency graph and wave output"
152
+ git-commit "[major] Rename all skills to noun-first convention, drop legacy verb-first aliases"
153
+ ```
154
+
155
+ ### Writing a good single-line subject
156
+
157
+ If the change feels too complex to summarize in one line, **make the subject more descriptive** — do not reach for a multi-line body. Aim for ~70–100 characters but go longer if it adds real information. Lead with the *what* and the *why* on the same line, separated by a colon when helpful:
158
+
159
+ - ✅ `[minor] Require research for every test type in /uat-generate with checkpoint gate`
160
+ - ✅ `[patch] Allow standard tools for markdown editing; ban bash exploration commands`
161
+ - ❌ `Update commands` (too vague, missing bump prefix)
162
+ - ❌ `[patch] Fix bug` (too vague)
163
+
164
+ Detailed reasoning, before/after examples, and rationale belong in **PR descriptions**, not in commit message bodies. The commit subject is the index entry; the PR is the encyclopedia.
@@ -0,0 +1,99 @@
1
+ ---
2
+ name: lint
3
+ description: Get IDE diagnostics then fix issues one-by-one in verify cycles
4
+ category: executing
5
+ model: claude-sonnet-4-6
6
+ disable-model-invocation: false
7
+ user-invocable: true
8
+ ---
9
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`.
10
+
11
+ # Lint Fix Cycles
12
+
13
+ Use IDE diagnostics to find and fix lint errors/warnings one at a time, verifying each fix before moving on.
14
+
15
+ ---
16
+
17
+ ## Step 1: Detect Source Directory
18
+
19
+ Determine the project's primary source directory:
20
+
21
+ 1. Check for common source directories in order: `src/`, `app/`, `lib/`, `pages/`, `components/`
22
+ 2. If none exist, use the project root (`.`)
23
+ 3. Note the detected path for reporting
24
+
25
+ ---
26
+
27
+ ## Step 2: Get Diagnostics
28
+
29
+ Use the `mcp__ide__getDiagnostics` tool to retrieve **all** current diagnostics — errors, warnings, info, and hints.
30
+
31
+ - Filter results to only include diagnostics from files within the detected source directory
32
+ - Include **every severity level**: errors, warnings (including CSS conflicts, unused imports, type issues), info, and hints
33
+ - Sort by severity: **errors first**, then warnings, then info/hints
34
+ - If no diagnostics are found, report "No lint issues found!" and **STOP**
35
+
36
+ Common warning types to look for:
37
+ - **CSS conflicts** (`cssConflict`) — e.g., conflicting Tailwind classes like `max-w-[80%]` with `max-w-none`
38
+ - **Unused variables/imports** — declared but never referenced
39
+ - **Type warnings** — implicit `any`, missing return types
40
+ - **Accessibility** — missing alt text, ARIA issues
41
+
42
+ Display a summary:
43
+ ```
44
+ Found X issue(s) — Y error(s), Z warning(s), N info/hint(s)
45
+ ```
46
+
47
+ ---
48
+
49
+ ## Step 3: Fix the First Issue (Cycle Start)
50
+
51
+ Take the **first** diagnostic (highest severity) and fix it:
52
+
53
+ 1. **Read the relevant code** using Serena symbolic tools or Read tool
54
+ 2. **Understand the issue** — what the diagnostic message means and what caused it
55
+ 3. **Apply the fix** — use the appropriate editing tool (Serena symbolic edit for code symbols, Edit for line-level changes)
56
+ 4. Keep fixes minimal and focused — only change what's needed to resolve the specific diagnostic
57
+
58
+ ### Fix strategies by diagnostic type
59
+
60
+ - **CSS conflict warnings** (e.g., `cssConflict`): Remove the conflicting/redundant class from the class string. When two Tailwind utilities set the same CSS property, remove the one that gets overridden.
61
+ - **Unused imports/variables**: Remove the unused declaration
62
+ - **Type errors**: Add proper types, fix mismatches
63
+ - **General lint warnings**: Follow the diagnostic's suggestion or apply the standard fix for the rule
64
+
65
+ ---
66
+
67
+ ## Step 4: Verify the Fix
68
+
69
+ After applying the fix:
70
+
71
+ 1. Call `mcp__ide__getDiagnostics` again
72
+ 2. Check if the specific diagnostic from Step 3 is **gone**
73
+ - **If fixed**: Report success — `"Fixed: [diagnostic message] in [file]"` — Cycle complete
74
+ - **If still present or new issues introduced**: Report the problem and attempt an alternative fix (max 2 retries per issue). If still failing after retries, skip the issue, report it as unresolvable, and move on
75
+
76
+ ---
77
+
78
+ ## Step 5: Continue or Stop
79
+
80
+ After a successful cycle:
81
+
82
+ 1. Check remaining diagnostics count
83
+ 2. If **more issues remain**: Report progress (`"Cycle N complete. X issue(s) remaining."`) and return to **Step 3** with the next diagnostic
84
+ 3. If **no issues remain**: Report completion and **STOP**
85
+
86
+ ```
87
+ All lint issues resolved! Fixed X issue(s) in Y cycle(s).
88
+ ```
89
+
90
+ ---
91
+
92
+ ## Rules
93
+
94
+ - **One fix per cycle** — never batch multiple fixes together
95
+ - **Verify after every fix** — always re-lint before moving to the next issue
96
+ - **Skip unfixable issues** — after 2 failed attempts, move on and report the skip
97
+ - **Don't introduce new issues** — if a fix creates new diagnostics, revert and try a different approach
98
+ - **Minimal changes only** — fix the diagnostic, nothing else
99
+ - **Report progress** — show cycle number, what was fixed, and remaining count after each cycle
@@ -0,0 +1,212 @@
1
+ ---
2
+ name: marp-slideshow
3
+ description: Summarize a file and emit a Marp/Marpit slideshow markdown deck following best practices
4
+ category: executing
5
+ model: claude-sonnet-4-6
6
+ argument-hint: <path to source file> [optional output path]
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
+ # Marp Slideshow
13
+
14
+ Read a source file at the path supplied in `$ARGUMENTS`, distill it into a structured outline, and emit a **Marpit-compatible Markdown slide deck** that follows the best practices below.
15
+
16
+ ---
17
+
18
+ **Source / args**: `$ARGUMENTS`
19
+
20
+ The first whitespace-separated token is the **input path** (required). An optional second token is the **output path**.
21
+
22
+ **Output path resolution rules** (apply in order):
23
+
24
+ 1. **No output path provided** → write to `.docs/MARP/<input-stem>.slides.md` (create `.docs/MARP/` if it doesn't exist). Do **not** place the deck next to the input file.
25
+ 2. **Output path provided** → always normalize the filename so it ends in `.slides.md`, even if the user didn't say so:
26
+ - `deck` → `deck.slides.md`
27
+ - `deck.md` → `deck.slides.md` (strip the trailing `.md`, then append `.slides.md`)
28
+ - `deck.slides.md` → keep as-is
29
+ - `path/to/deck.md` → `path/to/deck.slides.md` (preserve the directory the user gave)
30
+ 3. If the resolved output path collides with an existing file, ask the user before overwriting.
31
+
32
+ If `$ARGUMENTS` is empty, ask the user for the input path before proceeding.
33
+
34
+ ---
35
+
36
+ ## Phase 1 — Read & Summarize
37
+
38
+ 1. Read the input file with `Read` (markdown/config) or `mcp__serena__get_symbols_overview` + `mcp__serena__find_symbol` (code). Never `cat`/`head`.
39
+ 2. Extract:
40
+ - Title (filename stem if not obvious)
41
+ - Author / date metadata if present in front-matter or headers
42
+ - Top-level sections / headings → these usually become slide groups
43
+ - Key claims, data points, code snippets, diagrams, or commands worth a dedicated slide
44
+ 3. Produce a short outline (in your head, not a file) of 8–20 slides. Aim for **one idea per slide**, not one paragraph per slide.
45
+
46
+ ## Phase 2 — Plan the Deck
47
+
48
+ A standard structure:
49
+
50
+ 1. **Title slide** — title + subtitle/byline (`_class: lead`)
51
+ 2. **Agenda / Overview** — 3–6 bullets mapping the deck
52
+ 3. **Section slides** — each major section gets:
53
+ - A section divider slide (large heading, optional `_class: lead invert`)
54
+ - 1–N content slides for that section
55
+ 4. **Code / data slides** — fenced code blocks for code, tables for data
56
+ 5. **Summary / takeaways**
57
+ 6. **Q&A or thank-you slide**
58
+
59
+ Adjust based on the source: a short doc may collapse to 6 slides; a long one may need section dividers but should still cap around 20.
60
+
61
+ ## Phase 3 — Write the Deck
62
+
63
+ Use the `Write` tool to create the output file. The deck **must** start with a YAML front-matter block exactly like this template (tune values to the content):
64
+
65
+ ```markdown
66
+ ---
67
+ marp: true
68
+ theme: default
69
+ paginate: true
70
+ size: 16:9
71
+ header: '<short header or remove this line>'
72
+ footer: '<author or org · date>'
73
+ style: |
74
+ section { font-size: 28px; }
75
+ section.lead h1 { font-size: 64px; }
76
+ section.lead { text-align: center; }
77
+ h1, h2 { color: #0b3d91; }
78
+ code { font-size: 0.9em; }
79
+ ---
80
+ ```
81
+
82
+ Key rules:
83
+
84
+ - The **first** line after `---` opens the front-matter; the front-matter is the only place where `---` is **not** a slide break. After the closing `---`, every subsequent `---` on its own line is a slide separator.
85
+ - Always set `marp: true` so Marp CLI / VS Code Marp extension picks it up.
86
+ - Always set `paginate: true` (turn off per-slide with `<!-- _paginate: false -->` on the title slide).
87
+ - Use **local directives** (`<!-- backgroundColor: #fff -->`) for ranges and **spot directives with underscore prefix** (`<!-- _class: lead -->`, `<!-- _backgroundColor: black -->`, `<!-- _color: white -->`) for **single-slide** overrides.
88
+ - Keep slide content terse — if a slide has more than ~6 bullets or wraps past the visible area, split it.
89
+
90
+ ### Title slide pattern
91
+
92
+ ```markdown
93
+ <!-- _class: lead -->
94
+ <!-- _paginate: false -->
95
+
96
+ # Deck Title
97
+
98
+ #### Subtitle or one-line pitch
99
+
100
+ Author · YYYY-MM-DD
101
+
102
+ ---
103
+ ```
104
+
105
+ ### Section divider pattern
106
+
107
+ ```markdown
108
+ <!-- _class: lead -->
109
+ <!-- _backgroundColor: #0b3d91 -->
110
+ <!-- _color: white -->
111
+
112
+ # Section 2 — Architecture
113
+
114
+ ---
115
+ ```
116
+
117
+ ### Content slide pattern
118
+
119
+ ```markdown
120
+ ## Slide title (sentence-case is fine)
121
+
122
+ - Key point one — short, ideally < 10 words
123
+ - Key point two
124
+ - Key point three
125
+
126
+ > Optional pull-quote or callout
127
+
128
+ <!-- Speaker note: expand on point two; cite the metric from §3. -->
129
+
130
+ ---
131
+ ```
132
+
133
+ ### Image / background patterns
134
+
135
+ - Inline image with sizing: `![w:480](path.png)` or `![w:60% h:auto](path.png)`
136
+ - Full-bleed background: `![bg](path.jpg)`
137
+ - Split background (image left 40%, content right): `![bg left:40%](path.jpg)`
138
+ - Background with filter: `![bg blur:4px brightness:.8](path.jpg)`
139
+ - Solid color background for a slide: `![bg](#0b3d91)` or use `<!-- _backgroundColor: ... -->`
140
+
141
+ ### Code slide pattern
142
+
143
+ ````markdown
144
+ ## Quick example
145
+
146
+ ```php
147
+ final readonly class PatientId
148
+ {
149
+ public function __construct(public int $value) {}
150
+ }
151
+ ```
152
+
153
+ - Why it matters: …
154
+ - Tradeoff: …
155
+
156
+ ---
157
+ ````
158
+
159
+ ### Speaker notes
160
+
161
+ Marpit treats HTML comments as speaker notes when an exporter supports them. Add comments **inside** the slide they belong to, *before* the trailing `---`:
162
+
163
+ ```markdown
164
+ ## Slide title
165
+
166
+ - Bullet
167
+
168
+ <!--
169
+ Speaker note: full prose here. Multi-line is fine.
170
+ -->
171
+
172
+ ---
173
+ ```
174
+
175
+ Don't put directives and notes in the same comment — keep them in separate `<!-- ... -->` blocks so directive parsing stays clean.
176
+
177
+ ## Phase 4 — Best-practice Checklist (apply before writing)
178
+
179
+ Before calling `Write`, mentally verify:
180
+
181
+ - [ ] `marp: true` is in front-matter
182
+ - [ ] `theme`, `paginate`, `size` are set
183
+ - [ ] Title slide uses `_class: lead` and `_paginate: false`
184
+ - [ ] No slide exceeds ~6 bullets or ~40 words of body copy
185
+ - [ ] Each `---` between slides has a blank line above and below
186
+ - [ ] No `---` appears inside a slide body (use `***` for hr if you need a rule)
187
+ - [ ] Headings descend (no skipping H1 → H4); one H1 per slide max
188
+ - [ ] Code blocks are fenced with a language tag
189
+ - [ ] Images use Marpit sizing (`w:` / `h:` / `bg` / `bg left`) — no raw `<img>` unless necessary
190
+ - [ ] Speaker notes (HTML comments) are present where the source had context that didn't fit on-slide
191
+ - [ ] Footer / header are short (one line, no Markdown that breaks YAML — wrap in quotes if it contains `:` or `#`)
192
+ - [ ] Output filename ends in `.slides.md` (always — append/normalize even if the user-supplied path didn't include it)
193
+ - [ ] If the user did **not** supply an output path, the deck is written to `.docs/MARP/<input-stem>.slides.md` (not next to the source)
194
+
195
+ ## Phase 5 — Write & Confirm
196
+
197
+ 1. `Write` the deck to the output path.
198
+ 2. Print a short summary to the user:
199
+ - Output path
200
+ - Slide count
201
+ - Preview suggestion: `npx @marp-team/marp-cli@latest <output>.md` to render to HTML, or `npx @marp-team/marp-cli@latest <output>.md --pdf` for PDF, or open in VS Code with the **Marp for VS Code** extension.
202
+
203
+ ---
204
+
205
+ ## CRITICAL Rules
206
+
207
+ 1. **Never** modify the source file — only read it.
208
+ 2. Use `Read` for markdown/text source, Serena MCP for code source.
209
+ 3. Use `Write` (not `Edit`) to create the deck — it's a new file.
210
+ 4. Do not invent facts not in the source. If a section is unclear, mark the slide with a `<!-- TODO: verify ... -->` speaker-note comment instead of guessing.
211
+ 5. Do not embed images that aren't referenced in the source unless the user asks for them.
212
+ 6. Maximum of 3 sub-processes if you delegate research/summarization. Always terminate.