@ikon85/agent-workflow-kit 0.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 (273) hide show
  1. package/.agents/skills/ask-matt/SKILL.md +139 -0
  2. package/.agents/skills/ask-matt/THIRD-PARTY-NOTICES.md +29 -0
  3. package/.agents/skills/audit-skills/SKILL.md +145 -0
  4. package/.agents/skills/board-to-waves/SKILL.md +135 -0
  5. package/.agents/skills/code-review/SKILL.md +64 -0
  6. package/.agents/skills/codebase-design/DEEPENING.md +37 -0
  7. package/.agents/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
  8. package/.agents/skills/codebase-design/SKILL.md +114 -0
  9. package/.agents/skills/codebase-design/THIRD-PARTY-NOTICES.md +29 -0
  10. package/.agents/skills/codex-adapter-sync/SKILL.md +151 -0
  11. package/.agents/skills/decision-gate/SKILL.md +67 -0
  12. package/.agents/skills/diagnose/SKILL.md +136 -0
  13. package/.agents/skills/diagnose/THIRD-PARTY-NOTICES.md +29 -0
  14. package/.agents/skills/diagnose/scripts/hitl-loop.template.sh +41 -0
  15. package/.agents/skills/domain-modeling/ADR-FORMAT.md +47 -0
  16. package/.agents/skills/domain-modeling/CONTEXT-FORMAT.md +60 -0
  17. package/.agents/skills/domain-modeling/SKILL.md +76 -0
  18. package/.agents/skills/domain-modeling/THIRD-PARTY-NOTICES.md +29 -0
  19. package/.agents/skills/git-worktree-recover/SKILL.md +176 -0
  20. package/.agents/skills/grill-me/SKILL.md +54 -0
  21. package/.agents/skills/grill-me/THIRD-PARTY-NOTICES.md +29 -0
  22. package/.agents/skills/grill-with-docs/ADR-FORMAT.md +47 -0
  23. package/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md +60 -0
  24. package/.agents/skills/grill-with-docs/SKILL.md +137 -0
  25. package/.agents/skills/grill-with-docs/THIRD-PARTY-NOTICES.md +29 -0
  26. package/.agents/skills/implement/SKILL.md +15 -0
  27. package/.agents/skills/implement/THIRD-PARTY-NOTICES.md +29 -0
  28. package/.agents/skills/improve-codebase-architecture/ADR-FORMAT.md +47 -0
  29. package/.agents/skills/improve-codebase-architecture/CONTEXT-FORMAT.md +60 -0
  30. package/.agents/skills/improve-codebase-architecture/DEEPENING.md +37 -0
  31. package/.agents/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
  32. package/.agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md +46 -0
  33. package/.agents/skills/improve-codebase-architecture/LANGUAGE.md +53 -0
  34. package/.agents/skills/improve-codebase-architecture/SKILL.md +88 -0
  35. package/.agents/skills/improve-codebase-architecture/THIRD-PARTY-NOTICES.md +29 -0
  36. package/.agents/skills/kit-release/SKILL.md +56 -0
  37. package/.agents/skills/local-ci/SKILL.md +94 -0
  38. package/.agents/skills/orchestrate-wave/SKILL.md +261 -0
  39. package/.agents/skills/orchestrate-wave/references/builder-contract.md +67 -0
  40. package/.agents/skills/prototype/LOGIC.md +79 -0
  41. package/.agents/skills/prototype/SKILL.md +30 -0
  42. package/.agents/skills/prototype/THIRD-PARTY-NOTICES.md +29 -0
  43. package/.agents/skills/prototype/UI.md +112 -0
  44. package/.agents/skills/research/SKILL.md +12 -0
  45. package/.agents/skills/research/THIRD-PARTY-NOTICES.md +29 -0
  46. package/.agents/skills/resolving-merge-conflicts/SKILL.md +14 -0
  47. package/.agents/skills/resolving-merge-conflicts/THIRD-PARTY-NOTICES.md +29 -0
  48. package/.agents/skills/retro/SKILL.md +209 -0
  49. package/.agents/skills/scale-check/SKILL.md +141 -0
  50. package/.agents/skills/security-audit/SKILL.md +67 -0
  51. package/.agents/skills/setup-workflow/SKILL.md +187 -0
  52. package/.agents/skills/setup-workflow/THIRD-PARTY-NOTICES.md +29 -0
  53. package/.agents/skills/setup-workflow/board-sync.md +111 -0
  54. package/.agents/skills/setup-workflow/code-review.md +26 -0
  55. package/.agents/skills/setup-workflow/domain.md +51 -0
  56. package/.agents/skills/setup-workflow/issue-tracker-github.md +35 -0
  57. package/.agents/skills/setup-workflow/issue-tracker-gitlab.md +34 -0
  58. package/.agents/skills/setup-workflow/issue-tracker-local.md +30 -0
  59. package/.agents/skills/setup-workflow/orchestrate-wave-seed.md +44 -0
  60. package/.agents/skills/setup-workflow/spec-completeness-seed.md +44 -0
  61. package/.agents/skills/setup-workflow/spec-self-critique-seed.md +43 -0
  62. package/.agents/skills/setup-workflow/triage-labels.md +18 -0
  63. package/.agents/skills/setup-workflow/workflow-overview.md +33 -0
  64. package/.agents/skills/spec-self-critique/SKILL.md +152 -0
  65. package/.agents/skills/spec-self-critique/scenarios.md +82 -0
  66. package/.agents/skills/tdd/SKILL.md +120 -0
  67. package/.agents/skills/tdd/THIRD-PARTY-NOTICES.md +29 -0
  68. package/.agents/skills/tdd/deep-modules.md +33 -0
  69. package/.agents/skills/tdd/interface-design.md +31 -0
  70. package/.agents/skills/tdd/mocking.md +59 -0
  71. package/.agents/skills/tdd/refactoring.md +10 -0
  72. package/.agents/skills/tdd/tests.md +61 -0
  73. package/.agents/skills/to-issues/SKILL.md +325 -0
  74. package/.agents/skills/to-issues/THIRD-PARTY-NOTICES.md +29 -0
  75. package/.agents/skills/to-prd/PROGRAM-PRD-FORMAT.md +162 -0
  76. package/.agents/skills/to-prd/SKILL.md +180 -0
  77. package/.agents/skills/to-prd/THIRD-PARTY-NOTICES.md +29 -0
  78. package/.agents/skills/to-waves/SKILL.md +260 -0
  79. package/.agents/skills/to-waves/SLICE-METADATA-FORMAT.md +74 -0
  80. package/.agents/skills/triage/AGENT-BRIEF.md +168 -0
  81. package/.agents/skills/triage/OUT-OF-SCOPE.md +101 -0
  82. package/.agents/skills/triage/SKILL.md +122 -0
  83. package/.agents/skills/triage/THIRD-PARTY-NOTICES.md +29 -0
  84. package/.agents/skills/verify-spike/SKILL.md +39 -0
  85. package/.agents/skills/wayfinder/SKILL.md +127 -0
  86. package/.agents/skills/wayfinder/THIRD-PARTY-NOTICES.md +29 -0
  87. package/.agents/skills/wrapup/SKILL.md +71 -0
  88. package/.agents/skills/wrapup/SOURCES.txt +6 -0
  89. package/.agents/skills/zoom-out/SKILL.md +7 -0
  90. package/.agents/skills/zoom-out/THIRD-PARTY-NOTICES.md +29 -0
  91. package/.claude/hooks/_hook_utils.py +184 -0
  92. package/.claude/hooks/drift-guard.py +176 -0
  93. package/.claude/hooks/skill-drift-hint.py +122 -0
  94. package/.claude/hooks/sync-board-status.py +191 -0
  95. package/.claude/skills/ask-matt/SKILL.md +139 -0
  96. package/.claude/skills/ask-matt/THIRD-PARTY-NOTICES.md +29 -0
  97. package/.claude/skills/audit-skills/SKILL.md +145 -0
  98. package/.claude/skills/board-to-waves/SKILL.md +148 -0
  99. package/.claude/skills/code-review/SKILL.md +64 -0
  100. package/.claude/skills/codebase-design/DEEPENING.md +37 -0
  101. package/.claude/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
  102. package/.claude/skills/codebase-design/SKILL.md +114 -0
  103. package/.claude/skills/codebase-design/THIRD-PARTY-NOTICES.md +29 -0
  104. package/.claude/skills/codex-build/SKILL.md +126 -0
  105. package/.claude/skills/codex-build/THIRD-PARTY-NOTICES.md +35 -0
  106. package/.claude/skills/codex-review/SKILL.md +145 -0
  107. package/.claude/skills/codex-review/THIRD-PARTY-NOTICES.md +31 -0
  108. package/.claude/skills/decision-gate/SKILL.md +67 -0
  109. package/.claude/skills/diagnose/SKILL.md +136 -0
  110. package/.claude/skills/diagnose/THIRD-PARTY-NOTICES.md +29 -0
  111. package/.claude/skills/diagnose/scripts/hitl-loop.template.sh +41 -0
  112. package/.claude/skills/domain-modeling/ADR-FORMAT.md +47 -0
  113. package/.claude/skills/domain-modeling/CONTEXT-FORMAT.md +60 -0
  114. package/.claude/skills/domain-modeling/SKILL.md +76 -0
  115. package/.claude/skills/domain-modeling/THIRD-PARTY-NOTICES.md +29 -0
  116. package/.claude/skills/git-guardrails-claude-code/SKILL.md +96 -0
  117. package/.claude/skills/git-guardrails-claude-code/THIRD-PARTY-NOTICES.md +29 -0
  118. package/.claude/skills/git-guardrails-claude-code/scripts/block-dangerous-git.sh +28 -0
  119. package/.claude/skills/git-worktree-recover/SKILL.md +182 -0
  120. package/.claude/skills/grill-me/SKILL.md +54 -0
  121. package/.claude/skills/grill-me/THIRD-PARTY-NOTICES.md +29 -0
  122. package/.claude/skills/grill-me-codex/SKILL.md +158 -0
  123. package/.claude/skills/grill-me-codex/THIRD-PARTY-NOTICES.md +32 -0
  124. package/.claude/skills/grill-with-docs/ADR-FORMAT.md +47 -0
  125. package/.claude/skills/grill-with-docs/CONTEXT-FORMAT.md +60 -0
  126. package/.claude/skills/grill-with-docs/SKILL.md +137 -0
  127. package/.claude/skills/grill-with-docs/THIRD-PARTY-NOTICES.md +29 -0
  128. package/.claude/skills/grill-with-docs-codex/ADR-FORMAT.md +47 -0
  129. package/.claude/skills/grill-with-docs-codex/CONTEXT-FORMAT.md +60 -0
  130. package/.claude/skills/grill-with-docs-codex/SKILL.md +233 -0
  131. package/.claude/skills/grill-with-docs-codex/THIRD-PARTY-NOTICES.md +33 -0
  132. package/.claude/skills/implement/SKILL.md +15 -0
  133. package/.claude/skills/implement/THIRD-PARTY-NOTICES.md +29 -0
  134. package/.claude/skills/improve-codebase-architecture/ADR-FORMAT.md +47 -0
  135. package/.claude/skills/improve-codebase-architecture/CONTEXT-FORMAT.md +60 -0
  136. package/.claude/skills/improve-codebase-architecture/DEEPENING.md +37 -0
  137. package/.claude/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
  138. package/.claude/skills/improve-codebase-architecture/INTERFACE-DESIGN.md +46 -0
  139. package/.claude/skills/improve-codebase-architecture/LANGUAGE.md +53 -0
  140. package/.claude/skills/improve-codebase-architecture/SKILL.md +88 -0
  141. package/.claude/skills/improve-codebase-architecture/THIRD-PARTY-NOTICES.md +29 -0
  142. package/.claude/skills/kit-release/SKILL.md +56 -0
  143. package/.claude/skills/local-ci/SKILL.md +94 -0
  144. package/.claude/skills/orchestrate-wave/SKILL.md +269 -0
  145. package/.claude/skills/orchestrate-wave/references/builder-contract.md +67 -0
  146. package/.claude/skills/prototype/LOGIC.md +79 -0
  147. package/.claude/skills/prototype/SKILL.md +30 -0
  148. package/.claude/skills/prototype/THIRD-PARTY-NOTICES.md +29 -0
  149. package/.claude/skills/prototype/UI.md +112 -0
  150. package/.claude/skills/research/SKILL.md +12 -0
  151. package/.claude/skills/research/THIRD-PARTY-NOTICES.md +29 -0
  152. package/.claude/skills/resolving-merge-conflicts/SKILL.md +14 -0
  153. package/.claude/skills/resolving-merge-conflicts/THIRD-PARTY-NOTICES.md +29 -0
  154. package/.claude/skills/retro/SKILL.md +209 -0
  155. package/.claude/skills/scale-check/SKILL.md +141 -0
  156. package/.claude/skills/security-audit/SKILL.md +67 -0
  157. package/.claude/skills/setup-pre-commit/SKILL.md +104 -0
  158. package/.claude/skills/setup-pre-commit/scripts/pre-commit.template.sh +35 -0
  159. package/.claude/skills/setup-workflow/SKILL.md +187 -0
  160. package/.claude/skills/setup-workflow/THIRD-PARTY-NOTICES.md +29 -0
  161. package/.claude/skills/setup-workflow/board-sync.md +111 -0
  162. package/.claude/skills/setup-workflow/code-review.md +26 -0
  163. package/.claude/skills/setup-workflow/domain.md +51 -0
  164. package/.claude/skills/setup-workflow/issue-tracker-github.md +35 -0
  165. package/.claude/skills/setup-workflow/issue-tracker-gitlab.md +34 -0
  166. package/.claude/skills/setup-workflow/issue-tracker-local.md +30 -0
  167. package/.claude/skills/setup-workflow/orchestrate-wave-seed.md +44 -0
  168. package/.claude/skills/setup-workflow/spec-completeness-seed.md +44 -0
  169. package/.claude/skills/setup-workflow/spec-self-critique-seed.md +43 -0
  170. package/.claude/skills/setup-workflow/triage-labels.md +18 -0
  171. package/.claude/skills/setup-workflow/workflow-overview.md +33 -0
  172. package/.claude/skills/skill-manifest.json +389 -0
  173. package/.claude/skills/spec-self-critique/SKILL.md +152 -0
  174. package/.claude/skills/spec-self-critique/scenarios.md +82 -0
  175. package/.claude/skills/tdd/SKILL.md +120 -0
  176. package/.claude/skills/tdd/THIRD-PARTY-NOTICES.md +29 -0
  177. package/.claude/skills/tdd/deep-modules.md +33 -0
  178. package/.claude/skills/tdd/interface-design.md +31 -0
  179. package/.claude/skills/tdd/mocking.md +59 -0
  180. package/.claude/skills/tdd/refactoring.md +10 -0
  181. package/.claude/skills/tdd/tests.md +61 -0
  182. package/.claude/skills/to-issues/SKILL.md +325 -0
  183. package/.claude/skills/to-issues/THIRD-PARTY-NOTICES.md +29 -0
  184. package/.claude/skills/to-prd/PROGRAM-PRD-FORMAT.md +162 -0
  185. package/.claude/skills/to-prd/SKILL.md +180 -0
  186. package/.claude/skills/to-prd/THIRD-PARTY-NOTICES.md +29 -0
  187. package/.claude/skills/to-waves/SKILL.md +260 -0
  188. package/.claude/skills/to-waves/SLICE-METADATA-FORMAT.md +74 -0
  189. package/.claude/skills/triage/AGENT-BRIEF.md +168 -0
  190. package/.claude/skills/triage/OUT-OF-SCOPE.md +101 -0
  191. package/.claude/skills/triage/SKILL.md +122 -0
  192. package/.claude/skills/triage/THIRD-PARTY-NOTICES.md +29 -0
  193. package/.claude/skills/verify-spike/SKILL.md +39 -0
  194. package/.claude/skills/wayfinder/SKILL.md +127 -0
  195. package/.claude/skills/wayfinder/THIRD-PARTY-NOTICES.md +29 -0
  196. package/.claude/skills/wrapup/SKILL.md +81 -0
  197. package/.claude/skills/wrapup/SOURCES.txt +6 -0
  198. package/.claude/skills/write-a-skill/GLOSSARY.md +201 -0
  199. package/.claude/skills/write-a-skill/SKILL.md +88 -0
  200. package/.claude/skills/write-a-skill/THIRD-PARTY-NOTICES.md +29 -0
  201. package/.claude/skills/zoom-out/SKILL.md +7 -0
  202. package/.claude/skills/zoom-out/THIRD-PARTY-NOTICES.md +29 -0
  203. package/LICENSE +28 -0
  204. package/PROVENANCE.md +39 -0
  205. package/README.md +619 -0
  206. package/agent-workflow-kit.package.json +1939 -0
  207. package/docs/agents/board-sync.md +71 -0
  208. package/docs/agents/code-review.md +14 -0
  209. package/docs/agents/domain.md +7 -0
  210. package/docs/agents/issue-tracker.md +12 -0
  211. package/docs/agents/security-audit-runbook-template.md +205 -0
  212. package/docs/agents/skills/orchestrate-wave.md +13 -0
  213. package/docs/agents/skills/spec-self-critique.md +18 -0
  214. package/docs/agents/triage-labels.md +10 -0
  215. package/docs/agents/wave-anchor-template.md +88 -0
  216. package/docs/conventions/spec-completeness.md +23 -0
  217. package/docs/index.html +56 -0
  218. package/docs/methodology.html +488 -0
  219. package/docs/methodology.svg +93 -0
  220. package/docs/workflow.png +0 -0
  221. package/package.json +40 -0
  222. package/scripts/anchor_table.py +343 -0
  223. package/scripts/board-sync.py +1232 -0
  224. package/scripts/board_config.py +147 -0
  225. package/scripts/board_fields.py +192 -0
  226. package/scripts/build-kit.mjs +116 -0
  227. package/scripts/build-kit.test.mjs +59 -0
  228. package/scripts/check-kit-staleness.mjs +45 -0
  229. package/scripts/check-kit-staleness.test.mjs +19 -0
  230. package/scripts/execute-ready-check.py +516 -0
  231. package/scripts/issue_deps.py +79 -0
  232. package/scripts/kit-release.mjs +100 -0
  233. package/scripts/kit-release.test.mjs +67 -0
  234. package/scripts/lib/audit-refs.mjs +146 -0
  235. package/scripts/lib/scrub.mjs +113 -0
  236. package/scripts/lib/scrub.test.mjs +187 -0
  237. package/scripts/loc_offender_core.py +196 -0
  238. package/scripts/loc_offender_gate.py +182 -0
  239. package/scripts/node_kind.py +68 -0
  240. package/scripts/portability_profile_scan.py +53 -0
  241. package/scripts/pr-body-check.py +263 -0
  242. package/scripts/program_graph.py +125 -0
  243. package/scripts/program_graph_parse.py +275 -0
  244. package/scripts/program_graph_validate.py +256 -0
  245. package/scripts/program_sync.py +160 -0
  246. package/scripts/release-delta-guard.mjs +96 -0
  247. package/scripts/release-delta-guard.test.mjs +53 -0
  248. package/scripts/test_board_sync_create_idempotency.py +104 -0
  249. package/scripts/test_dist_kit_smoke.py +199 -0
  250. package/scripts/test_kit_docs_language_census.py +178 -0
  251. package/scripts/test_skill_code_review_seed.py +89 -0
  252. package/scripts/test_skill_frontmatter_lint.py +226 -0
  253. package/scripts/test_skill_gh_lint.py +124 -0
  254. package/scripts/test_skill_language_census.py +254 -0
  255. package/scripts/test_skill_portability_lint.py +773 -0
  256. package/scripts/test_skill_publish_audit.py +300 -0
  257. package/scripts/test_skill_selfcontainment_lint.py +255 -0
  258. package/scripts/test_skill_setup_workflow_seeds.py +200 -0
  259. package/scripts/test_skill_stale_name_lint.py +126 -0
  260. package/scripts/test_skill_surface_refs.py +300 -0
  261. package/scripts/test_skill_trailing_artifact_lint.py +71 -0
  262. package/scripts/wrapup-land.py +573 -0
  263. package/src/cli.mjs +70 -0
  264. package/src/commands/diff.mjs +6 -0
  265. package/src/commands/init.mjs +59 -0
  266. package/src/commands/uninstall.mjs +43 -0
  267. package/src/commands/update.mjs +95 -0
  268. package/src/lib/atomicWrite.mjs +49 -0
  269. package/src/lib/bundle.mjs +133 -0
  270. package/src/lib/hash.mjs +13 -0
  271. package/src/lib/manifest.mjs +58 -0
  272. package/src/lib/sentinel.mjs +20 -0
  273. package/src/lib/settings.mjs +23 -0
package/docs/methodology.html ADDED
@@ -0,0 +1,488 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>agent-workflow-kit — Methodology</title>
7
+ <style>
8
+ :root {
9
+ --page-bg: #F5F1E8;
10
+ --surface: #FAFAF7;
11
+ --ink: #1F2532;
12
+ --muted: #5B6579;
13
+ --border: #E8E4D8;
14
+ --accentD48;
15
+ --accent-deep: #5C5630;
16
+ --accent-light: #F4EFD9;
17
+ --baseline: #5B6579;
18
+
19
+ --program: #4A6280; --program-bg: #DDE3EC; --program-text: #2F4258;
20
+ --phase: #8A95A6; --phase-bg: #E8EBF0; --phase-text: #5B6579;
21
+ --wave: #5C7A4A; --wave-bg: #E8EDE0; --wave-text: #3D5230;
22
+ --slice: #C2902B; --slice-bg: #F2E5C7; --slice-text: #7A5B1D;
23
+ --gate: #A8432D; --gate-bg: #F2DAD0; --gate-text: #6E2B1D;
24
+ }
25
+ @media (prefers-color-scheme: dark) {
26
+ :root {
27
+ --page-bg: #1F2532; --surface: #2E3548; --ink: #F5F1E8; --muted: #A6B0BF;
28
+ --border: rgba(255,255,255,0.14); --accent: #B5A86B; --accent-deepD48;
29
+ --accent-light: #2D2A1C; --baseline: #8A95A6;
30
+
31
+ --programB2; --program-bg: #2E3850; --program-text: #8FA9C4;
32
+ --phase: #8A95A6; --phase-bg: #2A3142; --phase-text: #9CA6B5;
33
+ --wave: #82A36C; --wave-bg: #2A3A26; --wave-text: #94B57E;
34
+ --slice: #DBAC4F; --slice-bg: #3A3220; --slice-text: #DBAC4F;
35
+ --gate: #D9554F; --gate-bg: #3A2620; --gate-text: #EC8780;
36
+ }
37
+ }
38
+ :root[data-theme="dark"] {
39
+ --page-bg: #1F2532; --surface: #2E3548; --ink: #F5F1E8; --muted: #A6B0BF;
40
+ --border: rgba(255,255,255,0.14); --accent: #B5A86B; --accent-deepD48;
41
+ --accent-light: #2D2A1C; --baseline: #8A95A6;
42
+ --programB2; --program-bg: #2E3850; --program-text: #8FA9C4;
43
+ --phase: #8A95A6; --phase-bg: #2A3142; --phase-text: #9CA6B5;
44
+ --wave: #82A36C; --wave-bg: #2A3A26; --wave-text: #94B57E;
45
+ --slice: #DBAC4F; --slice-bg: #3A3220; --slice-text: #DBAC4F;
46
+ --gate: #D9554F; --gate-bg: #3A2620; --gate-text: #EC8780;
47
+ }
48
+ :root[data-theme="light"] {
49
+ --page-bg: #F5F1E8; --surface: #FAFAF7; --ink: #1F2532; --muted: #5B6579;
50
+ --border: #E8E4D8; --accentD48; --accent-deep: #5C5630;
51
+ --accent-light: #F4EFD9; --baseline: #5B6579;
52
+ --program: #4A6280; --program-bg: #DDE3EC; --program-text: #2F4258;
53
+ --phase: #8A95A6; --phase-bg: #E8EBF0; --phase-text: #5B6579;
54
+ --wave: #5C7A4A; --wave-bg: #E8EDE0; --wave-text: #3D5230;
55
+ --slice: #C2902B; --slice-bg: #F2E5C7; --slice-text: #7A5B1D;
56
+ --gate: #A8432D; --gate-bg: #F2DAD0; --gate-text: #6E2B1D;
57
+ }
58
+
59
+ * { box-sizing: border-box; }
60
+ html { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
61
+ body {
62
+ margin: 0;
63
+ background: var(--page-bg);
64
+ color: var(--ink);
65
+ font-family: Charter, "Bitstream Charter", "Iowan Old Style", Georgia, serif;
66
+ font-size: 17px;
67
+ line-height: 1.65;
68
+ overflow-x: hidden; /* the page itself never scrolls sideways */
69
+ }
70
+ .wrap { max-width: 940px; margin: 0 auto; padding: 44px 24px 96px; }
71
+
72
+ h1, h2, h3, h4, nav, .u { font-family: system-ui, "Segoe UI", -apple-system, sans-serif; }
73
+ h1 { font-size: 2.15rem; font-weight: 650; letter-spacing: -0.015em; line-height: 1.15; text-wrap: balance; margin: 0 0 10px; }
74
+ h2 { font-size: 1.4rem; font-weight: 650; letter-spacing: -0.01em; margin: 0 0 6px; }
75
+ h3 { font-size: 1.08rem; font-weight: 650; margin: 28px 0 6px; }
76
+ h4 { font-size: 0.98rem; font-weight: 650; margin: 0; }
77
+ p { margin: 0 0 1em; max-width: 70ch; }
78
+ a { color: var(--accent-deep); }
79
+ .lede { font-size: 1.12rem; color: var(--muted); max-width: 62ch; }
80
+
81
+ .eyebrow {
82
+ font-family: ui-monospace, "Cascadia Mono", Menlo, monospace;
83
+ font-size: 0.72rem; letter-spacing: 0.14em; text-transform: uppercase;
84
+ color: var(--muted); margin-bottom: 14px;
85
+ }
86
+
87
+ /* jump nav */
88
+ nav.jump { display: flex; flex-wrap: wrap; gap: 6px 16px; margin: 22px 0 8px; font-size: 0.85rem; }
89
+ nav.jump a { color: var(--muted); text-decoration: none; border-bottom: 1px dashed var(--border); padding-bottom: 1px; }
90
+ nav.jump a:hover { color: var(--accent-deep); border-color: var(--accent-deep); }
91
+
92
+ section { margin-top: 68px; }
93
+ .sec-head { display: flex; align-items: baseline; gap: 14px; margin-bottom: 6px; flex-wrap: wrap; }
94
+ .sec-num {
95
+ font-family: ui-monospace, Menlo, monospace; font-size: 0.8rem; color: var(--muted);
96
+ border: 1px solid var(--border); border-radius: 3px; padding: 1px 7px; white-space: nowrap;
97
+ }
98
+ .sec-sub { color: var(--muted); margin-bottom: 24px; max-width: 66ch; }
99
+
100
+ .term {
101
+ font-family: ui-monospace, Menlo, monospace; font-size: 0.85em;
102
+ background: var(--surface); border: 1px solid var(--border); border-radius: 4px; padding: 0 5px;
103
+ }
104
+
105
+ /* legend */
106
+ .legend { display: flex; flex-wrap: wrap; gap: 10px 18px; margin-top: 20px; }
107
+ .key { display: flex; align-items: center; gap: 7px; font-family: system-ui, sans-serif; font-size: 0.82rem; color: var(--muted); }
108
+ .dot { width: 11px; height: 11px; border-radius: 3px; background: var(--c); flex: none; }
109
+
110
+ /* ---------- Level 0: altitude ladder ---------- */
111
+ .ladder { display: flex; flex-direction: column; gap: 0; margin: 30px 0 8px; }
112
+ .rung {
113
+ display: grid; grid-template-columns: 112px 1fr auto; gap: 18px; align-items: center;
114
+ background: var(--surface); border: 1px solid var(--border); border-radius: 6px; padding: 16px 20px;
115
+ page-break-inside: avoid;
116
+ }
117
+ .rung .name { font-family: system-ui, "Segoe UI", sans-serif; font-weight: 650; color: var(--c); font-size: 1.05rem; }
118
+ .rung .name::before { content: ""; display: inline-block; width: 11px; height: 11px; border-radius: 3px; background: var(--c); margin-right: 9px; }
119
+ .rung .what { font-size: 0.95rem; color: var(--ink); }
120
+ .rung .what em { color: var(--muted); font-style: normal; }
121
+ .rung .arte { font-family: ui-monospace, Menlo, monospace; font-size: 0.72rem; color: var(--muted); text-align: right; white-space: nowrap; }
122
+ .rung-program { --c: var(--program); background: linear-gradient(to right, var(--program-bg), var(--surface) 42%); }
123
+ .rung-phase { --c: var(--phase); background: linear-gradient(to right, var(--phase-bg), var(--surface) 42%); margin-left: 32px; }
124
+ .rung-wave { --c: var(--wave); background: linear-gradient(to right, var(--wave-bg), var(--surface) 42%); margin-left: 64px; }
125
+ .rung-slice { --c: var(--slice); background: linear-gradient(to right, var(--slice-bg), var(--surface) 42%); margin-left: 96px; }
126
+ .card-join { font-family: ui-monospace, Menlo, monospace; font-size: 0.72rem; color: var(--muted); padding: 5px 0 5px 24px; }
127
+ .rung-phase + .card-join { padding-left: 56px; }
128
+ .rung-wave + .card-join { padding-left: 88px; }
129
+ .ladder-note { font-size: 0.9rem; color: var(--muted); max-width: 62ch; }
130
+
131
+ /* ---------- Level 1: routes ---------- */
132
+ .diagram-scroll { overflow-x: auto; }
133
+ .lane {
134
+ background: var(--surface); border: 1px solid var(--border); border-radius: 8px;
135
+ padding: 18px 22px 20px; margin-bottom: 16px; page-break-inside: avoid;
136
+ }
137
+ .lane.onramp { border-style: dashed; }
138
+ .lane-title { display: flex; align-items: center; gap: 10px; margin-bottom: 4px; flex-wrap: wrap; }
139
+ .lane-tag {
140
+ font-family: ui-monospace, Menlo, monospace; font-size: 0.68rem; letter-spacing: 0.08em; text-transform: uppercase;
141
+ color: var(--program-text); background: var(--program-bg); border-radius: 3px; padding: 2px 8px;
142
+ }
143
+ .lane-tag.gate { color: var(--gate-text); background: var(--gate-bg); }
144
+ .lane-tag.wave { color: var(--wave-text); background: var(--wave-bg); }
145
+ .lane-tag.slice { color: var(--slice-text); background: var(--slice-bg); }
146
+ .lane h4 { display: inline; font-size: 1rem; }
147
+ .lane p.desc { font-size: 0.92rem; color: var(--muted); margin: 6px 0 14px; max-width: 64ch; }
148
+ .chain { display: flex; flex-wrap: wrap; align-items: center; gap: 8px 4px; }
149
+ .chain.mini { gap: 6px 3px; margin: 10px 0; }
150
+ .station {
151
+ font-family: ui-monospace, Menlo, monospace; font-size: 0.8rem;
152
+ background: var(--soft, var(--page-bg)); color: var(--sc, var(--ink));
153
+ border: 1px solid var(--border); border-radius: 5px; padding: 6px 10px; white-space: nowrap;
154
+ }
155
+ .chain.mini .station { font-size: 0.74rem; padding: 4px 8px; }
156
+ .station.plain { --soft: var(--page-bg); --sc: var(--muted); font-style: italic; }
157
+ .st-program { --soft: var(--program-bg); --sc: var(--program-text); border-color: color-mix(in srgb, var(--program) 40%, var(--border)); }
158
+ .st-phase { --soft: var(--phase-bg); --sc: var(--phase-text); border-color: color-mix(in srgb, var(--phase) 40%, var(--border)); }
159
+ .st-wave { --soft: var(--wave-bg); --sc: var(--wave-text); border-color: color-mix(in srgb, var(--wave) 40%, var(--border)); }
160
+ .st-slice { --soft: var(--slice-bg); --sc: var(--slice-text); border-color: color-mix(in srgb, var(--slice) 40%, var(--border)); }
161
+ .st-gate { --soft: var(--gate-bg); --sc: var(--gate-text); border-color: color-mix(in srgb, var(--gate) 50%, var(--border)); font-weight: 600; }
162
+ .arrow { color: var(--muted); font-family: system-ui, sans-serif; font-size: 0.85rem; padding: 0 2px; user-select: none; }
163
+ .decision { font-size: 0.78rem; color: var(--muted); font-style: italic; padding: 0 4px; white-space: nowrap; }
164
+ .converge {
165
+ margin-top: 14px; padding-top: 14px; border-top: 1px dashed var(--border);
166
+ font-size: 0.92rem; color: var(--muted); max-width: 66ch;
167
+ }
168
+ .converge strong { color: var(--wave-text); font-family: system-ui, sans-serif; font-weight: 650; }
169
+ .subhead { margin: 34px 0 4px; }
170
+ .subhead h3 { margin: 0 0 4px; }
171
+
172
+ /* ---------- Level 2: mechanic stations ---------- */
173
+ details.mech {
174
+ background: var(--surface); border: 1px solid var(--border); border-radius: 7px;
175
+ margin-bottom: 12px; overflow: hidden; page-break-inside: avoid;
176
+ }
177
+ .mech .m-dot { width: 11px; height: 11px; border-radius: 3px; background: var(--mc); flex: none; }
178
+ details.mech summary {
179
+ cursor: pointer; display: flex; align-items: center; gap: 12px; padding: 14px 18px;
180
+ list-style: none; font-family: system-ui, "Segoe UI", sans-serif;
181
+ }
182
+ details.mech summary::-webkit-details-marker { display: none; }
183
+ details.mech summary:focus-visible { outline: 2px solid var(--mc); outline-offset: -2px; }
184
+ .mech .m-title { font-weight: 650; font-size: 0.98rem; }
185
+ .mech .m-hint { color: var(--muted); font-size: 0.85rem; margin-left: auto; text-align: right; }
186
+ .mech .m-caret { color: var(--muted); transition: transform 0.15s; font-size: 0.8rem; }
187
+ details[open] .m-caret { transform: rotate(90deg); }
188
+ @media (prefers-reduced-motion: reduce) { .mech .m-caret { transition: none; } }
189
+ .mech .m-body { padding: 2px 20px 18px; border-top: 1px solid var(--border); }
190
+ .mech .m-body p { font-size: 0.95rem; }
191
+ .mech-program { --mc: var(--program); }
192
+ .mech-phase { --mc: var(--phase); }
193
+ .mech-wave { --mc: var(--wave); }
194
+ .mech-slice { --mc: var(--slice); }
195
+ .mech-gate { --mc: var(--gate); }
196
+ .plain { background: var(--page-bg); border-radius: 5px; padding: 10px 14px; margin: 12px 0; font-size: 0.92rem; }
197
+ .plain b { font-family: system-ui, sans-serif; font-weight: 650; font-size: 0.78rem; letter-spacing: 0.04em; color: var(--muted); }
198
+
199
+ footer { margin-top: 72px; padding-top: 20px; border-top: 1px solid var(--border); font-size: 0.85rem; color: var(--muted); }
200
+
201
+ @media print {
202
+ body { font-size: 12.5px; }
203
+ nav.jump { display: none; }
204
+ .mech .m-body { display: block !important; } /* every station reads fully on paper */
205
+ .mech .m-caret { display: none; }
206
+ a { color: inherit; text-decoration: none; }
207
+ }
208
+ @media (max-width: 640px) {
209
+ .rung { grid-template-columns: 1fr; gap: 4px; padding: 13px 16px; }
210
+ .rung .arte { text-align: left; }
211
+ .rung-phase { margin-left: 12px; } .rung-wave { margin-left: 24px; } .rung-slice { margin-left: 36px; }
212
+ .card-join, .rung-phase + .card-join, .rung-wave + .card-join { padding-left: 16px; }
213
+ .mech .m-hint { display: none; }
214
+ }
215
+ </style>
216
+ </head>
217
+ <body>
218
+ <div class="wrap">
219
+ <div class="eyebrow">agent-workflow-kit · methodology</div>
220
+ <h1>Plan big things without losing the small ones</h1>
221
+ <p class="lede">The kit plans work at four altitudes and moves it through the same four phases every time — plan, execute, land, learn. Every altitude answers one question, produces one artifact, and hands a well-defined object to the level below, so a one-line idea and a ten-wave build program travel the same road.</p>
222
+
223
+ <nav class="jump" aria-label="Page sections">
224
+ <a href="#level-0">Level 0 — The altitude model</a>
225
+ <a href="#level-1">Level 1 — The route map</a>
226
+ <a href="#level-2">Level 2 — How it stays honest</a>
227
+ </nav>
228
+
229
+ <div class="legend">
230
+ <span class="key"><span class="dot" style="--c: var(--program)"></span> Program</span>
231
+ <span class="key"><span class="dot" style="--c: var(--phase)"></span> Phase</span>
232
+ <span class="key"><span class="dot" style="--c: var(--wave)"></span> Wave</span>
233
+ <span class="key"><span class="dot" style="--c: var(--slice)"></span> Slice</span>
234
+ <span class="key"><span class="dot" style="--c: var(--gate)"></span> Gate / checkpoint</span>
235
+ </div>
236
+
237
+ <!-- ================= LEVEL 0 ================= -->
238
+ <section id="level-0">
239
+ <div class="sec-head"><span class="sec-num">Level 0</span><h2>The altitude model</h2></div>
240
+ <p class="sec-sub">Four sizes of intent, one containment chain. Nothing here is a new tool — each rung is an <span class="term">issue</span> (a tracked unit of work in your issue tracker) or a field on one, with a fixed template. Colour follows altitude on every diagram on this page: the same blue-grey always means Program, the same amber always means Slice.</p>
241
+
242
+ <div class="ladder">
243
+ <div class="rung rung-program">
244
+ <span class="name">Program</span>
245
+ <span class="what">The whole undertaking. <em>Described once, in one Program document with a wave plan attached.</em></span>
246
+ <span class="arte">issue · type:program</span>
247
+ </div>
248
+ <div class="card-join">contains 1 : n</div>
249
+ <div class="rung rung-phase">
250
+ <span class="name">Phase</span>
251
+ <span class="what">An acceptance bracket around a handful of waves. <em>A board field and a checklist line — never its own issue. Optional.</em></span>
252
+ <span class="arte">board field · P1 / P2 / …</span>
253
+ </div>
254
+ <div class="card-join">brackets 1 : a few</div>
255
+ <div class="rung rung-wave">
256
+ <span class="name">Wave</span>
257
+ <span class="what">The working unit: one outcome, a small set of slices, one gate. <em>Unchanged — exactly the wave you already build today.</em></span>
258
+ <span class="arte">anchor issue · Wave N</span>
259
+ </div>
260
+ <div class="card-join">ships as 1 : a few</div>
261
+ <div class="rung rung-slice">
262
+ <span class="name">Slice</span>
263
+ <span class="what">One build session, one pull request, one visible result.</span>
264
+ <span class="arte">sub-issue · one PR</span>
265
+ </div>
266
+ </div>
267
+ <p class="ladder-note">Phase is the only optional rung — plenty of programs run without one, and every feature that never needed a Program at all still ends at the same Wave → Slice bottom two rungs.</p>
268
+ </section>
269
+
270
+ <!-- ================= LEVEL 1 ================= -->
271
+ <section id="level-1">
272
+ <div class="sec-head"><span class="sec-num">Level 1</span><h2>The route map</h2></div>
273
+ <p class="sec-sub">There is no single front door. Work enters wherever it actually starts, and every door funnels toward the same shape. Below are the two roads that lead there — the everyday route almost everything takes, and the road for work too big to fit in one wave.</p>
274
+
275
+ <div class="subhead"><h3>1a — One shape, many doors</h3></div>
276
+ <p class="desc" style="max-width:68ch">A vague idea, a plan you already wrote, a backlog, or a raw <span class="term">issue</span> — every entry funnels into the same shaped artefact: a <span class="term">PRD</span> (a short planning document — Product Requirements Document) that, once sliced, becomes either one atomic issue or a <span class="term">wave anchor</span> (a tracking issue with linked child slices). Grilling — a relentless interview that sharpens a fuzzy idea into a clear requirement — is optional and scales with the stakes.</p>
277
+
278
+ <div class="lane" style="margin-bottom:22px;">
279
+ <div class="diagram-scroll">
280
+ <div class="chain">
281
+ <span class="station plain">idea</span><span class="arrow">/</span>
282
+ <span class="station plain">plan</span><span class="arrow">/</span>
283
+ <span class="station plain">backlog</span><span class="arrow">/</span>
284
+ <span class="station plain">issue</span><span class="arrow">→</span>
285
+ <span class="station st-wave">grill-with-docs</span><span class="arrow">→</span>
286
+ <span class="station st-wave">to-prd</span><span class="arrow">→</span>
287
+ <span class="station st-wave">to-issues</span>
288
+ <span class="decision">(1 slice → atomic issue · several → wave anchor)</span><span class="arrow">→</span>
289
+ <span class="station st-gate">gate — verify-spike / decision-gate</span>
290
+ <span class="decision">(only if a slice hinges on an unknown)</span><span class="arrow">→</span>
291
+ <span class="station st-slice">tdd</span><span class="arrow">→</span>
292
+ <span class="station st-slice">wrapup</span><span class="arrow">→</span>
293
+ <span class="station st-program">retro</span>
294
+ </div>
295
+ </div>
296
+ <p class="converge" style="margin-top:12px;border-top:none;padding-top:0;">Sharpen only as deep as the work deserves: skip the grill for a mechanical change, run it lightly for a normal feature, escalate to a cross-model review for something hard to reverse. You approve the slice breakdown before anything is published — this funnel never writes to the board behind your back.</p>
297
+ </div>
298
+
299
+ <div class="lane onramp">
300
+ <div class="lane-title"><span class="lane-tag slice">on-ramp</span><h4>Work that doesn't start as an idea</h4></div>
301
+ <p class="desc">Two doors sit outside the planning funnel and feed straight into the build layer instead:</p>
302
+ <div class="chain mini">
303
+ <span class="station plain">bugs / requests piling up</span><span class="arrow">→</span>
304
+ <span class="station st-slice">triage</span><span class="arrow">→</span>
305
+ <span class="station st-wave">to-issues</span>
306
+ </div>
307
+ <div class="chain mini">
308
+ <span class="station plain">something's broken</span><span class="arrow">→</span>
309
+ <span class="station st-slice">diagnose</span>
310
+ <span class="decision">(reproduce → isolate → fix → prove)</span><span class="arrow">→</span>
311
+ <span class="station st-slice">tdd</span>
312
+ </div>
313
+ </div>
314
+
315
+ <div class="subhead"><h3>1b — When the work outgrows one wave</h3></div>
316
+ <p class="desc" style="max-width:68ch">The Program route is <strong>one strand</strong> within this map, not a separate system: it plans several waves at once, then hands each one down into the exact same build → land → learn spine as 1a. Use it only when the size is genuinely unclear — a new build, a big cross-cutting change, several independently-shippable stages.</p>
317
+
318
+ <div class="lane" style="--c: var(--program)">
319
+ <div class="lane-title"><span class="lane-tag">top-down</span><h4>You know it's big</h4></div>
320
+ <p class="desc"><span class="term">scale-check</span> asks a handful of plain-language questions and names the size. A big undertaking gets grilled once, written down once as a Program document with a wave plan attached, and unfolded into named, numbered waves — bracketed by phases where the program has real acceptance stages — after you approve a full preview in chat.</p>
321
+ <div class="diagram-scroll">
322
+ <div class="chain">
323
+ <span class="station st-program">scale-check</span><span class="arrow">→</span>
324
+ <span class="station st-program">grill</span><span class="arrow">→</span>
325
+ <span class="station st-program">Program document</span><span class="arrow">→</span>
326
+ <span class="station st-gate">preview gate</span><span class="arrow">→</span>
327
+ <span class="station st-wave">to-waves</span><span class="arrow">→</span>
328
+ <span class="station st-phase">phases stamped</span><span class="arrow">+</span>
329
+ <span class="station st-wave">Wave 1…n + slices</span>
330
+ </div>
331
+ </div>
332
+ </div>
333
+
334
+ <div class="lane" style="--c: var(--wave)">
335
+ <div class="lane-title"><span class="lane-tag wave">execution rhythm</span><h4>Then the rhythm takes over</h4></div>
336
+ <p class="desc">Waves are built in plan order, one at a time — through the identical <span class="term">tdd</span> → <span class="term">wrapup</span> → <span class="term">retro</span> spine as 1a. Every wave ends at its own outcome gate; when the last wave of a phase lands, the matching phase gate is ticked on the Program document. The program issue closes last, by hand, once everything under it is done.</p>
337
+ <div class="diagram-scroll">
338
+ <div class="chain">
339
+ <span class="station st-wave">build Wave n</span><span class="arrow">→</span>
340
+ <span class="station st-gate">wave gate</span><span class="arrow">→</span>
341
+ <span class="station st-wave">next wave…</span><span class="arrow">→</span>
342
+ <span class="station st-gate">phase gate P1 ✓</span><span class="arrow">→</span>
343
+ <span class="station st-program">program Done</span>
344
+ </div>
345
+ </div>
346
+ </div>
347
+
348
+ <div class="lane" style="--c: var(--slice)">
349
+ <div class="lane-title"><span class="lane-tag slice">bottom-up</span><h4>It grew on the board</h4></div>
350
+ <p class="desc">Loose issues cluster into wave candidates. A candidate is not a commitment — it gets a real number only when you promote it. If a cluster of candidates starts looking like a program on its own, the kit says so and escalates instead of spraying out more small stubs.</p>
351
+ <div class="diagram-scroll">
352
+ <div class="chain">
353
+ <span class="station st-slice">board issues</span><span class="arrow">→</span>
354
+ <span class="station st-slice">board-to-waves</span><span class="arrow">→</span>
355
+ <span class="station st-wave">wave stub</span>
356
+ <span class="decision">(a placeholder issue reserving a wave's number)</span><span class="arrow">→</span>
357
+ <span class="station st-gate">your call</span><span class="arrow">→</span>
358
+ <span class="station st-wave">promote</span>
359
+ </div>
360
+ </div>
361
+ <div class="converge">Both routes meet here: <strong>one wave anchor, a few slice sub-issues, one outcome gate</strong> — built, verified, and landed slice by slice, exactly like every wave always has been.</div>
362
+ </div>
363
+ </section>
364
+
365
+ <!-- ================= LEVEL 2 ================= -->
366
+ <section id="level-2">
367
+ <div class="sec-head"><span class="sec-num">Level 2</span><h2>How it stays honest</h2></div>
368
+ <p class="sec-sub">Six mechanics carry the promises above. Each folds open into the detail that backs the one-sentence claim next to it.</p>
369
+
370
+ <details class="mech mech-gate">
371
+ <summary>
372
+ <span class="m-caret">▶</span><span class="m-dot"></span>
373
+ <span class="m-title">Gates — a decision lives at the level it can still change</span>
374
+ <span class="m-hint">placement rule</span>
375
+ </summary>
376
+ <div class="m-body">
377
+ <div class="chain mini">
378
+ <span class="station st-program">Program / Wave shape</span><span class="arrow">→</span>
379
+ <span class="station plain">settled during the grill</span>
380
+ </div>
381
+ <div class="chain mini">
382
+ <span class="station st-slice">a single slice hinges on an unknown</span><span class="arrow">→</span>
383
+ <span class="station st-gate">verify-spike / decision-gate</span><span class="arrow">→</span>
384
+ <span class="station st-slice">tdd</span>
385
+ </div>
386
+ <div class="plain"><b>IN PLAIN TERMS</b><br>Big decisions get made where they can still reshape everything; small decisions ride along with only the one slice they affect.</div>
387
+ <p>A gate slice does read-only research — it never writes code — and is sequenced before the build slice it blocks, so the build never waits on a moving target. A call that's genuinely hard to reverse escalates one step further, to a cross-model review, before it locks in.</p>
388
+ </div>
389
+ </details>
390
+
391
+ <details class="mech mech-wave">
392
+ <summary>
393
+ <span class="m-caret">▶</span><span class="m-dot"></span>
394
+ <span class="m-title">Late binding — a wave's content is written just before it starts</span>
395
+ <span class="m-hint">to-prd Mode B · self-critique</span>
396
+ </summary>
397
+ <div class="m-body">
398
+ <div class="chain mini">
399
+ <span class="station st-program">Program document</span>
400
+ <span class="decision">(wave headlines, months ahead)</span><span class="arrow">→</span>
401
+ <span class="station st-wave">wave stub</span>
402
+ <span class="decision">(name + slice skeleton only)</span><span class="arrow">→</span>
403
+ <span class="station st-wave">fresh write-up</span>
404
+ <span class="decision">(the week the wave starts)</span>
405
+ </div>
406
+ <div class="plain"><b>IN PLAIN TERMS</b><br>You never build from a stale spec — the plan names the destination early; the route is drawn right before you set off.</div>
407
+ <p>The wave's actual scope and acceptance criteria are authored fresh at start time, using everything learned since the plan was written. A self-critique pass runs on that write-up before anyone approves it, and a wave already known to be high-stakes gets a deeper pass than a routine one.</p>
408
+ </div>
409
+ </details>
410
+
411
+ <details class="mech mech-program">
412
+ <summary>
413
+ <span class="m-caret">▶</span><span class="m-dot"></span>
414
+ <span class="m-title">Drift propagation — what one wave learns reaches the others</span>
415
+ <span class="m-hint">append-only · never silent</span>
416
+ </summary>
417
+ <div class="m-body">
418
+ <div class="chain mini">
419
+ <span class="station st-wave">Wave 3 — an assumption flips</span><span class="arrow">→</span>
420
+ <span class="station st-wave">Wave 7 (note waiting)</span><span class="arrow">+</span>
421
+ <span class="station st-program">Program document (note waiting)</span>
422
+ </div>
423
+ <div class="plain"><b>IN PLAIN TERMS</b><br>A discovery in an early wave doesn't wait for someone to remember it later — it's already sitting there as a note when the later wave opens.</div>
424
+ <p>Notes are appended, never rewritten into a plan's tables. Only a genuine change to the wave plan itself — a wave added, scope moved between waves — takes the slower, structural path in the next mechanic. A wave's outcome gate is not considered cleared until any drift addressed to it has been read.</p>
425
+ </div>
426
+ </details>
427
+
428
+ <details class="mech mech-phase">
429
+ <summary>
430
+ <span class="m-caret">▶</span><span class="m-dot"></span>
431
+ <span class="m-title">Revision loop — a stale stub stops loudly instead of building quietly wrong</span>
432
+ <span class="m-hint">program-revision marker</span>
433
+ </summary>
434
+ <div class="m-body">
435
+ <div class="chain mini">
436
+ <span class="station st-wave">wave stub — stamped r1</span><span class="arrow">vs.</span>
437
+ <span class="station st-program">plan revised → r2</span><span class="arrow">→</span>
438
+ <span class="station st-gate">stop: refresh before building</span>
439
+ </div>
440
+ <div class="plain"><b>IN PLAIN TERMS</b><br>If the plan changed after a stub was written, the kit stops you before you build the outdated version, instead of you finding out later.</div>
441
+ <p>Every wave stub is stamped with the Program document's revision number the day it's created. Revising the plan after that — inserting a wave, moving a scope item — re-unfolds only the difference (new waves added, existing ones matched, orphans flagged) and re-stamps every stub the change actually touches, so the marker and the plan agree again.</p>
442
+ </div>
443
+ </details>
444
+
445
+ <details class="mech mech-wave">
446
+ <summary>
447
+ <span class="m-caret">▶</span><span class="m-dot"></span>
448
+ <span class="m-title">program-sync — the plan is a living table, not a snapshot</span>
449
+ <span class="m-hint">status only · never rewinds</span>
450
+ </summary>
451
+ <div class="m-body">
452
+ <div class="chain mini">
453
+ <span class="station st-slice">board — real status</span><span class="arrow">→</span>
454
+ <span class="station st-wave">sync</span><span class="arrow">→</span>
455
+ <span class="station st-program">wave-plan table — status column</span>
456
+ </div>
457
+ <div class="plain"><b>IN PLAIN TERMS</b><br>The plan document updates its own status column from what actually happened on the board, instead of drifting out of sync with a hand-typed guess.</div>
458
+ <p>Only the status column is regenerated, and only forward — a wave already marked done never reverts to open. The plan's own columns and any handwritten notes are left exactly as written. A dry run shows the change before anything is written, the same discipline the kit already uses to keep a wave anchor's slice table current.</p>
459
+ </div>
460
+ </details>
461
+
462
+ <details class="mech mech-slice">
463
+ <summary>
464
+ <span class="m-caret">▶</span><span class="m-dot"></span>
465
+ <span class="m-title">Completeness — counted, not remembered</span>
466
+ <span class="m-hint">coverage X of Y</span>
467
+ </summary>
468
+ <div class="m-body">
469
+ <div class="chain mini">
470
+ <span class="station st-slice">scope items S1…Sn</span><span class="arrow">→</span>
471
+ <span class="station st-wave">carried by ≥1 wave? <em style="font-style:normal;color:var(--muted)">[count]</em></span>
472
+ </div>
473
+ <div class="chain mini">
474
+ <span class="station st-wave">wave → slice → gate</span><span class="arrow">→</span>
475
+ <span class="station st-gate">chain closes without a gap? <em style="font-style:normal;color:var(--muted)">[count]</em></span>
476
+ </div>
477
+ <div class="plain"><b>IN PLAIN TERMS</b><br>Nobody has to remember whether everything is covered — the tool counts it and shows the number before anyone approves.</div>
478
+ <p>Both counts appear at the same zero-write preview gate that shows the whole wave plan: how many scope items are carried by a wave (coverage), and whether every wave's chain down to a gated slice closes without a gap (rollup). Nothing is written to the board until both counts are shown and approved — the preview reads the plan, it never touches it.</p>
479
+ </div>
480
+ </details>
481
+ </section>
482
+
483
+ <footer>
484
+ Every rung, route, and mechanic on this page maps to a real skill or script shipped in this kit — see the README for how to install and run them.
485
+ </footer>
486
+ </div>
487
+ </body>
488
+ </html>
package/docs/methodology.svg ADDED
@@ -0,0 +1,93 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <svg viewBox="0 0 960 680" xmlns="http://www.w3.org/2000/svg" role="img" font-family="Segoe UI, Helvetica, Arial, sans-serif">
3
+ <title>agent-workflow-kit methodology: the Program to Phase to Wave to Slice altitude ladder, and the two routes (a planned top-down Program route and a grown bottom-up board route) that both fund the same Wave-and-Slices build spine.</title>
4
+ <defs>
5
+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
6
+ <path d="M0,0 L10,5 L0,10 z" fill="#8A95A6"/>
7
+ </marker>
8
+ </defs>
9
+
10
+ <!-- canvas -->
11
+ <rect x="0" y="0" width="960" height="680" rx="16" fill="#1F2532"/>
12
+
13
+ <!-- header -->
14
+ <text x="40" y="36" font-size="12" letter-spacing="2" fill="#8A95A6">AGENT-WORKFLOW-KIT · METHODOLOGY</text>
15
+
16
+ <!-- ===================== Level 0 — altitude ladder ===================== -->
17
+ <text x="40" y="62" font-size="13" fill="#A6B0BF">Level 0 — one containment chain, four altitudes</text>
18
+
19
+ <!-- Program -->
20
+ <rect x="40" y="72" width="880" height="46" rx="7" fill="#2E3850"/>
21
+ <rect x="40" y="72" width="6" height="46" rx="3" fill="B2"/>
22
+ <text x="62" y="100" font-size="16" font-weight="700" fill="#8FA9C4">Program</text>
23
+ <text x="180" y="100" font-size="13.5" fill="#A6B0BF">The whole undertaking — one document, one wave plan.</text>
24
+ <text x="880" y="100" font-size="11" fill="#8A95A6" text-anchor="end">issue · type:program</text>
25
+
26
+ <!-- Phase -->
27
+ <rect x="76" y="130" width="808" height="46" rx="7" fill="#2A3142"/>
28
+ <rect x="76" y="130" width="6" height="46" rx="3" fill="#8A95A6"/>
29
+ <text x="98" y="158" font-size="16" font-weight="700" fill="#9CA6B5">Phase</text>
30
+ <text x="200" y="158" font-size="13.5" fill="#A6B0BF">An acceptance bracket around a few waves. Optional.</text>
31
+ <text x="884" y="158" font-size="11" fill="#8A95A6" text-anchor="end">board field</text>
32
+
33
+ <!-- Wave -->
34
+ <rect x="112" y="188" width="736" height="46" rx="7" fill="#2A3A26"/>
35
+ <rect x="112" y="188" width="6" height="46" rx="3" fill="#82A36C"/>
36
+ <text x="134" y="216" font-size="16" font-weight="700" fill="#94B57E">Wave</text>
37
+ <text x="222" y="216" font-size="13.5" fill="#A6B0BF">One outcome, a few slices, one gate — unchanged.</text>
38
+ <text x="848" y="216" font-size="11" fill="#8A95A6" text-anchor="end">anchor issue</text>
39
+
40
+ <!-- Slice -->
41
+ <rect x="148" y="246" width="664" height="46" rx="7" fill="#3A3220"/>
42
+ <rect x="148" y="246" width="6" height="46" rx="3" fill="#DBAC4F"/>
43
+ <text x="170" y="274" font-size="16" font-weight="700" fill="#DBAC4F">Slice</text>
44
+ <text x="258" y="274" font-size="13.5" fill="#A6B0BF">One build session, one pull request, one result.</text>
45
+ <text x="812" y="274" font-size="11" fill="#8A95A6" text-anchor="end">sub-issue · one PR</text>
46
+
47
+ <!-- ===================== Level 1 — two roads, one spine ===================== -->
48
+ <text x="40" y="332" font-size="13" fill="#A6B0BF">Level 1 — two roads fund the same build spine</text>
49
+
50
+ <!-- top branch: planned top-down -->
51
+ <rect x="350" y="350" width="260" height="40" rx="7" fill="#2E3850" stroke="B2" stroke-width="1.2"/>
52
+ <text x="480" y="375" font-size="12.5" fill="#8FA9C4" text-anchor="middle">scale-check → grill → to-waves</text>
53
+ <line x1="480" y1="390" x2="553" y2="430" stroke="#8A95A6" stroke-width="1.4" marker-end="url(#arrow)"/>
54
+
55
+ <!-- main spine -->
56
+ <g font-size="13">
57
+ <rect x="40" y="432" width="150" height="56" rx="7" fill="#2E3548" stroke="#3C4356"/>
58
+ <text x="115" y="465" fill="#A6B0BF" text-anchor="middle">idea · plan · issue</text>
59
+
60
+ <text x="202" y="465" fill="#8A95A6" text-anchor="middle" font-size="16">→</text>
61
+
62
+ <rect x="214" y="432" width="230" height="56" rx="7" fill="#2A3A26" stroke="#82A36C"/>
63
+ <text x="329" y="460" fill="#94B57E" text-anchor="middle">grill-with-docs → to-prd</text>
64
+ <text x="329" y="477" fill="#94B57E" text-anchor="middle">→ to-issues</text>
65
+
66
+ <text x="456" y="465" fill="#8A95A6" text-anchor="middle" font-size="16">→</text>
67
+
68
+ <rect x="468" y="425" width="170" height="70" rx="8" fill="#2A3A26" stroke="#94B57E" stroke-width="2"/>
69
+ <text x="553" y="455" fill="#94B57E" text-anchor="middle" font-weight="700">Wave</text>
70
+ <text x="553" y="475" fill="#94B57E" text-anchor="middle" font-weight="700">+ Slices</text>
71
+
72
+ <text x="650" y="465" fill="#8A95A6" text-anchor="middle" font-size="16">→</text>
73
+
74
+ <rect x="662" y="432" width="90" height="56" rx="7" fill="#3A3220" stroke="#DBAC4F"/>
75
+ <text x="707" y="465" fill="#DBAC4F" text-anchor="middle">tdd</text>
76
+
77
+ <text x="764" y="465" fill="#8A95A6" text-anchor="middle" font-size="16">→</text>
78
+
79
+ <rect x="776" y="432" width="150" height="56" rx="7" fill="#2E3548" stroke="#3C4356"/>
80
+ <text x="851" y="460" fill="#A6B0BF" text-anchor="middle">wrapup</text>
81
+ <text x="851" y="477" fill="#A6B0BF" text-anchor="middle">→ retro</text>
82
+ </g>
83
+
84
+ <!-- bottom branch: grown bottom-up -->
85
+ <line x1="480" y1="560" x2="553" y2="493" stroke="#8A95A6" stroke-width="1.4" marker-end="url(#arrow)"/>
86
+ <rect x="350" y="560" width="260" height="40" rx="7" fill="#3A3220" stroke="#DBAC4F" stroke-width="1.2"/>
87
+ <text x="480" y="585" font-size="12.5" fill="#DBAC4F" text-anchor="middle">board-to-waves → promote</text>
88
+
89
+ <!-- footer captions -->
90
+ <text x="40" y="628" font-size="12" fill="#8A95A6">Top: a Program plans several waves at once, gated by a chat preview before anything is written.</text>
91
+ <text x="40" y="648" font-size="12" fill="#8A95A6">Bottom: loose board issues cluster into a wave candidate and get a number only when promoted.</text>
92
+ <text x="40" y="668" font-size="12" fill="#8A95A6">Either way, the same Wave + Slices lands through the identical tdd → wrapup → retro spine.</text>
93
+ </svg>
package/docs/workflow.png ADDED
Binary file
package/package.json ADDED
@@ -0,0 +1,40 @@
1
+ {
2
+ "name": "@ikon85/agent-workflow-kit",
3
+ "version": "0.10.0",
4
+ "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
5
+ "type": "module",
6
+ "bin": {
7
+ "agent-workflow-kit": "src/cli.mjs"
8
+ },
9
+ "scripts": {
10
+ "test": "npm run test:node && npm run test:python",
11
+ "test:node": "node --test",
12
+ "test:python": "python3 -m unittest discover -s scripts -p 'test_*.py'",
13
+ "kit:build": "node scripts/build-kit.mjs",
14
+ "kit:staleness": "node scripts/check-kit-staleness.mjs",
15
+ "release:prepare": "node scripts/kit-release.mjs",
16
+ "release:guard": "node scripts/release-delta-guard.mjs"
17
+ },
18
+ "files": [
19
+ ".claude/",
20
+ ".agents/",
21
+ "scripts/",
22
+ "docs/",
23
+ "src/",
24
+ "agent-workflow-kit.package.json",
25
+ "LICENSE",
26
+ "README.md",
27
+ "PROVENANCE.md"
28
+ ],
29
+ "license": "MIT",
30
+ "repository": {
31
+ "type": "git",
32
+ "url": "git+https://github.com/iKon85/agent-workflow-kit.git"
33
+ },
34
+ "engines": {
35
+ "node": ">=20"
36
+ },
37
+ "dependencies": {
38
+ "@clack/prompts": "^0.7.0"
39
+ }
40
+ }