@vpxa/aikit 0.1.74 → 0.1.75

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 (134) hide show
  1. package/package.json +6 -1
  2. package/packages/cli/dist/index.js +2 -2
  3. package/packages/cli/dist/{init-DQkar6Es.js → init-CuRXmyD9.js} +1 -1
  4. package/packages/cli/dist/scaffold-WMQ2uQ48.js +2 -0
  5. package/packages/cli/dist/{user-CopNWxHP.js → user-vbJwa7x2.js} +1 -1
  6. package/scaffold/dist/adapters/claude-code.mjs +4 -0
  7. package/scaffold/dist/adapters/copilot.mjs +75 -0
  8. package/scaffold/dist/adapters/flows.mjs +1 -0
  9. package/scaffold/dist/adapters/skills.mjs +1 -0
  10. package/scaffold/{compiled → dist/compiled}/flows-data.mjs +304 -446
  11. package/scaffold/{compiled → dist/compiled}/skills-data.mjs +554 -2281
  12. package/scaffold/dist/definitions/agents.mjs +9 -0
  13. package/scaffold/{definitions → dist/definitions}/bodies.mjs +6 -229
  14. package/scaffold/dist/definitions/exclusions.mjs +1 -0
  15. package/scaffold/dist/definitions/hooks.mjs +1 -0
  16. package/scaffold/dist/definitions/models.mjs +1 -0
  17. package/scaffold/dist/definitions/plugins.mjs +1 -0
  18. package/scaffold/{definitions → dist/definitions}/prompts.mjs +9 -149
  19. package/scaffold/{definitions → dist/definitions}/protocols.mjs +9 -37
  20. package/scaffold/dist/definitions/tools.mjs +1 -0
  21. package/packages/cli/dist/scaffold-ukCDW3wQ.js +0 -2
  22. package/scaffold/_preview/agents/Architect-Reviewer-Alpha.agent.md +0 -132
  23. package/scaffold/_preview/agents/Architect-Reviewer-Beta.agent.md +0 -132
  24. package/scaffold/_preview/agents/Code-Reviewer-Alpha.agent.md +0 -112
  25. package/scaffold/_preview/agents/Code-Reviewer-Beta.agent.md +0 -112
  26. package/scaffold/_preview/agents/Debugger.agent.md +0 -412
  27. package/scaffold/_preview/agents/Documenter.agent.md +0 -468
  28. package/scaffold/_preview/agents/Explorer.agent.md +0 -76
  29. package/scaffold/_preview/agents/Frontend.agent.md +0 -440
  30. package/scaffold/_preview/agents/Implementer.agent.md +0 -425
  31. package/scaffold/_preview/agents/Orchestrator.agent.md +0 -452
  32. package/scaffold/_preview/agents/Planner.agent.md +0 -481
  33. package/scaffold/_preview/agents/README.md +0 -57
  34. package/scaffold/_preview/agents/Refactor.agent.md +0 -435
  35. package/scaffold/_preview/agents/Researcher-Alpha.agent.md +0 -151
  36. package/scaffold/_preview/agents/Researcher-Beta.agent.md +0 -152
  37. package/scaffold/_preview/agents/Researcher-Delta.agent.md +0 -153
  38. package/scaffold/_preview/agents/Researcher-Gamma.agent.md +0 -152
  39. package/scaffold/_preview/agents/Security.agent.md +0 -433
  40. package/scaffold/_preview/agents/_shared/architect-reviewer-base.md +0 -104
  41. package/scaffold/_preview/agents/_shared/code-agent-base.md +0 -366
  42. package/scaffold/_preview/agents/_shared/code-reviewer-base.md +0 -87
  43. package/scaffold/_preview/agents/_shared/decision-protocol.md +0 -27
  44. package/scaffold/_preview/agents/_shared/forge-protocol.md +0 -90
  45. package/scaffold/_preview/agents/_shared/researcher-base.md +0 -114
  46. package/scaffold/_preview/agents/templates/adr-template.md +0 -28
  47. package/scaffold/_preview/agents/templates/execution-state.md +0 -26
  48. package/scaffold/_preview/flows/_epilogue/steps/docs-sync/README.md +0 -120
  49. package/scaffold/_preview/flows/aikit-advanced/README.md +0 -70
  50. package/scaffold/_preview/flows/aikit-advanced/steps/design/README.md +0 -178
  51. package/scaffold/_preview/flows/aikit-advanced/steps/execute/README.md +0 -145
  52. package/scaffold/_preview/flows/aikit-advanced/steps/plan/README.md +0 -122
  53. package/scaffold/_preview/flows/aikit-advanced/steps/spec/README.md +0 -121
  54. package/scaffold/_preview/flows/aikit-advanced/steps/task/README.md +0 -119
  55. package/scaffold/_preview/flows/aikit-advanced/steps/verify/README.md +0 -145
  56. package/scaffold/_preview/flows/aikit-basic/README.md +0 -51
  57. package/scaffold/_preview/flows/aikit-basic/steps/assess/README.md +0 -109
  58. package/scaffold/_preview/flows/aikit-basic/steps/design/README.md +0 -116
  59. package/scaffold/_preview/flows/aikit-basic/steps/implement/README.md +0 -131
  60. package/scaffold/_preview/flows/aikit-basic/steps/verify/README.md +0 -123
  61. package/scaffold/_preview/prompts/aikit-ask.prompt.md +0 -13
  62. package/scaffold/_preview/prompts/aikit-debug.prompt.md +0 -15
  63. package/scaffold/_preview/prompts/aikit-design.prompt.md +0 -15
  64. package/scaffold/_preview/prompts/aikit-flow-add.prompt.md +0 -84
  65. package/scaffold/_preview/prompts/aikit-flow-create.prompt.md +0 -80
  66. package/scaffold/_preview/prompts/aikit-flow-manage.prompt.md +0 -24
  67. package/scaffold/_preview/prompts/aikit-implement.prompt.md +0 -17
  68. package/scaffold/_preview/prompts/aikit-plan.prompt.md +0 -15
  69. package/scaffold/_preview/prompts/aikit-review.prompt.md +0 -24
  70. package/scaffold/_preview/skills/adr-skill/SKILL.md +0 -335
  71. package/scaffold/_preview/skills/adr-skill/assets/templates/adr-madr.md +0 -89
  72. package/scaffold/_preview/skills/adr-skill/assets/templates/adr-readme.md +0 -20
  73. package/scaffold/_preview/skills/adr-skill/assets/templates/adr-simple.md +0 -46
  74. package/scaffold/_preview/skills/adr-skill/references/adr-conventions.md +0 -95
  75. package/scaffold/_preview/skills/adr-skill/references/examples.md +0 -193
  76. package/scaffold/_preview/skills/adr-skill/references/review-checklist.md +0 -77
  77. package/scaffold/_preview/skills/adr-skill/references/template-variants.md +0 -52
  78. package/scaffold/_preview/skills/adr-skill/scripts/bootstrap_adr.js +0 -259
  79. package/scaffold/_preview/skills/adr-skill/scripts/new_adr.js +0 -391
  80. package/scaffold/_preview/skills/adr-skill/scripts/set_adr_status.js +0 -169
  81. package/scaffold/_preview/skills/aikit/SKILL.md +0 -754
  82. package/scaffold/_preview/skills/brainstorming/SKILL.md +0 -265
  83. package/scaffold/_preview/skills/brainstorming/spec-document-reviewer-prompt.md +0 -49
  84. package/scaffold/_preview/skills/c4-architecture/SKILL.md +0 -389
  85. package/scaffold/_preview/skills/c4-architecture/references/advanced-patterns.md +0 -552
  86. package/scaffold/_preview/skills/c4-architecture/references/c4-syntax.md +0 -510
  87. package/scaffold/_preview/skills/c4-architecture/references/common-mistakes.md +0 -437
  88. package/scaffold/_preview/skills/c4-architecture/references/html-design-system.md +0 -337
  89. package/scaffold/_preview/skills/c4-architecture/references/html-template.html +0 -627
  90. package/scaffold/_preview/skills/docs/SKILL.md +0 -553
  91. package/scaffold/_preview/skills/docs/references/diataxis-anti-patterns.md +0 -147
  92. package/scaffold/_preview/skills/docs/references/diataxis-compass.md +0 -123
  93. package/scaffold/_preview/skills/docs/references/diataxis-quadrants.md +0 -192
  94. package/scaffold/_preview/skills/docs/references/diataxis-quality.md +0 -76
  95. package/scaffold/_preview/skills/docs/references/diataxis-templates.md +0 -120
  96. package/scaffold/_preview/skills/docs/references/flow-artifacts-guide.md +0 -70
  97. package/scaffold/_preview/skills/docs/references/project-knowledge-gotchas.md +0 -32
  98. package/scaffold/_preview/skills/docs/references/project-knowledge-templates.md +0 -281
  99. package/scaffold/_preview/skills/docs/references/project-knowledge-workflow.md +0 -80
  100. package/scaffold/_preview/skills/frontend-design/SKILL.md +0 -237
  101. package/scaffold/_preview/skills/lesson-learned/SKILL.md +0 -113
  102. package/scaffold/_preview/skills/lesson-learned/references/anti-patterns.md +0 -55
  103. package/scaffold/_preview/skills/lesson-learned/references/se-principles.md +0 -109
  104. package/scaffold/_preview/skills/multi-agents-development/SKILL.md +0 -448
  105. package/scaffold/_preview/skills/multi-agents-development/architecture-review-prompt.md +0 -81
  106. package/scaffold/_preview/skills/multi-agents-development/code-quality-review-prompt.md +0 -91
  107. package/scaffold/_preview/skills/multi-agents-development/implementer-prompt.md +0 -93
  108. package/scaffold/_preview/skills/multi-agents-development/parallel-dispatch-example.md +0 -167
  109. package/scaffold/_preview/skills/multi-agents-development/spec-review-prompt.md +0 -81
  110. package/scaffold/_preview/skills/present/SKILL.md +0 -616
  111. package/scaffold/_preview/skills/react/SKILL.md +0 -309
  112. package/scaffold/_preview/skills/repo-access/SKILL.md +0 -178
  113. package/scaffold/_preview/skills/repo-access/references/error-patterns.md +0 -116
  114. package/scaffold/_preview/skills/repo-access/references/platform-matrix.md +0 -142
  115. package/scaffold/_preview/skills/requirements-clarity/SKILL.md +0 -333
  116. package/scaffold/_preview/skills/session-handoff/SKILL.md +0 -199
  117. package/scaffold/_preview/skills/session-handoff/references/handoff-template.md +0 -139
  118. package/scaffold/_preview/skills/session-handoff/references/resume-checklist.md +0 -80
  119. package/scaffold/_preview/skills/session-handoff/scripts/check_staleness.js +0 -269
  120. package/scaffold/_preview/skills/session-handoff/scripts/create_handoff.js +0 -299
  121. package/scaffold/_preview/skills/session-handoff/scripts/list_handoffs.js +0 -113
  122. package/scaffold/_preview/skills/session-handoff/scripts/validate_handoff.js +0 -241
  123. package/scaffold/_preview/skills/typescript/SKILL.md +0 -405
  124. package/scaffold/adapters/claude-code.mjs +0 -73
  125. package/scaffold/adapters/copilot.mjs +0 -292
  126. package/scaffold/adapters/flows.mjs +0 -27
  127. package/scaffold/adapters/skills.mjs +0 -25
  128. package/scaffold/definitions/agents.mjs +0 -266
  129. package/scaffold/definitions/exclusions.mjs +0 -58
  130. package/scaffold/definitions/hooks.mjs +0 -43
  131. package/scaffold/definitions/models.mjs +0 -84
  132. package/scaffold/definitions/plugins.mjs +0 -147
  133. package/scaffold/definitions/tools.mjs +0 -250
  134. package/scaffold/generate.mjs +0 -92
@@ -1,7 +1,4 @@
1
- // Auto-generated by scaffold/compile.mjs DO NOT EDIT
2
- export const FLOWS = {
3
- "_epilogue": [
4
- { file: "steps/docs-sync/README.md", content: `# Epilogue: Documentation Sync
1
+ const e={_epilogue:[{file:`steps/docs-sync/README.md`,content:`# Epilogue: Documentation Sync
5
2
 
6
3
  > **This is a mandatory epilogue step.** It runs automatically after every flow completes to keep project documentation synchronized with code changes.
7
4
 
@@ -120,260 +117,185 @@ If the flow's changes don't warrant doc updates (e.g., pure bug fix with no reve
120
117
  - [ ] \`docs/\` bootstrapped with tool outputs if it didn't exist
121
118
  - [ ] Relevant docs created or updated (or skipped with reason)
122
119
  - [ ] \`docs/README.md\` index is current
123
- - [ ] No placeholder/empty docs created — all content tool-generated or hand-written with purpose` },
124
- ],
125
- "aikit-advanced": [
126
- { file: "README.md", content: `# aikit:advanced — Full Development Flow
127
-
128
- Full development flow for **new features, API design, and architecture changes**.
129
-
130
- ## Steps
131
-
132
- | # | Step | Skill | Produces | Requires | Agents |
133
- |---|------|-------|----------|----------|--------|
134
- | 1 | **Design Gate** | \`steps/design/README.md\` | \`design-decisions.md\` | — | Researcher-Alpha/Beta/Gamma/Delta |
135
- | 2 | **Specification** | \`steps/spec/README.md\` | \`spec.md\` | \`design-decisions.md\` | Researcher-Alpha |
136
- | 3 | **Planning** | \`steps/plan/README.md\` | \`plan.md\` | \`spec.md\` | Planner, Explorer |
137
- | 4 | **Task Breakdown** | \`steps/task/README.md\` | \`tasks.md\` | \`plan.md\` | Planner, Architect-Reviewer-Alpha |
138
- | 5 | **Execution** | \`steps/execute/README.md\` | \`progress.md\` | \`tasks.md\` | Orchestrator, Implementer, Frontend, Refactor |
139
- | 6 | **Verification** | \`steps/verify/README.md\` | \`verify-report.md\` | \`progress.md\` | Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta, Security |
140
-
141
- ## How It Works
142
-
143
- Each step has a **README.md** file that contains the detailed instructions for the agent(s) executing that step. The Orchestrator reads the README.md via \`flow_read_instruction\` and delegates work accordingly.
144
-
145
- ### Step 1: Design Gate
146
- - Full brainstorming session for new features and architectural changes
147
- - FORGE classification (\`forge_classify\`) + grounding (\`forge_ground\`) for complex tasks
148
- - Parallel 4-researcher decision protocol for non-trivial technical decisions
149
- - ADR generation for critical-tier tasks
150
- - **Mandatory user stop** before proceeding design decisions must be approved
151
- - Read \`steps/design/README.md\` for the full protocol
152
-
153
- ### Step 2: Specification
154
- - Elicit requirements from the user, clarify scope
155
- - Define acceptance criteria and constraints
156
- - Build on design decisions from the previous step
157
-
158
- ### Step 3: Planning
159
- - Deep codebase analysis using \`search\`, \`scope_map\`, \`trace\`, \`analyze_*\`
160
- - Design architecture based on spec and design decisions
161
- - Create comprehensive implementation plan with file-level changes
162
-
163
- ### Step 4: Task Breakdown
164
- - Break the plan into ordered, atomic implementation tasks
165
- - Define dependencies between tasks
166
- - Identify parallel batches for multi-agent execution
167
- - Architecture review of the task structure
168
-
169
- ### Step 5: Execution
170
- - Orchestrator dispatches agents in parallel batches per the task breakdown
171
- - Each agent gets a scoped task (1-3 files) with clear acceptance criteria
172
- - TDD: write tests first, then implement
173
- - Per-batch review cycle: Code Review (dual) Arch Review Security Evidence Gate
174
-
175
- ### Step 6: Verification
176
- - Dual code review (Code-Reviewer-Alpha + Beta)
177
- - Architecture review (Architect-Reviewer-Alpha + Beta)
178
- - Security review
179
- - Run \`check({})\` + \`test_run({})\` + \`blast_radius({})\`
180
- - \`evidence_map({ action: "gate" })\` for final quality gate
181
-
182
- ## Using Skills Inside Steps
183
-
184
- When the Orchestrator activates a step:
185
-
186
- 1. **Read the instruction first** — \`flow_read_instruction\` returns the README.md for the current step
187
- 2. **Follow step instructions** — the README.md is the primary guide for what to do
188
- 3. **Delegate to listed agents** each step lists which agents are appropriate
189
- 4. **Produce the required artifact** — the step's \`produces\` field specifies what file to create in the artifacts directory
190
- 5. **Check dependencies** — the step's \`requires\` field lists artifacts from previous steps that must exist
191
- 6. **Report status** — agents report \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\` to the Orchestrator
192
-
193
- ## Artifacts
194
-
195
- All artifacts are stored in the run directory under \`.flows/{topic}/\`. The template variable \`{{artifacts_path}}\` resolves to the actual path at runtime.
196
- ` },
197
- { file: "steps/design/README.md", content: `# Design Gate — Advanced Flow
198
-
199
- Full design gate for new features, API design, and architecture changes. Runs brainstorming, decision protocol, and FORGE classification before specification begins.
200
-
201
- ## When This Step Runs
202
-
203
- This is the **first step** of the \`aikit:advanced\` flow. It runs before specification.
204
-
205
- ## Instructions
206
-
207
- ### 1. Task Classification
208
-
209
- Classify the task:
210
-
211
- | Category | Indicators | Action |
212
- |----------|-----------|--------|
213
- | **Bug fix** | Error, regression, "fix" — wrong flow, should use \`aikit:basic\` | → Note mismatch, still run Quick Design |
214
- | **New feature** | New behavior, new API, new component | Run **Full Design** below |
215
- | **Architecture change** | Restructure, migration, new pattern, cross-cutting | → Run **Full Design** with architecture focus |
216
-
217
- ### 2. FORGE Classification
218
-
219
- Run \`forge_classify({ task: "<task description>", files: [<relevant files>] })\` to determine the complexity tier.
220
-
221
- | Tier | Meaning | Design Depth |
222
- |------|---------|-------------|
223
- | **Floor** | Low risk, well-understood | Quick brainstorm, 1-2 decisions |
224
- | **Standard** | Moderate complexity | Full brainstorm, parallel research, decision protocol |
225
- | **Critical** | High risk, contract/security implications | Deep brainstorm, 4-researcher parallel review, ADR required |
226
-
227
- ### 3. Brainstorming Session
228
-
229
- Load the \`brainstorming\` skill and conduct a structured brainstorming session:
230
-
231
- 1. **Intent Discovery** — What is the user trying to achieve? What problem does this solve?
232
- 2. **Constraint Mapping** Technical constraints, time constraints, compatibility requirements
233
- 3. **Approach Exploration** — Generate 2-4 possible approaches
234
- 4. **Trade-off Analysis** Compare approaches on: complexity, maintainability, performance, risk
235
-
236
- For **Critical** tier tasks, also explore:
237
- - Security implications
238
- - Backward compatibility
239
- - Migration path
240
- - Rollback strategy
241
-
242
- ### 4. Decision Protocol (Standard & Critical tiers)
243
-
244
- When technical decisions need resolution:
245
-
246
- 1. **Identify decisions** — List each decision point with 2+ viable options
247
- 2. **Parallel research** Delegate to Researcher agents (2 for Standard, 4 for Critical):
248
- - Researcher-Alpha: Deep analysis of primary approach
249
- - Researcher-Beta: Trade-offs and edge cases of alternatives
250
- - Researcher-Gamma: Cross-domain patterns and precedents
251
- - Researcher-Delta: Feasibility and performance implications
252
- 3. **Synthesize** — Combine researcher findings into a recommendation per decision
253
- 4. **ADR** (Critical tier) — Load \`adr-skill\` and create an Architecture Decision Record
254
-
255
- ### 5. FORGE Ground (Standard & Critical tiers)
256
-
257
- Run \`forge_ground({ task, root_path: "." })\` to:
258
- - Scope the affected files and modules
259
- - Identify unknowns and risks
260
- - Load existing constraints and conventions
261
-
262
- **Auto-upgrade check**: If \`forge_ground\` reveals contract-type unknowns or security concerns not caught by initial \`forge_classify\`, recommend tier upgrade.
263
-
264
- ### 6. Write \`{{artifacts_path}}/design-decisions.md\` to disk
265
-
266
- **You MUST create this file on disk** using \`create_file\` or equivalent — do not just present content in chat.
267
-
268
- \`\`\`markdown
269
- ## Design Decisions
270
-
271
- ### FORGE Assessment
272
- - **Tier**: {Floor | Standard | Critical}
273
- - **Rationale**: {why this tier}
274
- - **Auto-upgrade**: {yes/no if yes, explain}
275
-
276
- ### Task Summary
277
- - **Goal**: {what we're building}
278
- - **Problem**: {what problem this solves}
279
- - **Users affected**: {who is impacted}
280
-
281
- ### Approach
282
- - **Chosen approach**: {description}
283
- - **Alternatives considered**: {list with reasons for rejection}
284
-
285
- ### Key Decisions
286
- | # | Decision | Choice | Rationale |
287
- |---|----------|--------|-----------|
288
- | 1 | {decision} | {choice} | {why} |
289
-
290
- ### Constraints
291
- - {constraint 1}
292
- - {constraint 2}
293
-
294
- ### Risks
295
- | Risk | Likelihood | Impact | Mitigation |
296
- |------|-----------|--------|------------|
297
- | {risk} | {L/M/H} | {L/M/H} | {mitigation} |
298
-
299
- ### Open Questions
300
- - {question 1}
301
- - {question 2}
302
- \`\`\`
303
-
304
- ### 7. Present to User
305
-
306
- Use \`present({ format: "html" })\` (or \`format: "browser"\` in CLI mode) to show:
307
- - Design decisions summary
308
- - FORGE tier and rationale
309
- - Key trade-offs
310
- - Open questions requiring user input
311
-
312
- **🛑 MANDATORY STOP** — Wait for user approval of design decisions before proceeding.
313
-
314
- ### 8. Report to Orchestrator
315
-
316
- After user approves:
317
- - \`DONE\` — design decisions approved, ready for specification
318
- - \`DONE_WITH_CONCERNS\` — approved with caveats (list them)
319
- - \`NEEDS_CONTEXT\` — user raised questions that need more research
320
-
321
- **Do NOT call \`flow_step\`** — let the Orchestrator advance the flow.
322
-
323
- ## Outputs
324
-
325
- Write \`{{artifacts_path}}/design-decisions.md\` to disk. **You MUST create this file** using \`create_file\` or equivalent — do not just present content in chat. This file is a prerequisite for the next step.
326
-
327
- ## Produces
328
-
329
- - \`{{artifacts_path}}/design-decisions.md\` — FORGE tier, approach, key decisions, constraints, risks
330
-
331
- ## Agents
332
-
333
- - \`Researcher-Alpha\` — Deep analysis of primary approach
334
- - \`Researcher-Beta\` — Trade-offs and edge cases
335
- - \`Researcher-Gamma\` — Cross-domain patterns
336
- - \`Researcher-Delta\` — Feasibility and performance
337
-
338
- ## Foundation Integration
339
-
340
- Load these skills BEFORE executing this step:
341
-
342
- | Skill | Purpose | When |
343
- |-------|---------|------|
344
- | \`aikit\` | Core MCP tools — search, analyze, remember, validate | Always (auto-loaded) |
345
- | \`present\` | Rich rendering for any structured output — assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
346
- | \`multi-agents-development\` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
347
- | \`brainstorming\` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
348
- | \`c4-architecture\` | C4 model diagrams showing system structure changes | When visualizing proposed architecture |
349
- | \`adr-skill\` | Architecture Decision Records for non-trivial decisions | Critical tier — document architecture decisions |
350
-
351
- ### Presentation Rules
352
- - Use \`present\` for **any output** that benefits from rich rendering — not limited to dashboards
353
- - Assessments, reports, comparisons, reviews, status boards → \`present({ format: "html" })\`
354
- - Tables, charts, progress tracking, code review findings → always present
355
- - Artifact content and summaries → present with structured layout
356
- - Only use plain text for brief confirmations and simple questions
357
-
358
- ## Completion Criteria
359
-
360
- - [ ] \`{{artifacts_path}}/design-decisions.md\` written to disk (NOT just presented in chat)
361
- - [ ] FORGE tier determined and documented
362
- - [ ] Brainstorming session completed (for Standard+ tier)
363
- - [ ] Key design decisions documented with rationale
364
- - [ ] User approval received (🛑 MANDATORY STOP)
365
-
366
- ## Knowledge Capture
367
-
368
- Before completing this step, persist important findings using \`remember()\`:
369
-
370
- - **Design decisions**: Chosen approach and alternatives considered with trade-offs
371
- - **Architecture patterns**: New patterns introduced or existing patterns that must be followed
372
- - **Constraints discovered**: Technical limitations, compatibility requirements, or performance boundaries
373
-
374
- **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
375
- ` },
376
- { file: "steps/execute/README.md", content: `---
120
+ - [ ] No placeholder/empty docs created — all content tool-generated or hand-written with purpose`}],"aikit-advanced":[{file:`README.md`,content:"# aikit:advanced — Full Development Flow\n\nFull development flow for **new features, API design, and architecture changes**.\n\n## Steps\n\n| # | Step | Skill | Produces | Requires | Agents |\n|---|------|-------|----------|----------|--------|\n| 1 | **Design Gate** | `steps/design/README.md` | `design-decisions.md` | — | Researcher-Alpha/Beta/Gamma/Delta |\n| 2 | **Specification** | `steps/spec/README.md` | `spec.md` | `design-decisions.md` | Researcher-Alpha |\n| 3 | **Planning** | `steps/plan/README.md` | `plan.md` | `spec.md` | Planner, Explorer |\n| 4 | **Task Breakdown** | `steps/task/README.md` | `tasks.md` | `plan.md` | Planner, Architect-Reviewer-Alpha |\n| 5 | **Execution** | `steps/execute/README.md` | `progress.md` | `tasks.md` | Orchestrator, Implementer, Frontend, Refactor |\n| 6 | **Verification** | `steps/verify/README.md` | `verify-report.md` | `progress.md` | Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta, Security |\n\n## How It Works\n\nEach step has a **README.md** file that contains the detailed instructions for the agent(s) executing that step. The Orchestrator reads the README.md via `flow_read_instruction` and delegates work accordingly.\n\n### Step 1: Design Gate\n- Full brainstorming session for new features and architectural changes\n- FORGE classification (`forge_classify`) + grounding (`forge_ground`) for complex tasks\n- Parallel 4-researcher decision protocol for non-trivial technical decisions\n- ADR generation for critical-tier tasks\n- **Mandatory user stop** before proceeding — design decisions must be approved\n- Read `steps/design/README.md` for the full protocol\n\n### Step 2: Specification\n- Elicit requirements from the user, clarify scope\n- Define acceptance criteria and constraints\n- Build on design decisions from the previous step\n\n### Step 3: Planning\n- Deep codebase analysis using `search`, `scope_map`, `trace`, `analyze_*`\n- Design architecture based on spec and design decisions\n- Create comprehensive implementation plan with file-level changes\n\n### Step 4: Task Breakdown\n- Break the plan into ordered, atomic implementation tasks\n- Define dependencies between tasks\n- Identify parallel batches for multi-agent execution\n- Architecture review of the task structure\n\n### Step 5: Execution\n- Orchestrator dispatches agents in parallel batches per the task breakdown\n- Each agent gets a scoped task (1-3 files) with clear acceptance criteria\n- TDD: write tests first, then implement\n- Per-batch review cycle: Code Review (dual) → Arch Review → Security → Evidence Gate\n\n### Step 6: Verification\n- Dual code review (Code-Reviewer-Alpha + Beta)\n- Architecture review (Architect-Reviewer-Alpha + Beta)\n- Security review\n- Run `check({})` + `test_run({})` + `blast_radius({})`\n- `evidence_map({ action: \"gate\" })` for final quality gate\n\n## Using Skills Inside Steps\n\nWhen the Orchestrator activates a step:\n\n1. **Read the instruction first** — `flow_read_instruction` returns the README.md for the current step\n2. **Follow step instructions** — the README.md is the primary guide for what to do\n3. **Delegate to listed agents** — each step lists which agents are appropriate\n4. **Produce the required artifact** — the step's `produces` field specifies what file to create in the artifacts directory\n5. **Check dependencies** — the step's `requires` field lists artifacts from previous steps that must exist\n6. **Report status** — agents report `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED` to the Orchestrator\n\n## Artifacts\n\nAll artifacts are stored in the run directory under `.flows/{topic}/`. The template variable `{{artifacts_path}}` resolves to the actual path at runtime.\n"},{file:`steps/design/README.md`,content:`# Design Gate — Advanced Flow
121
+
122
+ Full design gate for new features, API design, and architecture changes. Runs brainstorming, decision protocol, and FORGE classification before specification begins.
123
+
124
+ ## When This Step Runs
125
+
126
+ This is the **first step** of the \`aikit:advanced\` flow. It runs before specification.
127
+
128
+ ## Instructions
129
+
130
+ ### 1. Task Classification
131
+
132
+ Classify the task:
133
+
134
+ | Category | Indicators | Action |
135
+ |----------|-----------|--------|
136
+ | **Bug fix** | Error, regression, "fix" wrong flow, should use \`aikit:basic\` | Note mismatch, still run Quick Design |
137
+ | **New feature** | New behavior, new API, new component | → Run **Full Design** below |
138
+ | **Architecture change** | Restructure, migration, new pattern, cross-cutting | → Run **Full Design** with architecture focus |
139
+
140
+ ### 2. FORGE Classification
141
+
142
+ Run \`forge_classify({ task: "<task description>", files: [<relevant files>] })\` to determine the complexity tier.
143
+
144
+ | Tier | Meaning | Design Depth |
145
+ |------|---------|-------------|
146
+ | **Floor** | Low risk, well-understood | Quick brainstorm, 1-2 decisions |
147
+ | **Standard** | Moderate complexity | Full brainstorm, parallel research, decision protocol |
148
+ | **Critical** | High risk, contract/security implications | Deep brainstorm, 4-researcher parallel review, ADR required |
149
+
150
+ ### 3. Brainstorming Session
151
+
152
+ Load the \`brainstorming\` skill and conduct a structured brainstorming session:
153
+
154
+ 1. **Intent Discovery** — What is the user trying to achieve? What problem does this solve?
155
+ 2. **Constraint Mapping** — Technical constraints, time constraints, compatibility requirements
156
+ 3. **Approach Exploration** Generate 2-4 possible approaches
157
+ 4. **Trade-off Analysis** Compare approaches on: complexity, maintainability, performance, risk
158
+
159
+ For **Critical** tier tasks, also explore:
160
+ - Security implications
161
+ - Backward compatibility
162
+ - Migration path
163
+ - Rollback strategy
164
+
165
+ ### 4. Decision Protocol (Standard & Critical tiers)
166
+
167
+ When technical decisions need resolution:
168
+
169
+ 1. **Identify decisions** List each decision point with 2+ viable options
170
+ 2. **Parallel research** Delegate to Researcher agents (2 for Standard, 4 for Critical):
171
+ - Researcher-Alpha: Deep analysis of primary approach
172
+ - Researcher-Beta: Trade-offs and edge cases of alternatives
173
+ - Researcher-Gamma: Cross-domain patterns and precedents
174
+ - Researcher-Delta: Feasibility and performance implications
175
+ 3. **Synthesize** — Combine researcher findings into a recommendation per decision
176
+ 4. **ADR** (Critical tier) Load \`adr-skill\` and create an Architecture Decision Record
177
+
178
+ ### 5. FORGE Ground (Standard & Critical tiers)
179
+
180
+ Run \`forge_ground({ task, root_path: "." })\` to:
181
+ - Scope the affected files and modules
182
+ - Identify unknowns and risks
183
+ - Load existing constraints and conventions
184
+
185
+ **Auto-upgrade check**: If \`forge_ground\` reveals contract-type unknowns or security concerns not caught by initial \`forge_classify\`, recommend tier upgrade.
186
+
187
+ ### 6. Write \`{{artifacts_path}}/design-decisions.md\` to disk
188
+
189
+ **You MUST create this file on disk** using \`create_file\` or equivalent — do not just present content in chat.
190
+
191
+ \`\`\`markdown
192
+ ## Design Decisions
193
+
194
+ ### FORGE Assessment
195
+ - **Tier**: {Floor | Standard | Critical}
196
+ - **Rationale**: {why this tier}
197
+ - **Auto-upgrade**: {yes/no — if yes, explain}
198
+
199
+ ### Task Summary
200
+ - **Goal**: {what we're building}
201
+ - **Problem**: {what problem this solves}
202
+ - **Users affected**: {who is impacted}
203
+
204
+ ### Approach
205
+ - **Chosen approach**: {description}
206
+ - **Alternatives considered**: {list with reasons for rejection}
207
+
208
+ ### Key Decisions
209
+ | # | Decision | Choice | Rationale |
210
+ |---|----------|--------|-----------|
211
+ | 1 | {decision} | {choice} | {why} |
212
+
213
+ ### Constraints
214
+ - {constraint 1}
215
+ - {constraint 2}
216
+
217
+ ### Risks
218
+ | Risk | Likelihood | Impact | Mitigation |
219
+ |------|-----------|--------|------------|
220
+ | {risk} | {L/M/H} | {L/M/H} | {mitigation} |
221
+
222
+ ### Open Questions
223
+ - {question 1}
224
+ - {question 2}
225
+ \`\`\`
226
+
227
+ ### 7. Present to User
228
+
229
+ Use \`present({ format: "html" })\` (or \`format: "browser"\` in CLI mode) to show:
230
+ - Design decisions summary
231
+ - FORGE tier and rationale
232
+ - Key trade-offs
233
+ - Open questions requiring user input
234
+
235
+ **🛑 MANDATORY STOP** — Wait for user approval of design decisions before proceeding.
236
+
237
+ ### 8. Report to Orchestrator
238
+
239
+ After user approves:
240
+ - \`DONE\` — design decisions approved, ready for specification
241
+ - \`DONE_WITH_CONCERNS\` approved with caveats (list them)
242
+ - \`NEEDS_CONTEXT\` — user raised questions that need more research
243
+
244
+ **Do NOT call \`flow_step\`** let the Orchestrator advance the flow.
245
+
246
+ ## Outputs
247
+
248
+ Write \`{{artifacts_path}}/design-decisions.md\` to disk. **You MUST create this file** using \`create_file\` or equivalent — do not just present content in chat. This file is a prerequisite for the next step.
249
+
250
+ ## Produces
251
+
252
+ - \`{{artifacts_path}}/design-decisions.md\` FORGE tier, approach, key decisions, constraints, risks
253
+
254
+ ## Agents
255
+
256
+ - \`Researcher-Alpha\` Deep analysis of primary approach
257
+ - \`Researcher-Beta\` Trade-offs and edge cases
258
+ - \`Researcher-Gamma\` — Cross-domain patterns
259
+ - \`Researcher-Delta\` Feasibility and performance
260
+
261
+ ## Foundation Integration
262
+
263
+ Load these skills BEFORE executing this step:
264
+
265
+ | Skill | Purpose | When |
266
+ |-------|---------|------|
267
+ | \`aikit\` | Core MCP tools — search, analyze, remember, validate | Always (auto-loaded) |
268
+ | \`present\` | Rich rendering for any structured output — assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
269
+ | \`multi-agents-development\` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
270
+ | \`brainstorming\` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
271
+ | \`c4-architecture\` | C4 model diagrams showing system structure changes | When visualizing proposed architecture |
272
+ | \`adr-skill\` | Architecture Decision Records for non-trivial decisions | Critical tier — document architecture decisions |
273
+
274
+ ### Presentation Rules
275
+ - Use \`present\` for **any output** that benefits from rich rendering — not limited to dashboards
276
+ - Assessments, reports, comparisons, reviews, status boards → \`present({ format: "html" })\`
277
+ - Tables, charts, progress tracking, code review findings → always present
278
+ - Artifact content and summaries → present with structured layout
279
+ - Only use plain text for brief confirmations and simple questions
280
+
281
+ ## Completion Criteria
282
+
283
+ - [ ] \`{{artifacts_path}}/design-decisions.md\` written to disk (NOT just presented in chat)
284
+ - [ ] FORGE tier determined and documented
285
+ - [ ] Brainstorming session completed (for Standard+ tier)
286
+ - [ ] Key design decisions documented with rationale
287
+ - [ ] User approval received (🛑 MANDATORY STOP)
288
+
289
+ ## Knowledge Capture
290
+
291
+ Before completing this step, persist important findings using \`remember()\`:
292
+
293
+ - **Design decisions**: Chosen approach and alternatives considered with trade-offs
294
+ - **Architecture patterns**: New patterns introduced or existing patterns that must be followed
295
+ - **Constraints discovered**: Technical limitations, compatibility requirements, or performance boundaries
296
+
297
+ **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
298
+ `},{file:`steps/execute/README.md`,content:`---
377
299
  name: execute
378
300
  description: Implement all tasks from the task breakdown, dispatching agents in parallel where possible.
379
301
  ---
@@ -518,8 +440,7 @@ Before completing this step, persist important findings using \`remember()\`:
518
440
  - **Gotchas encountered**: Edge cases, workarounds, or non-obvious behaviors discovered during execution
519
441
 
520
442
  **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
521
- ` },
522
- { file: "steps/plan/README.md", content: `---
443
+ `},{file:`steps/plan/README.md`,content:`---
523
444
  name: plan
524
445
  description: Analyze the codebase, design the architecture, and create a detailed implementation plan.
525
446
  ---
@@ -641,8 +562,7 @@ Before completing this step, persist important findings using \`remember()\`:
641
562
  - **Resource decisions**: File ownership, module boundaries, and integration points
642
563
 
643
564
  **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
644
- ` },
645
- { file: "steps/spec/README.md", content: `---
565
+ `},{file:`steps/spec/README.md`,content:`---
646
566
  name: spec
647
567
  description: Elicit requirements, clarify scope, and define acceptance criteria through structured dialogue.
648
568
  ---
@@ -763,8 +683,7 @@ Before completing this step, persist important findings using \`remember()\`:
763
683
  - **Acceptance criteria**: Key testable conditions that define "done"
764
684
 
765
685
  **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
766
- ` },
767
- { file: "steps/task/README.md", content: `---
686
+ `},{file:`steps/task/README.md`,content:`---
768
687
  name: task
769
688
  description: Break the implementation plan into ordered, atomic tasks with dependencies and agent assignments.
770
689
  ---
@@ -883,8 +802,7 @@ Before completing this step, persist important findings using \`remember()\`:
883
802
  - **Coordination points**: Where tasks interact and handoff requirements
884
803
 
885
804
  **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
886
- ` },
887
- { file: "steps/verify/README.md", content: `---
805
+ `},{file:`steps/verify/README.md`,content:`---
888
806
  name: verify
889
807
  description: Dual code review, architecture review, security review, and comprehensive test validation.
890
808
  ---
@@ -1029,62 +947,7 @@ Before completing this step, persist important findings using \`remember()\`:
1029
947
  - **Session checkpoint**: Summarize what was accomplished, decisions made, and any remaining work
1030
948
 
1031
949
  **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
1032
- ` },
1033
- ],
1034
- "aikit-basic": [
1035
- { file: "README.md", content: `# aikit:basic — Quick Development Flow
1036
-
1037
- Quick development flow for **bug fixes, small features, and refactoring**.
1038
-
1039
- ## Steps
1040
-
1041
- | # | Step | Skill | Produces | Requires | Agents |
1042
- |---|------|-------|----------|----------|--------|
1043
- | 1 | **Design Gate** | \`steps/design/README.md\` | \`design-decisions.md\` | — | Researcher-Alpha/Beta/Gamma/Delta |
1044
- | 2 | **Assessment** | \`steps/assess/README.md\` | \`assessment.md\` | \`design-decisions.md\` | Explorer, Researcher-Alpha |
1045
- | 3 | **Implementation** | \`steps/implement/README.md\` | \`progress.md\` | \`assessment.md\` | Implementer, Frontend |
1046
- | 4 | **Verification** | \`steps/verify/README.md\` | \`verify-report.md\` | \`progress.md\` | Code-Reviewer-Alpha, Security |
1047
-
1048
- ## How It Works
1049
-
1050
- Each step has a **README.md** file that contains the detailed instructions for the agent(s) executing that step. The Orchestrator reads the README.md via \`flow_read_instruction\` and delegates work accordingly.
1051
-
1052
- ### Step 1: Design Gate
1053
- - **Auto-skips** for bug fixes and refactors (produces a minimal \`design-decisions.md\` noting it was skipped)
1054
- - For small features: runs quick brainstorming, FORGE classification, and optional decision protocol
1055
- - Read \`steps/design/README.md\` for the full decision tree
1056
-
1057
- ### Step 2: Assessment
1058
- - Explore the codebase to understand scope and impact
1059
- - Use \`search\`, \`scope_map\`, \`file_summary\`, \`compact\` to gather context
1060
- - Identify the approach and produce \`assessment.md\`
1061
-
1062
- ### Step 3: Implementation
1063
- - Write code following the assessment plan
1064
- - The Orchestrator dispatches Implementer/Frontend agents with specific file scopes
1065
- - Follow TDD practices where applicable
1066
-
1067
- ### Step 4: Verification
1068
- - Code review, test execution, security check
1069
- - Run \`check({})\` + \`test_run({})\` + \`blast_radius({})\`
1070
- - Produce \`verify-report.md\` with findings
1071
-
1072
- ## Using Skills Inside Steps
1073
-
1074
- When the Orchestrator activates a step:
1075
-
1076
- 1. **Read the instruction first** — \`flow_read_instruction\` returns the README.md for the current step
1077
- 2. **Follow step instructions** — the README.md is the primary guide for what to do
1078
- 3. **Delegate to listed agents** — each step lists which agents are appropriate
1079
- 4. **Produce the required artifact** — the step's \`produces\` field specifies what file to create in the artifacts directory
1080
- 5. **Check dependencies** — the step's \`requires\` field lists artifacts from previous steps that must exist
1081
- 6. **Report status** — agents report \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\` to the Orchestrator
1082
-
1083
- ## Artifacts
1084
-
1085
- All artifacts are stored in the run directory under \`.flows/{topic}/\`. The template variable \`{{artifacts_path}}\` resolves to the actual path at runtime.
1086
- ` },
1087
- { file: "steps/assess/README.md", content: `---
950
+ `}],"aikit-basic":[{file:`README.md`,content:"# aikit:basic — Quick Development Flow\n\nQuick development flow for **bug fixes, small features, and refactoring**.\n\n## Steps\n\n| # | Step | Skill | Produces | Requires | Agents |\n|---|------|-------|----------|----------|--------|\n| 1 | **Design Gate** | `steps/design/README.md` | `design-decisions.md` | — | Researcher-Alpha/Beta/Gamma/Delta |\n| 2 | **Assessment** | `steps/assess/README.md` | `assessment.md` | `design-decisions.md` | Explorer, Researcher-Alpha |\n| 3 | **Implementation** | `steps/implement/README.md` | `progress.md` | `assessment.md` | Implementer, Frontend |\n| 4 | **Verification** | `steps/verify/README.md` | `verify-report.md` | `progress.md` | Code-Reviewer-Alpha, Security |\n\n## How It Works\n\nEach step has a **README.md** file that contains the detailed instructions for the agent(s) executing that step. The Orchestrator reads the README.md via `flow_read_instruction` and delegates work accordingly.\n\n### Step 1: Design Gate\n- **Auto-skips** for bug fixes and refactors (produces a minimal `design-decisions.md` noting it was skipped)\n- For small features: runs quick brainstorming, FORGE classification, and optional decision protocol\n- Read `steps/design/README.md` for the full decision tree\n\n### Step 2: Assessment\n- Explore the codebase to understand scope and impact\n- Use `search`, `scope_map`, `file_summary`, `compact` to gather context\n- Identify the approach and produce `assessment.md`\n\n### Step 3: Implementation\n- Write code following the assessment plan\n- The Orchestrator dispatches Implementer/Frontend agents with specific file scopes\n- Follow TDD practices where applicable\n\n### Step 4: Verification\n- Code review, test execution, security check\n- Run `check({})` + `test_run({})` + `blast_radius({})`\n- Produce `verify-report.md` with findings\n\n## Using Skills Inside Steps\n\nWhen the Orchestrator activates a step:\n\n1. **Read the instruction first** — `flow_read_instruction` returns the README.md for the current step\n2. **Follow step instructions** — the README.md is the primary guide for what to do\n3. **Delegate to listed agents** — each step lists which agents are appropriate\n4. **Produce the required artifact** — the step's `produces` field specifies what file to create in the artifacts directory\n5. **Check dependencies** — the step's `requires` field lists artifacts from previous steps that must exist\n6. **Report status** — agents report `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED` to the Orchestrator\n\n## Artifacts\n\nAll artifacts are stored in the run directory under `.flows/{topic}/`. The template variable `{{artifacts_path}}` resolves to the actual path at runtime.\n"},{file:`steps/assess/README.md`,content:`---
1088
951
  name: assess
1089
952
  description: Understand scope, analyze the codebase, and identify the implementation approach.
1090
953
  ---
@@ -1193,125 +1056,123 @@ Before completing this step, persist important findings using \`remember()\`:
1193
1056
  - **Scope decisions**: What's in scope, what's explicitly excluded, and why
1194
1057
 
1195
1058
  **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
1196
- ` },
1197
- { file: "steps/design/README.md", content: `# Design Gate — Basic Flow
1198
-
1199
- Lightweight design gate for bug fixes, small features, and refactoring. Evaluates the task type and determines whether design work is needed before proceeding.
1200
-
1201
- ## When This Step Runs
1202
-
1203
- This is the **first step** of the \`aikit:basic\` flow. It runs before assessment.
1204
-
1205
- ## Instructions
1206
-
1207
- ### 1. Task Classification
1208
-
1209
- Classify the task into one of these categories:
1210
-
1211
- | Category | Indicators | Action |
1212
- |----------|-----------|--------|
1213
- | **Bug fix** | Error reports, stack traces, regression, "fix", "broken" | → **Auto-skip** to next step |
1214
- | **Refactor** | Code cleanup, rename, restructure, no behavior change | → **Auto-skip** to next step |
1215
- | **Small feature** | New behavior, new endpoint, new component, UI change | → Run **Quick Design** below |
1216
-
1217
- **If the task is a bug fix or refactor**, write \`{{artifacts_path}}/design-decisions.md\` to disk:
1218
- \`\`\`markdown
1219
- ## Design Decisions
1220
- - **Task type**: Bug fix / Refactor
1221
- - **Design gate**: Auto-skipped — no design work needed
1222
- - **Proceed to**: Assessment
1223
- \`\`\`
1224
- **You MUST create this file on disk** at the exact \`{{artifacts_path}}/design-decisions.md\` path do not just present the content in chat.
1225
- Then report \`DONE\` to the Orchestrator so the flow advances.
1226
-
1227
- ### 2. Quick Design (Small Features Only)
1228
-
1229
- For small features that need minimal design:
1230
-
1231
- 1. **FORGE Classify** — Run \`forge_classify({ task: "<task description>", files: [<relevant files>] })\` to determine complexity tier
1232
- 2. **Brainstorming** (if tier ≥ Standard) — Load the \`brainstorming\` skill and run a focused brainstorming session:
1233
- - What is the user trying to achieve?
1234
- - What are the constraints?
1235
- - What is the simplest approach?
1236
- 3. **Decision Protocol** (if technical decisions exist) — Delegate to 2-4 Researcher agents in parallel:
1237
- - Each researcher evaluates a different approach
1238
- - Synthesize findings into a recommendation
1239
- 4. **Write \`{{artifacts_path}}/design-decisions.md\`** to disk:
1240
-
1241
- \`\`\`markdown
1242
- ## Design Decisions
1243
-
1244
- ### FORGE Assessment
1245
- - **Tier**: {Floor | Standard | Critical}
1246
- - **Rationale**: {why this tier}
1247
-
1248
- ### Task Summary
1249
- - **Goal**: {what we're building}
1250
- - **Approach**: {chosen approach}
1251
- - **Key decisions**: {list}
1252
-
1253
- ### Constraints
1254
- - {constraint 1}
1255
- - {constraint 2}
1256
- \`\`\`
1257
-
1258
- ### 3. Report to Orchestrator
1259
-
1260
- When complete, report status:
1261
- - \`DONE\` — design decisions captured, ready for assessment
1262
- - \`DONE_WITH_CONCERNS\` — design captured but open questions remain (list them)
1263
-
1264
- **Do NOT call \`flow_step\`** — let the Orchestrator advance the flow.
1265
-
1266
- ## Outputs
1267
-
1268
- Write \`{{artifacts_path}}/design-decisions.md\` to disk. **You MUST create this file** using \`create_file\` or equivalent — do not just present content in chat. This file is a prerequisite for the next step.
1269
-
1270
- ## Produces
1271
-
1272
- - \`{{artifacts_path}}/design-decisions.md\` — Task classification, FORGE tier, key design decisions
1273
-
1274
- ## Agents
1275
-
1276
- - \`Researcher-Alpha\`, \`Researcher-Beta\`, \`Researcher-Gamma\`, \`Researcher-Delta\` — for parallel research during decision protocol
1277
-
1278
- ## Foundation Integration
1279
-
1280
- Load these skills BEFORE executing this step:
1281
-
1282
- | Skill | Purpose | When |
1283
- |-------|---------|------|
1284
- | \`aikit\` | Core MCP toolssearch, analyze, remember, validate | Always (auto-loaded) |
1285
- | \`present\` | Rich rendering for any structured output — assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
1286
- | \`multi-agents-development\` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
1287
- | \`brainstorming\` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
1288
- | \`c4-architecture\` | C4 model architecture diagrams system context, container, component, deployment views | When visualizing system structure during design |
1289
- | \`adr-skill\` | Architecture Decision Records — create, review, maintain ADRs | When making non-trivial design or technology decisions |
1290
-
1291
- ### Presentation Rules
1292
- - Use \`present\` for **any output** that benefits from rich rendering — not limited to dashboards
1293
- - Assessments, reports, comparisons, reviews, status boards\`present({ format: "html" })\`
1294
- - Tables, charts, progress tracking, code review findings always present
1295
- - Artifact content and summaries present with structured layout
1296
- - Only use plain text for brief confirmations and simple questions
1297
-
1298
- ## Completion Criteria
1299
-
1300
- - [ ] \`{{artifacts_path}}/design-decisions.md\` written to disk (NOT just presented in chat)
1301
- - [ ] FORGE tier determined (for small features)
1302
- - [ ] Key design decisions documented
1303
-
1304
- ## Knowledge Capture
1305
-
1306
- Before completing this step, persist important findings using \`remember()\`:
1307
-
1308
- - **Design decisions**: Chosen approach and alternatives considered with trade-offs
1309
- - **Architecture patterns**: New patterns introduced or existing patterns that must be followed
1310
- - **Constraints discovered**: Technical limitations, compatibility requirements, or performance boundaries
1311
-
1312
- **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
1313
- ` },
1314
- { file: "steps/implement/README.md", content: `---
1059
+ `},{file:`steps/design/README.md`,content:`# Design Gate — Basic Flow
1060
+
1061
+ Lightweight design gate for bug fixes, small features, and refactoring. Evaluates the task type and determines whether design work is needed before proceeding.
1062
+
1063
+ ## When This Step Runs
1064
+
1065
+ This is the **first step** of the \`aikit:basic\` flow. It runs before assessment.
1066
+
1067
+ ## Instructions
1068
+
1069
+ ### 1. Task Classification
1070
+
1071
+ Classify the task into one of these categories:
1072
+
1073
+ | Category | Indicators | Action |
1074
+ |----------|-----------|--------|
1075
+ | **Bug fix** | Error reports, stack traces, regression, "fix", "broken" | → **Auto-skip** to next step |
1076
+ | **Refactor** | Code cleanup, rename, restructure, no behavior change | → **Auto-skip** to next step |
1077
+ | **Small feature** | New behavior, new endpoint, new component, UI change | → Run **Quick Design** below |
1078
+
1079
+ **If the task is a bug fix or refactor**, write \`{{artifacts_path}}/design-decisions.md\` to disk:
1080
+ \`\`\`markdown
1081
+ ## Design Decisions
1082
+ - **Task type**: Bug fix / Refactor
1083
+ - **Design gate**: Auto-skipped no design work needed
1084
+ - **Proceed to**: Assessment
1085
+ \`\`\`
1086
+ **You MUST create this file on disk** at the exact \`{{artifacts_path}}/design-decisions.md\` path — do not just present the content in chat.
1087
+ Then report \`DONE\` to the Orchestrator so the flow advances.
1088
+
1089
+ ### 2. Quick Design (Small Features Only)
1090
+
1091
+ For small features that need minimal design:
1092
+
1093
+ 1. **FORGE Classify** — Run \`forge_classify({ task: "<task description>", files: [<relevant files>] })\` to determine complexity tier
1094
+ 2. **Brainstorming** (if tier Standard) Load the \`brainstorming\` skill and run a focused brainstorming session:
1095
+ - What is the user trying to achieve?
1096
+ - What are the constraints?
1097
+ - What is the simplest approach?
1098
+ 3. **Decision Protocol** (if technical decisions exist) — Delegate to 2-4 Researcher agents in parallel:
1099
+ - Each researcher evaluates a different approach
1100
+ - Synthesize findings into a recommendation
1101
+ 4. **Write \`{{artifacts_path}}/design-decisions.md\`** to disk:
1102
+
1103
+ \`\`\`markdown
1104
+ ## Design Decisions
1105
+
1106
+ ### FORGE Assessment
1107
+ - **Tier**: {Floor | Standard | Critical}
1108
+ - **Rationale**: {why this tier}
1109
+
1110
+ ### Task Summary
1111
+ - **Goal**: {what we're building}
1112
+ - **Approach**: {chosen approach}
1113
+ - **Key decisions**: {list}
1114
+
1115
+ ### Constraints
1116
+ - {constraint 1}
1117
+ - {constraint 2}
1118
+ \`\`\`
1119
+
1120
+ ### 3. Report to Orchestrator
1121
+
1122
+ When complete, report status:
1123
+ - \`DONE\` — design decisions captured, ready for assessment
1124
+ - \`DONE_WITH_CONCERNS\` — design captured but open questions remain (list them)
1125
+
1126
+ **Do NOT call \`flow_step\`** — let the Orchestrator advance the flow.
1127
+
1128
+ ## Outputs
1129
+
1130
+ Write \`{{artifacts_path}}/design-decisions.md\` to disk. **You MUST create this file** using \`create_file\` or equivalent — do not just present content in chat. This file is a prerequisite for the next step.
1131
+
1132
+ ## Produces
1133
+
1134
+ - \`{{artifacts_path}}/design-decisions.md\` — Task classification, FORGE tier, key design decisions
1135
+
1136
+ ## Agents
1137
+
1138
+ - \`Researcher-Alpha\`, \`Researcher-Beta\`, \`Researcher-Gamma\`, \`Researcher-Delta\` — for parallel research during decision protocol
1139
+
1140
+ ## Foundation Integration
1141
+
1142
+ Load these skills BEFORE executing this step:
1143
+
1144
+ | Skill | Purpose | When |
1145
+ |-------|---------|------|
1146
+ | \`aikit\` | Core MCP tools — search, analyze, remember, validate | Always (auto-loaded) |
1147
+ | \`present\` | Rich rendering for any structured output assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
1148
+ | \`multi-agents-development\` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
1149
+ | \`brainstorming\` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
1150
+ | \`c4-architecture\` | C4 model architecture diagrams system context, container, component, deployment views | When visualizing system structure during design |
1151
+ | \`adr-skill\` | Architecture Decision Recordscreate, review, maintain ADRs | When making non-trivial design or technology decisions |
1152
+
1153
+ ### Presentation Rules
1154
+ - Use \`present\` for **any output** that benefits from rich rendering — not limited to dashboards
1155
+ - Assessments, reports, comparisons, reviews, status boards \`present({ format: "html" })\`
1156
+ - Tables, charts, progress tracking, code review findings always present
1157
+ - Artifact content and summaries present with structured layout
1158
+ - Only use plain text for brief confirmations and simple questions
1159
+
1160
+ ## Completion Criteria
1161
+
1162
+ - [ ] \`{{artifacts_path}}/design-decisions.md\` written to disk (NOT just presented in chat)
1163
+ - [ ] FORGE tier determined (for small features)
1164
+ - [ ] Key design decisions documented
1165
+
1166
+ ## Knowledge Capture
1167
+
1168
+ Before completing this step, persist important findings using \`remember()\`:
1169
+
1170
+ - **Design decisions**: Chosen approach and alternatives considered with trade-offs
1171
+ - **Architecture patterns**: New patterns introduced or existing patterns that must be followed
1172
+ - **Constraints discovered**: Technical limitations, compatibility requirements, or performance boundaries
1173
+
1174
+ **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
1175
+ `},{file:`steps/implement/README.md`,content:`---
1315
1176
  name: implement
1316
1177
  description: Write code following the assessment plan, using TDD practices where applicable.
1317
1178
  ---
@@ -1442,8 +1303,7 @@ Before completing this step, persist important findings using \`remember()\`:
1442
1303
  - **Gotchas encountered**: Edge cases, workarounds, or non-obvious behaviors discovered during implementation
1443
1304
 
1444
1305
  **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
1445
- ` },
1446
- { file: "steps/verify/README.md", content: `---
1306
+ `},{file:`steps/verify/README.md`,content:`---
1447
1307
  name: verify
1448
1308
  description: Review code changes, run tests, validate correctness and quality.
1449
1309
  ---
@@ -1566,6 +1426,4 @@ Before completing this step, persist important findings using \`remember()\`:
1566
1426
  - **Session checkpoint**: Summarize what was accomplished, decisions made, and any remaining work
1567
1427
 
1568
1428
  **Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`remember()\` now.
1569
- ` },
1570
- ],
1571
- };
1429
+ `}]};export{e as FLOWS};