@thierrynakoa/fire-flow 10.0.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 (215) hide show
  1. package/.claude-plugin/plugin.json +64 -0
  2. package/ARCHITECTURE-DIAGRAM.md +440 -0
  3. package/COMMAND-REFERENCE.md +172 -0
  4. package/DOMINION-FLOW-OVERVIEW.md +421 -0
  5. package/LICENSE +21 -0
  6. package/QUICK-START.md +351 -0
  7. package/README.md +398 -0
  8. package/TROUBLESHOOTING.md +264 -0
  9. package/agents/fire-codebase-mapper.md +484 -0
  10. package/agents/fire-debugger.md +535 -0
  11. package/agents/fire-executor.md +949 -0
  12. package/agents/fire-fact-checker.md +276 -0
  13. package/agents/fire-learncoding-explainer.md +237 -0
  14. package/agents/fire-learncoding-walker.md +147 -0
  15. package/agents/fire-planner.md +675 -0
  16. package/agents/fire-project-researcher.md +155 -0
  17. package/agents/fire-research-synthesizer.md +166 -0
  18. package/agents/fire-researcher.md +723 -0
  19. package/agents/fire-reviewer.md +499 -0
  20. package/agents/fire-roadmapper.md +203 -0
  21. package/agents/fire-verifier.md +880 -0
  22. package/bin/cli.js +208 -0
  23. package/commands/fire-0-orient.md +476 -0
  24. package/commands/fire-1-new.md +281 -0
  25. package/commands/fire-1a-discuss.md +455 -0
  26. package/commands/fire-2-plan.md +527 -0
  27. package/commands/fire-3-execute.md +1303 -0
  28. package/commands/fire-4-verify.md +845 -0
  29. package/commands/fire-5-handoff.md +515 -0
  30. package/commands/fire-6-resume.md +501 -0
  31. package/commands/fire-7-review.md +409 -0
  32. package/commands/fire-add-new-skill.md +598 -0
  33. package/commands/fire-analytics.md +499 -0
  34. package/commands/fire-assumptions.md +78 -0
  35. package/commands/fire-autonomous.md +528 -0
  36. package/commands/fire-brainstorm.md +413 -0
  37. package/commands/fire-complete-milestone.md +270 -0
  38. package/commands/fire-dashboard.md +375 -0
  39. package/commands/fire-debug.md +663 -0
  40. package/commands/fire-discover.md +616 -0
  41. package/commands/fire-double-check.md +460 -0
  42. package/commands/fire-execute-plan.md +182 -0
  43. package/commands/fire-learncoding.md +242 -0
  44. package/commands/fire-loop-resume.md +272 -0
  45. package/commands/fire-loop-stop.md +198 -0
  46. package/commands/fire-loop.md +1168 -0
  47. package/commands/fire-map-codebase.md +313 -0
  48. package/commands/fire-new-milestone.md +356 -0
  49. package/commands/fire-reflect.md +235 -0
  50. package/commands/fire-research.md +246 -0
  51. package/commands/fire-search.md +330 -0
  52. package/commands/fire-security-audit-repo.md +293 -0
  53. package/commands/fire-security-scan.md +484 -0
  54. package/commands/fire-session-summary.md +252 -0
  55. package/commands/fire-skills-diff.md +506 -0
  56. package/commands/fire-skills-history.md +388 -0
  57. package/commands/fire-skills-rollback.md +408 -0
  58. package/commands/fire-skills-sync.md +470 -0
  59. package/commands/fire-test.md +520 -0
  60. package/commands/fire-todos.md +335 -0
  61. package/commands/fire-transition.md +186 -0
  62. package/commands/fire-update.md +312 -0
  63. package/commands/fire-verify-uat.md +146 -0
  64. package/commands/fire-vuln-scan.md +493 -0
  65. package/hooks/hooks.json +16 -0
  66. package/hooks/run-hook.cmd +69 -0
  67. package/hooks/run-hook.sh +8 -0
  68. package/hooks/run-session-end.cmd +49 -0
  69. package/hooks/run-session-end.sh +7 -0
  70. package/hooks/session-end.sh +90 -0
  71. package/hooks/session-start.sh +111 -0
  72. package/package.json +52 -0
  73. package/plugin.json +7 -0
  74. package/references/auto-skill-extraction.md +136 -0
  75. package/references/behavioral-directives.md +365 -0
  76. package/references/blocker-tracking.md +155 -0
  77. package/references/checkpoints.md +165 -0
  78. package/references/circuit-breaker.md +410 -0
  79. package/references/context-engineering.md +587 -0
  80. package/references/decision-time-guidance.md +289 -0
  81. package/references/error-classification.md +326 -0
  82. package/references/execution-mode-intelligence.md +242 -0
  83. package/references/git-integration.md +217 -0
  84. package/references/honesty-protocols.md +304 -0
  85. package/references/integration-architecture.md +470 -0
  86. package/references/issue-to-pr-pipeline.md +150 -0
  87. package/references/metrics-and-trends.md +234 -0
  88. package/references/playwright-e2e-testing.md +326 -0
  89. package/references/questioning.md +125 -0
  90. package/references/research-improvements.md +110 -0
  91. package/references/skills-usage-guide.md +429 -0
  92. package/references/tdd.md +131 -0
  93. package/references/testing-enforcement.md +192 -0
  94. package/references/ui-brand.md +383 -0
  95. package/references/validation-checklist.md +456 -0
  96. package/references/verification-patterns.md +187 -0
  97. package/references/warrior-principles.md +173 -0
  98. package/skills-library/SKILLS-INDEX.md +588 -0
  99. package/skills-library/_general/frontend/html-visual-reports.md +292 -0
  100. package/skills-library/_general/methodology/debug-swarm-researcher-escape-hatch.md +240 -0
  101. package/skills-library/_general/methodology/learncoding-agentic-pattern.md +114 -0
  102. package/skills-library/_general/methodology/shell-autonomous-loop-fixplan.md +238 -0
  103. package/skills-library/basics/api-rest-basics.md +162 -0
  104. package/skills-library/basics/env-variables.md +96 -0
  105. package/skills-library/basics/error-handling-basics.md +125 -0
  106. package/skills-library/basics/git-commit-conventions.md +106 -0
  107. package/skills-library/basics/readme-template.md +108 -0
  108. package/skills-library/common-tasks/async-await-patterns.md +157 -0
  109. package/skills-library/common-tasks/auth-jwt-basics.md +164 -0
  110. package/skills-library/common-tasks/database-schema-design.md +166 -0
  111. package/skills-library/common-tasks/file-upload-basics.md +166 -0
  112. package/skills-library/common-tasks/form-validation.md +159 -0
  113. package/skills-library/debugging/FAILURE_TAXONOMY_CLASSIFICATION.md +117 -0
  114. package/skills-library/debugging/THREE_AGENT_HYPOTHESIS_DEBUGGING.md +86 -0
  115. package/skills-library/methodology/BREATH_BASED_PARALLEL_EXECUTION.md +678 -0
  116. package/skills-library/methodology/CONFIDENCE_GATED_EXECUTION.md +243 -0
  117. package/skills-library/methodology/EVIDENCE_BASED_VALIDATION.md +308 -0
  118. package/skills-library/methodology/MULTI_PERSPECTIVE_CODE_REVIEW.md +330 -0
  119. package/skills-library/methodology/PATH_VERIFICATION_GATE.md +211 -0
  120. package/skills-library/methodology/REFLEXION_MEMORY_PATTERN.md +183 -0
  121. package/skills-library/methodology/RESEARCH_BACKED_WORKFLOW_UPGRADE.md +263 -0
  122. package/skills-library/methodology/SABBATH_REST_PATTERN.md +267 -0
  123. package/skills-library/methodology/STONE_AND_SCAFFOLD.md +220 -0
  124. package/skills-library/performance/cache-augmented-generation.md +172 -0
  125. package/skills-library/quality-safety/debugging-steps.md +147 -0
  126. package/skills-library/quality-safety/deployment-checklist.md +155 -0
  127. package/skills-library/quality-safety/security-checklist.md +204 -0
  128. package/skills-library/quality-safety/testing-basics.md +180 -0
  129. package/skills-library/security/agent-security-scanner.md +445 -0
  130. package/skills-library/specialists/api-architecture/api-designer.md +49 -0
  131. package/skills-library/specialists/api-architecture/graphql-architect.md +49 -0
  132. package/skills-library/specialists/api-architecture/mcp-developer.md +51 -0
  133. package/skills-library/specialists/api-architecture/microservices-architect.md +50 -0
  134. package/skills-library/specialists/api-architecture/websocket-engineer.md +48 -0
  135. package/skills-library/specialists/backend/django-expert.md +52 -0
  136. package/skills-library/specialists/backend/fastapi-expert.md +52 -0
  137. package/skills-library/specialists/backend/laravel-specialist.md +52 -0
  138. package/skills-library/specialists/backend/nestjs-expert.md +51 -0
  139. package/skills-library/specialists/backend/rails-expert.md +53 -0
  140. package/skills-library/specialists/backend/spring-boot-engineer.md +56 -0
  141. package/skills-library/specialists/data-ml/fine-tuning-expert.md +48 -0
  142. package/skills-library/specialists/data-ml/ml-pipeline.md +47 -0
  143. package/skills-library/specialists/data-ml/pandas-pro.md +47 -0
  144. package/skills-library/specialists/data-ml/rag-architect.md +51 -0
  145. package/skills-library/specialists/data-ml/spark-engineer.md +47 -0
  146. package/skills-library/specialists/frontend/angular-architect.md +52 -0
  147. package/skills-library/specialists/frontend/flutter-expert.md +51 -0
  148. package/skills-library/specialists/frontend/nextjs-developer.md +54 -0
  149. package/skills-library/specialists/frontend/react-native-expert.md +50 -0
  150. package/skills-library/specialists/frontend/vue-expert.md +51 -0
  151. package/skills-library/specialists/infrastructure/chaos-engineer.md +74 -0
  152. package/skills-library/specialists/infrastructure/cloud-architect.md +70 -0
  153. package/skills-library/specialists/infrastructure/database-optimizer.md +64 -0
  154. package/skills-library/specialists/infrastructure/devops-engineer.md +70 -0
  155. package/skills-library/specialists/infrastructure/kubernetes-specialist.md +52 -0
  156. package/skills-library/specialists/infrastructure/monitoring-expert.md +70 -0
  157. package/skills-library/specialists/infrastructure/sre-engineer.md +70 -0
  158. package/skills-library/specialists/infrastructure/terraform-engineer.md +51 -0
  159. package/skills-library/specialists/languages/cpp-pro.md +74 -0
  160. package/skills-library/specialists/languages/csharp-developer.md +69 -0
  161. package/skills-library/specialists/languages/dotnet-core-expert.md +54 -0
  162. package/skills-library/specialists/languages/golang-pro.md +51 -0
  163. package/skills-library/specialists/languages/java-architect.md +49 -0
  164. package/skills-library/specialists/languages/javascript-pro.md +68 -0
  165. package/skills-library/specialists/languages/kotlin-specialist.md +68 -0
  166. package/skills-library/specialists/languages/php-pro.md +49 -0
  167. package/skills-library/specialists/languages/python-pro.md +52 -0
  168. package/skills-library/specialists/languages/react-expert.md +51 -0
  169. package/skills-library/specialists/languages/rust-engineer.md +50 -0
  170. package/skills-library/specialists/languages/sql-pro.md +56 -0
  171. package/skills-library/specialists/languages/swift-expert.md +69 -0
  172. package/skills-library/specialists/languages/typescript-pro.md +51 -0
  173. package/skills-library/specialists/platform/atlassian-mcp.md +52 -0
  174. package/skills-library/specialists/platform/embedded-systems.md +53 -0
  175. package/skills-library/specialists/platform/game-developer.md +53 -0
  176. package/skills-library/specialists/platform/salesforce-developer.md +53 -0
  177. package/skills-library/specialists/platform/shopify-expert.md +49 -0
  178. package/skills-library/specialists/platform/wordpress-pro.md +49 -0
  179. package/skills-library/specialists/quality/code-documenter.md +51 -0
  180. package/skills-library/specialists/quality/code-reviewer.md +67 -0
  181. package/skills-library/specialists/quality/debugging-wizard.md +51 -0
  182. package/skills-library/specialists/quality/fullstack-guardian.md +51 -0
  183. package/skills-library/specialists/quality/legacy-modernizer.md +50 -0
  184. package/skills-library/specialists/quality/playwright-expert.md +65 -0
  185. package/skills-library/specialists/quality/spec-miner.md +56 -0
  186. package/skills-library/specialists/quality/test-master.md +65 -0
  187. package/skills-library/specialists/security/secure-code-guardian.md +55 -0
  188. package/skills-library/specialists/security/security-reviewer.md +53 -0
  189. package/skills-library/specialists/workflow/architecture-designer.md +53 -0
  190. package/skills-library/specialists/workflow/cli-developer.md +70 -0
  191. package/skills-library/specialists/workflow/feature-forge.md +65 -0
  192. package/skills-library/specialists/workflow/prompt-engineer.md +54 -0
  193. package/skills-library/specialists/workflow/the-fool.md +62 -0
  194. package/templates/ASSUMPTIONS.md +125 -0
  195. package/templates/BLOCKERS.md +73 -0
  196. package/templates/DECISION_LOG.md +116 -0
  197. package/templates/UAT.md +96 -0
  198. package/templates/blueprint.md +94 -0
  199. package/templates/brainstorm.md +185 -0
  200. package/templates/conscience.md +92 -0
  201. package/templates/fire-handoff.md +159 -0
  202. package/templates/metrics.md +67 -0
  203. package/templates/phase-prompt.md +142 -0
  204. package/templates/record.md +131 -0
  205. package/templates/review-report.md +117 -0
  206. package/templates/skills-index.md +157 -0
  207. package/templates/verification.md +149 -0
  208. package/templates/vision.md +79 -0
  209. package/validation-config.yml +793 -0
  210. package/version.json +7 -0
  211. package/workflows/execute-phase.md +732 -0
  212. package/workflows/handoff-session.md +678 -0
  213. package/workflows/new-project.md +578 -0
  214. package/workflows/plan-phase.md +592 -0
  215. package/workflows/verify-phase.md +874 -0
package/skills-library/_general/frontend/html-visual-reports.md ADDED
@@ -0,0 +1,292 @@
1
+ ---
2
+ name: html-visual-reports
3
+ category: frontend
4
+ version: 1.0.0
5
+ contributed: 2026-03-06
6
+ contributor: dominion-flow
7
+ last_updated: 2026-03-06
8
+ contributors:
9
+ - dominion-flow
10
+ tags: [html, css, visualization, reports, dashboards, data-tables, diagrams, self-contained]
11
+ difficulty: medium
12
+ usage_count: 0
13
+ success_rate: 100
14
+ ---
15
+
16
+ # HTML Visual Reports & Dashboards
17
+
18
+ ## Problem
19
+
20
+ When presenting data to stakeholders — competitive analyses, audit results, feature matrices, architecture overviews — plain text tables in the terminal are hard to read and impossible to share. Screenshots of terminal output look unprofessional. External tools (Google Slides, Figma) require context-switching and manual data entry.
21
+
22
+ Symptoms:
23
+ - ASCII box-drawing tables with 10+ rows are unreadable
24
+ - Stakeholders ask "can you put that in a slide?"
25
+ - Architecture diagrams drawn with text characters lack clarity
26
+ - Data comparisons lose impact without color-coded status indicators
27
+ - No way to share Claude's analysis output as a professional artifact
28
+
29
+ ## Solution Pattern
30
+
31
+ Generate **self-contained HTML files** that open directly in any browser. No build step, no dependencies, no server — just a single `.html` file with inline CSS, Google Fonts via CDN, and optional JavaScript for interactivity. The file IS the deliverable.
32
+
33
+ ### Core Architecture
34
+
35
+ Every report follows this structure:
36
+
37
+ ```html
38
+ <!DOCTYPE html>
39
+ <html lang="en">
40
+ <head>
41
+ <meta charset="UTF-8">
42
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
43
+ <title>Descriptive Title</title>
44
+ <link href="https://fonts.googleapis.com/css2?family=...&display=swap" rel="stylesheet">
45
+ <style>
46
+ /* CSS custom properties for theming */
47
+ /* Full layout, components, animations — all inline */
48
+ </style>
49
+ </head>
50
+ <body>
51
+ <!-- Semantic HTML: sections, headings, tables, inline SVG -->
52
+ <!-- Optional: <script> for Mermaid, scroll spy, or Chart.js -->
53
+ </body>
54
+ </html>
55
+ ```
56
+
57
+ ### Design System (CSS Custom Properties)
58
+
59
+ Every report defines a complete palette via CSS variables. This enables dark/light theme support and consistent styling:
60
+
61
+ ```css
62
+ :root {
63
+ --bg: #0a0e17;
64
+ --surface: #111827;
65
+ --surface2: #1a2236;
66
+ --border: rgba(255, 255, 255, 0.06);
67
+ --text: #e2e8f0;
68
+ --text-dim: #64748b;
69
+ --cyan: #22d3ee;
70
+ --cyan-dim: rgba(34, 211, 238, 0.10);
71
+ --green: #4ade80;
72
+ --green-dim: rgba(74, 222, 128, 0.10);
73
+ --red: #f87171;
74
+ --red-dim: rgba(248, 113, 113, 0.10);
75
+ --amber: #fbbf24;
76
+ --amber-dim: rgba(251, 191, 36, 0.10);
77
+ }
78
+
79
+ @media (prefers-color-scheme: light) {
80
+ :root {
81
+ --bg: #f0f4f8;
82
+ --surface: #ffffff;
83
+ /* ... light overrides ... */
84
+ }
85
+ }
86
+ ```
87
+
88
+ ### Aesthetic Variations
89
+
90
+ Rotate aesthetics to avoid cookie-cutter output:
91
+
92
+ | Aesthetic | When to Use | Font Pairing |
93
+ |-----------|-------------|--------------|
94
+ | Neon Dashboard | Competitive analysis, metrics, KPIs | Orbitron + JetBrains Mono |
95
+ | Editorial | Executive summaries, proposals | Instrument Serif + JetBrains Mono |
96
+ | Blueprint | Architecture diagrams, technical specs | Space Mono + system-ui |
97
+ | Paper/Ink | Documentation, guides | Literata + Fira Code |
98
+ | IDE-inspired | Code reviews, debug reports | Use Dracula/Nord/Catppuccin palette |
99
+
100
+ ### Key Components
101
+
102
+ **KPI Cards** — Large hero numbers with labels, color-coded by meaning:
103
+ ```html
104
+ <div class="kpi-row">
105
+ <div class="kpi-card">
106
+ <div class="kpi-card__value" style="color:var(--cyan)">42</div>
107
+ <div class="kpi-card__label">Commands</div>
108
+ </div>
109
+ </div>
110
+ ```
111
+
112
+ **Data Tables** — Real `<table>` elements with sticky headers, alternating rows, status badges:
113
+ ```html
114
+ <div class="table-wrap">
115
+ <div class="table-scroll">
116
+ <table class="data-table">
117
+ <thead><tr><th>Feature</th><th>Status</th></tr></thead>
118
+ <tbody>
119
+ <tr><td>Auth</td><td><span class="status status--yes">YES</span></td></tr>
120
+ <tr><td>Caching</td><td><span class="status status--no">NO</span></td></tr>
121
+ </tbody>
122
+ </table>
123
+ </div>
124
+ </div>
125
+ ```
126
+
127
+ **Status Badges** — Never use emoji. Use styled `<span>` elements:
128
+ ```css
129
+ .status--yes { background: var(--green-dim); color: var(--green); }
130
+ .status--no { background: var(--red-dim); color: var(--red); }
131
+ .status--partial { background: var(--amber-dim); color: var(--amber); }
132
+ ```
133
+
134
+ **Grade Badges** — Letter grades with color-coded borders:
135
+ ```css
136
+ .grade--a { background: var(--green-dim); color: var(--green); border: 1px solid var(--green); }
137
+ .grade--f { background: var(--red-dim); color: var(--red); border: 1px solid var(--red); }
138
+ ```
139
+
140
+ **Section Navigation** — For pages with 4+ sections, add a sticky sidebar TOC on desktop that collapses to a horizontal scrollable bar on mobile. Use IntersectionObserver for scroll-spy highlighting.
141
+
142
+ **Staggered Animations** — Use CSS `--i` variable per element for load stagger:
143
+ ```css
144
+ @keyframes fadeUp {
145
+ from { opacity: 0; transform: translateY(14px); }
146
+ to { opacity: 1; transform: translateY(0); }
147
+ }
148
+ .animate {
149
+ animation: fadeUp 0.4s ease-out both;
150
+ animation-delay: calc(var(--i, 0) * 0.05s);
151
+ }
152
+ ```
153
+
154
+ ### Diagram Types and Rendering
155
+
156
+ | Diagram Type | Approach |
157
+ |---|---|
158
+ | Architecture (text-heavy cards) | CSS Grid + flow arrows |
159
+ | Flowcharts, sequence diagrams | Mermaid.js via CDN |
160
+ | Data tables, comparisons | HTML `<table>` element |
161
+ | ER / schema diagrams | Mermaid erDiagram |
162
+ | Dashboards with charts | CSS Grid + Chart.js via CDN |
163
+ | Timelines | CSS central line + alternating cards |
164
+
165
+ ### Mermaid Integration
166
+
167
+ For flowcharts, sequence diagrams, and ER diagrams, use Mermaid.js with custom theming:
168
+
169
+ ```html
170
+ <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
171
+ <script>
172
+ mermaid.initialize({
173
+ theme: 'base',
174
+ themeVariables: {
175
+ primaryColor: '#1e293b',
176
+ primaryTextColor: '#e2e8f0',
177
+ lineColor: '#22d3ee'
178
+ }
179
+ });
180
+ </script>
181
+ ```
182
+
183
+ Always add zoom controls (+/-/reset buttons) to Mermaid containers.
184
+
185
+ ## Code Example
186
+
187
+ ```html
188
+ <!-- Before: ASCII table in terminal -->
189
+ <!--
190
+ | Feature | Us | Them |
191
+ |------------|-----|------|
192
+ | Auth | YES | NO |
193
+ | Memory | YES | YES |
194
+ | Parallel | YES | NO |
195
+ Unreadable at scale, can't share, no visual hierarchy
196
+ -->
197
+
198
+ <!-- After: Self-contained HTML report -->
199
+ <!DOCTYPE html>
200
+ <html lang="en">
201
+ <head>
202
+ <meta charset="UTF-8">
203
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
204
+ <title>Feature Comparison</title>
205
+ <link href="https://fonts.googleapis.com/css2?family=Orbitron:wght@700;900&family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet">
206
+ <style>
207
+ :root {
208
+ --bg: #0a0e17; --surface: #111827; --text: #e2e8f0;
209
+ --text-dim: #64748b; --border: rgba(255,255,255,0.06);
210
+ --cyan: #22d3ee; --cyan-dim: rgba(34,211,238,0.10);
211
+ --green: #4ade80; --green-dim: rgba(74,222,128,0.10);
212
+ --red: #f87171; --red-dim: rgba(248,113,113,0.10);
213
+ }
214
+ * { margin: 0; padding: 0; box-sizing: border-box; }
215
+ body { background: var(--bg); color: var(--text); font-family: system-ui; padding: 40px; }
216
+ h1 { font-family: 'Orbitron'; color: var(--cyan); font-size: 24px; margin-bottom: 24px; }
217
+ .table-wrap { background: var(--surface); border: 1px solid var(--border); border-radius: 12px; overflow: hidden; }
218
+ .data-table { width: 100%; border-collapse: collapse; font-size: 13px; }
219
+ .data-table th { background: #1a2236; font-family: 'JetBrains Mono'; font-size: 10px; text-transform: uppercase; letter-spacing: 1.2px; color: var(--text-dim); padding: 14px; text-align: left; }
220
+ .data-table td { padding: 12px 14px; border-bottom: 1px solid var(--border); }
221
+ .data-table tbody tr:hover { background: var(--cyan-dim); }
222
+ .status { font-family: 'JetBrains Mono'; font-size: 10px; font-weight: 600; padding: 3px 10px; border-radius: 6px; }
223
+ .status--yes { background: var(--green-dim); color: var(--green); }
224
+ .status--no { background: var(--red-dim); color: var(--red); }
225
+ </style>
226
+ </head>
227
+ <body>
228
+ <h1>Feature Comparison</h1>
229
+ <div class="table-wrap">
230
+ <table class="data-table">
231
+ <thead><tr><th>Feature</th><th>Us</th><th>Competitor</th></tr></thead>
232
+ <tbody>
233
+ <tr><td><strong>Auth</strong></td><td><span class="status status--yes">YES</span></td><td><span class="status status--no">NO</span></td></tr>
234
+ <tr><td><strong>Memory</strong></td><td><span class="status status--yes">YES</span></td><td><span class="status status--yes">YES</span></td></tr>
235
+ <tr><td><strong>Parallel</strong></td><td><span class="status status--yes">YES</span></td><td><span class="status status--no">NO</span></td></tr>
236
+ </tbody>
237
+ </table>
238
+ </div>
239
+ </body>
240
+ </html>
241
+ ```
242
+
243
+ ## Implementation Steps
244
+
245
+ 1. Choose an aesthetic that fits the audience and content type
246
+ 2. Pick a distinctive Google Fonts pairing (never use Inter/Roboto/Arial)
247
+ 3. Define the full CSS variable palette with both dark and light themes
248
+ 4. Structure content with semantic HTML (sections, headings, tables)
249
+ 5. Add KPI cards above tables for visual hook
250
+ 6. Use status badges (never emoji) for match/gap/partial indicators
251
+ 7. Add staggered fadeUp animations with `--i` variable
252
+ 8. Add section navigation if 4+ sections
253
+ 9. Add `@media (prefers-reduced-motion: reduce)` for accessibility
254
+ 10. Write to `~/.agent/diagrams/` and open in browser
255
+ 11. Always respect `overflow-wrap: break-word` and `min-width: 0` on flex/grid children
256
+
257
+ ## When to Use
258
+
259
+ - Competitive analysis or feature comparisons (4+ rows, 3+ columns)
260
+ - Architecture or system diagrams
261
+ - Audit results or requirement reviews
262
+ - Project dashboards with KPI metrics
263
+ - Any data you'd present as an ASCII table — generate HTML instead
264
+ - When sharing analysis output with stakeholders who don't use the terminal
265
+
266
+ ## When NOT to Use
267
+
268
+ - Quick 2-3 line comparisons that fit naturally in chat
269
+ - Internal debugging output that doesn't need to be shared
270
+ - When the user explicitly asks for plain text output
271
+ - Real-time dashboards that need live data (use a proper framework)
272
+
273
+ ## Common Mistakes
274
+
275
+ - Using flat solid backgrounds (add subtle radial gradients for atmosphere)
276
+ - Same animation on everything (use fadeUp for cards, fadeScale for KPIs)
277
+ - Forgetting `overflow-x: auto` wrapper on wide tables
278
+ - Using `display: flex` on `<li>` for markers (causes overflow — use absolute positioning)
279
+ - Not testing both light and dark themes via `prefers-color-scheme`
280
+ - Using emoji for status indicators instead of styled `<span>` elements
281
+ - Forgetting `min-width: 0` on CSS Grid/Flex children (causes container overflow)
282
+
283
+ ## Related Skills
284
+
285
+ - [plugin-doc-auto-generation](../plugin-development/plugin-doc-auto-generation.md) — Auto-generate plugin docs from filesystem
286
+ - [complexity-divider](../complexity-metrics/complexity-divider.md) — Complexity analysis patterns
287
+
288
+ ## References
289
+
290
+ - Contributed from: dominion-flow competitive analysis session (2026-03-06)
291
+ - Pattern refined across 20+ generated diagrams and dashboards
292
+ - Aesthetic catalog: Neon, Editorial, Blueprint, Paper/Ink, IDE-inspired, Hand-drawn
package/skills-library/_general/methodology/debug-swarm-researcher-escape-hatch.md ADDED
@@ -0,0 +1,240 @@
1
+ ---
2
+ name: debug-swarm-researcher-escape-hatch
3
+ category: methodology
4
+ version: 1.0.0
5
+ contributed: 2026-03-04
6
+ contributor: dominion-flow-v2
7
+ last_updated: 2026-03-04
8
+ tags: [debugging, swarm, multi-agent, escape-hatch, researcher, blocked, orchestration, autonomous-loop]
9
+ difficulty: hard
10
+ usage_count: 0
11
+ success_rate: 100
12
+ ---
13
+
14
+ # Debug Swarm Researcher Escape Hatch
15
+
16
+ ## Problem
17
+
18
+ Multi-agent debug swarms run parallel agents attacking the same bug from different hypotheses. When every hypothesis fails — every agent returns BLOCKED — the orchestrator is stuck. Spinning up identical agents produces identical failures. Halting loses all session context.
19
+
20
+ **Symptoms:**
21
+ - All swarm agents return `{status:"BLOCKED", issue, attempts_made[], error_context}` after N iterations
22
+ - No remaining hypotheses to test
23
+ - Loop stagnation: circuit breaker fires (`CB_STAGNATION >= limit`)
24
+ - Problem requires external knowledge: prior art, community solution, docs deep-dive
25
+
26
+ **The core trap:** You can't debug your way out of a knowledge gap. The swarm needs new information before it can make progress.
27
+
28
+ ## Solution Pattern
29
+
30
+ When the swarm hits a collective wall, **escape the debug loop entirely** and spawn a dedicated researcher agent. The researcher searches external sources (skills library, MCP servers, WebSearch, GitHub) and writes structured findings to a persistent file. The findings file is then injected into the next swarm iteration as first-class context.
31
+
32
+ ### The Three-Layer Escape
33
+
34
+ ```
35
+ Layer 1: SWARM AGENTS (parallel per hypothesis)
36
+ ↓ All return BLOCKED
37
+ Layer 2: ESCAPE TRIGGER (orchestrator detects collective BLOCKED)
38
+ ↓ Spawns fire-researcher instead of re-trying swarm
39
+ Layer 3: RESEARCHER (skills lib + MCP + WebSearch + GitHub)
40
+ ↓ Writes .planning/research/YYYY-MM-DD-{slug}.md
41
+ ↓ Returns research summary to orchestrator
42
+ Layer 1 again: NEW SWARM AGENTS (with research injected as context)
43
+ ↓ Fresh hypotheses informed by external knowledge
44
+ ```
45
+
46
+ **Key insight:** The escape does NOT count as a swarm iteration. The loop counter
47
+ stays constant. The researcher is outside the iteration budget.
48
+
49
+ ### BLOCKED Agent Response Contract
50
+
51
+ Swarm agents signal a wall using a structured response:
52
+
53
+ ```json
54
+ {
55
+ "status": "BLOCKED",
56
+ "issue": "Cannot determine why X fails — tried Y and Z",
57
+ "attempts_made": [
58
+ "Checked env variable binding — correct",
59
+ "Added console.log to line 47 — never fires",
60
+ "Tried disabling auth middleware — same result"
61
+ ],
62
+ "error_context": {
63
+ "error": "Cannot read properties of undefined (reading 'id')",
64
+ "file": "src/auth/middleware.ts",
65
+ "line": 23,
66
+ "stack": "..."
67
+ },
68
+ "files_checked": ["src/auth/middleware.ts", "src/routes/users.ts"]
69
+ }
70
+ ```
71
+
72
+ The orchestrator collects all BLOCKED responses and synthesizes a research brief.
73
+
74
+ ### Orchestrator Escape Logic
75
+
76
+ ```python
77
+ def check_escape_condition(swarm_results):
78
+ blocked_count = sum(1 for r in swarm_results if r["status"] == "BLOCKED")
79
+ if blocked_count == len(swarm_results):
80
+ # All agents blocked — trigger escape hatch
81
+ return True
82
+ return False
83
+
84
+ def build_research_brief(blocked_responses):
85
+ # Synthesize what the swarm tried and where it's stuck
86
+ all_attempts = [a for r in blocked_responses for a in r["attempts_made"]]
87
+ error_patterns = [r["error_context"] for r in blocked_responses]
88
+ return {
89
+ "problem_summary": "...",
90
+ "attempted_approaches": all_attempts,
91
+ "error_signatures": error_patterns,
92
+ "research_queries": [
93
+ "Cannot read properties undefined middleware chain express",
94
+ "JWT auth middleware undefined user id request context"
95
+ ]
96
+ }
97
+ ```
98
+
99
+ ### Researcher Sources (priority order)
100
+
101
+ ```
102
+ 1. Skills library search — Has this been solved before in our patterns?
103
+ 2. context7 MCP server — Framework/library official docs
104
+ 3. WebSearch — Community solutions, Stack Overflow, GitHub Issues
105
+ 4. GitHub code search — Real-world implementations of the pattern
106
+ 5. Episodic memory search — Did WE solve a similar issue in a past session?
107
+ ```
108
+
109
+ ### Research Output Format
110
+
111
+ Researcher writes to `.planning/research/YYYY-MM-DD-{slug}.md`:
112
+
113
+ ```markdown
114
+ # Research: {problem title}
115
+ **Date:** YYYY-MM-DD
116
+ **Trigger:** Debug swarm collective BLOCKED — N agents, N attempts
117
+
118
+ ## Root Cause Hypothesis (from research)
119
+ [What the researcher found that the swarm was missing]
120
+
121
+ ## Solution Approach
122
+ [Concrete steps to fix based on external sources]
123
+
124
+ ## Code Reference
125
+ ```[language]
126
+ // From: [source URL or skill name]
127
+ [relevant code snippet]
128
+ ```
129
+
130
+ ## Sources
131
+ - [Source 1 with URL]
132
+ - [Source 2 with URL]
133
+
134
+ ## Re-injection Prompt
135
+ [Ready-to-use context block for injecting into next swarm iteration]
136
+ ```
137
+
138
+ ### Re-injection Into Next Swarm Iteration
139
+
140
+ After researcher completes, the orchestrator spawns a fresh swarm with the research pre-loaded:
141
+
142
+ ```
143
+ CONTEXT FROM PREVIOUS SWARM + RESEARCHER:
144
+
145
+ The debug swarm tried N approaches and was blocked. A researcher agent
146
+ investigated and found:
147
+
148
+ [Research summary — from .planning/research/YYYY-MM-DD-{slug}.md]
149
+
150
+ Known dead ends (do NOT retry):
151
+ - [attempt 1]
152
+ - [attempt 2]
153
+
154
+ New hypotheses to test based on research:
155
+ - [fresh hypothesis 1 from external sources]
156
+ - [fresh hypothesis 2]
157
+ ```
158
+
159
+ ## Code Example
160
+
161
+ ```markdown
162
+ # fire-debug.md — Swarm Orchestrator (key escape section)
163
+
164
+ ## Swarm Mode Orchestrator
165
+
166
+ ```pseudocode
167
+ results = await Promise.all(swarm_agents.map(agent => agent.run()))
168
+
169
+ if results.every(r => r.status === "BLOCKED"):
170
+ # Escape hatch: all agents blocked
171
+ brief = build_research_brief(results)
172
+
173
+ research = await spawn_agent(
174
+ "fire-researcher",
175
+ {
176
+ query: brief.problem_summary,
177
+ search_sources: ["skills-library", "context7-mcp", "web-search", "github"],
178
+ write_to: f".planning/research/{today}-{slug}.md"
179
+ }
180
+ )
181
+
182
+ # Re-spawn swarm with research context (doesn't count as iteration)
183
+ new_swarm = spawn_swarm(hypotheses=research.new_hypotheses, context=research)
184
+ results = await new_swarm.run()
185
+ ```
186
+ ```
187
+
188
+ ## Implementation Steps
189
+
190
+ 1. Define BLOCKED response contract in swarm agent instructions (the JSON shape above)
191
+ 2. Implement `check_escape_condition()` in orchestrator — triggers when ALL agents blocked
192
+ 3. Implement `build_research_brief()` — synthesizes blocked responses into research queries
193
+ 4. Spawn `fire-researcher` (or equivalent) with the brief + write path
194
+ 5. Researcher writes structured `.planning/research/YYYY-MM-DD-{slug}.md`
195
+ 6. Orchestrator reads research, builds re-injection context block
196
+ 7. Spawn fresh swarm iteration with research pre-loaded as context
197
+
198
+ ## When to Use
199
+
200
+ - Multi-agent debug swarm where ALL agents return BLOCKED simultaneously
201
+ - Problem requires external knowledge (docs, prior art, community solutions)
202
+ - Stagnation circuit breaker has fired due to repeated identical failures
203
+ - The error pattern is unfamiliar — novel framework, obscure edge case, known bug in dependency
204
+ - You want to preserve research findings across sessions (write to disk, not just memory)
205
+
206
+ ## When NOT to Use
207
+
208
+ - Single-agent debugging (use systematic-debugging skill instead)
209
+ - Only 1-2 agents blocked (not all) — remaining agents may still find a path
210
+ - Problem is clearly a typo or obvious logic error (don't need external research)
211
+ - Swarm has only run 1 iteration (premature escape — try more hypotheses first)
212
+ - Time-critical hotfix where research delay is unacceptable
213
+
214
+ ## Common Mistakes
215
+
216
+ - **Counting escape as an iteration** — the researcher escape is outside the iteration budget; resetting the loop counter erases progress tracking
217
+ - **Vague research brief** — synthesize specific error signatures and exact code context, not just "it doesn't work". The researcher is only as good as the brief
218
+ - **Not writing research to disk** — if findings stay in memory only, they're lost on session compaction. Always write `.planning/research/*.md`
219
+ - **Re-injecting all research** — only inject the relevant new hypotheses, not the full research doc. Context window is precious
220
+ - **Escaping too early** — require collective BLOCKED (all agents, not just some). Partial blocking means other hypotheses are still viable
221
+
222
+ ## Exit Codes (when used in shell loop)
223
+
224
+ | Code | Meaning | Action |
225
+ |------|---------|--------|
226
+ | 0 | Bug fixed after research re-injection | Proceed to verify |
227
+ | 2 | Escape triggered, researcher found nothing | Human investigation required |
228
+ | 3 | Research found solution, fix not implemented | Apply research manually |
229
+
230
+ ## Related Skills
231
+
232
+ - [shell-autonomous-loop-fixplan](_general/methodology/shell-autonomous-loop-fixplan.md) — shell-level loop with BLOCKED signal (exit code 2)
233
+ - [autonomous-multi-phase-build](_general/methodology/autonomous-multi-phase-build.md) — phase-level orchestration
234
+ - [systematic-debugging] — single-agent debugging pattern
235
+
236
+ ## References
237
+
238
+ - Implemented in: `dominion-flow-v2/commands/fire-debug.md` (--swarm mode section)
239
+ - Inspired by: RLHF researcher escalation patterns + bmalph/Ralph BLOCKED exit
240
+ - Contributed from: dominion-flow-v2 build session 2026-03-04
package/skills-library/_general/methodology/learncoding-agentic-pattern.md ADDED
@@ -0,0 +1,114 @@
1
+ ---
2
+ name: learncoding-agentic-pattern
3
+ category: methodology
4
+ version: 1.0.0
5
+ contributed: 2026-03-04
6
+ contributor: dominion-flow-v2
7
+ last_updated: 2026-03-04
8
+ tags: [learning, walkthrough, cognitive-debt, simon-willison, agentic-engineering, linear-walkthrough, anti-vibe-coding]
9
+ difficulty: medium
10
+ usage_count: 0
11
+ success_rate: 100
12
+ ---
13
+
14
+ # Learncoding: Agentic Engineering Walkthrough Pattern
15
+
16
+ ## Problem
17
+
18
+ Vibe coding (accepting all AI output without understanding) creates **cognitive debt**:
19
+ you build things you can't explain, can't debug, and can't confidently extend.
20
+ Simon Willison's definition: "If you don't understand the code, your only recourse is
21
+ to ask AI to fix it — like paying off credit card debt with another credit card."
22
+
23
+ Symptoms:
24
+ - You can't explain a file you "wrote" with AI
25
+ - Bugs require asking AI to fix rather than reasoning yourself
26
+ - Architecture decisions feel opaque or arbitrary
27
+ - You'd fail a code review on your own code
28
+
29
+ ## Solution Pattern
30
+
31
+ Apply Simon Willison's **Linear Walkthrough** pattern:
32
+
33
+ > "Give me a linear walkthrough of the code that explains how it all works in detail."
34
+
35
+ Combined with his **Hoard Things You Know** principle: once you understand something,
36
+ capture it. The walkthrough document becomes your hoard entry.
37
+
38
+ ### The Three Questions Per File
39
+
40
+ For every file in the walkthrough, answer:
41
+ 1. **WHAT** — what does this file do for the user of the application?
42
+ 2. **WHY** — why is it written this way, not the obvious alternative?
43
+ 3. **PATTERN** — which design pattern is being used and what is its name?
44
+
45
+ ### The Showboat Extraction Rule
46
+
47
+ Never paraphrase code from memory. Always extract real snippets using shell tools:
48
+
49
+ ```bash
50
+ # Extract real code — prevents LLM hallucination of "close but wrong" code
51
+ cat src/auth/middleware.ts # whole file
52
+ sed -n '/^export function/,/^}/p' src/auth.ts # specific function
53
+ grep -A 20 "class UserService" src/services/user.ts # class body
54
+ ```
55
+
56
+ This is the core principle from Willison's Showboat tool — agents that
57
+ copy code from memory will introduce subtle errors. Shell extraction is exact.
58
+
59
+ ## Code Example
60
+
61
+ ```bash
62
+ # The four-step learncoding workflow
63
+ # 1. Load source
64
+ gh api repos/user/repo/git/trees/HEAD?recursive=1 \
65
+ --jq '.tree[] | select(.type=="blob") | .path' > files.txt
66
+
67
+ # 2. Detect entry point
68
+ cat package.json | jq -r '.main // .scripts.start'
69
+
70
+ # 3. Extract real snippet (Showboat principle)
71
+ gh api repos/user/repo/contents/src/index.ts \
72
+ --jq '.content' | base64 -d
73
+
74
+ # 4. Walk imports breadth-first from entry point
75
+ grep -E "^import.*from ['\"]\./" src/index.ts
76
+ ```
77
+
78
+ ## When to Use
79
+
80
+ - Learning a new codebase before contributing
81
+ - Recreating a GitHub project from scratch to understand it deeply
82
+ - Onboarding to a new tech stack (walk an example project)
83
+ - After AI generates a multi-file feature — walk it before committing
84
+ - Teaching someone else a codebase
85
+ - Any time you feel "I accepted this but I don't fully get it"
86
+
87
+ ## When NOT to Use
88
+
89
+ - You already understand the codebase well
90
+ - Single-file scripts (just read them directly)
91
+ - Generated boilerplate with no novel logic
92
+ - Time-pressured hotfixes (use a quick `/fire-debug` instead)
93
+
94
+ ## Willison's Golden Rule
95
+
96
+ > "I won't commit any code to my repository if I couldn't explain exactly
97
+ > what it does to somebody else."
98
+
99
+ Apply this as a pre-commit gate: before every `git commit`, ask yourself if you
100
+ could explain the diff to a colleague. If not, run a walkthrough first.
101
+
102
+ ## Related Patterns
103
+
104
+ - Simon Willison's guide: simonwillison.net/guides/agentic-engineering-patterns/linear-walkthroughs/
105
+ - Interactive Explanations: simonwillison.net/guides/agentic-engineering-patterns/interactive-explanations/
106
+ - Showboat tool: github.com/simonw/showboat
107
+
108
+ ## References
109
+
110
+ - [Linear Walkthroughs — Agentic Engineering Patterns](https://simonwillison.net/guides/agentic-engineering-patterns/linear-walkthroughs/)
111
+ - [Cognitive Debt](https://simonwillison.net/2026/Feb/15/cognitive-debt/)
112
+ - [Not all AI-assisted programming is vibe coding](https://simonwillison.net/2025/Mar/19/vibe-coding/)
113
+ - [Showboat GitHub](https://github.com/simonw/showboat)
114
+ - Contributed from: dominion-flow-v2 learncoding session 2026-03-04