maestro-flow 0.3.11 → 0.3.12

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 (164) hide show
  1. package/.claude/agents/conceptual-planning-agent.md +1 -0
  2. package/.claude/agents/workflow-analyzer.md +114 -114
  3. package/.claude/agents/workflow-collab-planner.md +144 -144
  4. package/.claude/agents/workflow-debugger.md +102 -103
  5. package/.claude/agents/workflow-executor.md +127 -128
  6. package/.claude/agents/workflow-integration-checker.md +82 -82
  7. package/.claude/agents/workflow-nyquist-auditor.md +85 -84
  8. package/.claude/agents/workflow-phase-researcher.md +85 -85
  9. package/.claude/agents/workflow-plan-checker.md +90 -90
  10. package/.claude/agents/workflow-planner.md +178 -178
  11. package/.claude/agents/workflow-roadmapper.md +81 -83
  12. package/.claude/agents/workflow-verifier.md +119 -119
  13. package/.claude/commands/learn-retro.md +2 -2
  14. package/.claude/commands/learn-second-opinion.md +2 -2
  15. package/.claude/commands/maestro-brainstorm.md +1 -0
  16. package/.claude/commands/maestro-fork.md +133 -111
  17. package/.claude/commands/maestro-merge.md +85 -77
  18. package/.claude/commands/maestro-plan.md +88 -2
  19. package/.claude/commands/maestro-roadmap.md +113 -2
  20. package/.claude/commands/maestro.md +1 -0
  21. package/.claude/commands/quality-business-test.md +5 -5
  22. package/.claude/commands/quality-debug.md +3 -2
  23. package/.claude/commands/quality-retrospective.md +6 -4
  24. package/.claude/commands/quality-review.md +1 -1
  25. package/.claude/commands/quality-test-gen.md +5 -4
  26. package/.codex/skills/maestro-brainstorm/SKILL.md +1 -1
  27. package/.codex/skills/maestro-fork/SKILL.md +98 -68
  28. package/.codex/skills/maestro-init/SKILL.md +4 -3
  29. package/.codex/skills/maestro-merge/SKILL.md +69 -62
  30. package/.codex/skills/maestro-ui-design/SKILL.md +1 -1
  31. package/.codex/skills/maestro-verify/SKILL.md +12 -12
  32. package/.codex/skills/manage-learn/SKILL.md +1 -1
  33. package/.codex/skills/manage-status/SKILL.md +4 -4
  34. package/.codex/skills/quality-business-test/SKILL.md +2 -2
  35. package/.codex/skills/quality-integration-test/SKILL.md +1 -1
  36. package/.codex/skills/quality-retrospective/SKILL.md +7 -7
  37. package/.codex/skills/quality-review/SKILL.md +2 -2
  38. package/.codex/skills/quality-test/SKILL.md +2 -2
  39. package/.codex/skills/quality-test-gen/SKILL.md +1 -1
  40. package/README.md +2 -0
  41. package/README.zh-CN.md +2 -0
  42. package/dashboard/dist/assets/{ArtifactsPage-DZNCi6tn.js → ArtifactsPage-CUrrDGgN.js} +1 -1
  43. package/dashboard/dist/assets/ChatInput-pUOLJIKE.js +49 -0
  44. package/dashboard/dist/assets/ChatPage-B8Xqkt0v.js +27 -0
  45. package/dashboard/dist/assets/{CollabPage-B4NAHXS2.js → CollabPage-DIUXeazv.js} +1 -1
  46. package/dashboard/dist/assets/{ExecutionPanel-CFt4LJyq.js → ExecutionPanel-VmYeADFj.js} +1 -1
  47. package/dashboard/dist/assets/KanbanPage-DLq8v7hg.js +21 -0
  48. package/dashboard/dist/assets/{MarkdownRenderer-X4af_WNb.js → MarkdownRenderer-D7AehrnR.js} +1 -1
  49. package/dashboard/dist/assets/{McpPage-BKfCVIyU.js → McpPage-BY0SjTgw.js} +2 -2
  50. package/dashboard/dist/assets/{OutputPanel-BlBQFJSW.js → OutputPanel-B-Rjwgmv.js} +1 -1
  51. package/dashboard/dist/assets/{ProblemsPanel-De3DLvoI.js → ProblemsPanel-GEpF-oi4.js} +1 -1
  52. package/dashboard/dist/assets/RequirementBoardPage-xs8uDM7I.js +6 -0
  53. package/dashboard/dist/assets/{RequirementPage-Bllxe2XI.js → RequirementPage-BKDSFwjA.js} +5 -10
  54. package/dashboard/dist/assets/SpecsPage-DLFb9ZH0.js +36 -0
  55. package/dashboard/dist/assets/SupervisorPage-SOki_kgz.js +6 -0
  56. package/dashboard/dist/assets/TeamsPage-BO2kP70F.js +11 -0
  57. package/dashboard/dist/assets/{TreeBrowser-Q12qobZs.js → TreeBrowser-B9DHdULE.js} +1 -1
  58. package/dashboard/dist/assets/{WorkflowPage-D_Fzdy3_.js → WorkflowPage-C8hWbYim.js} +1 -1
  59. package/dashboard/dist/assets/{check-u6fGOwQO.js → check-DJDk3A2a.js} +1 -1
  60. package/dashboard/dist/assets/{chevron-right-Csu22t58.js → chevron-right-C7bVDreZ.js} +1 -1
  61. package/dashboard/dist/assets/{circle-CMrkbRNg.js → circle-Qfgy4LB_.js} +1 -1
  62. package/dashboard/dist/assets/{circle-alert-c3tH1P4z.js → circle-alert-Na1vf6qQ.js} +1 -1
  63. package/dashboard/dist/assets/{circle-check-gYxxSYuH.js → circle-check-CEGgy3NV.js} +1 -1
  64. package/dashboard/dist/assets/{circle-check-big-TDSeWstm.js → circle-check-big-3JB8zRYj.js} +1 -1
  65. package/dashboard/dist/assets/{code-CFN2uX9V.js → code-Ble63Idz.js} +1 -1
  66. package/dashboard/dist/assets/{columns-3-38xIDlzy.js → columns-3-BUcKlxve.js} +1 -1
  67. package/dashboard/dist/assets/{download-DC7KkKyP.js → download-CMqkfn8x.js} +1 -1
  68. package/dashboard/dist/assets/{folder-CWq_lAnf.js → folder-B9ewx9LL.js} +1 -1
  69. package/dashboard/dist/assets/index-C2Mcb4TJ.js +231 -0
  70. package/dashboard/dist/assets/index-DyBbPc18.css +1 -0
  71. package/dashboard/dist/assets/{index-Do71weNR.js → index-JTmGteaT.js} +1 -1
  72. package/dashboard/dist/assets/{list-CgIP_2A-.js → list-DI8Wn2aT.js} +1 -1
  73. package/dashboard/dist/assets/loader-B5F6PzFT.js +11 -0
  74. package/dashboard/dist/assets/{minus-DYoN5UGk.js → minus-Lp_BfctG.js} +1 -1
  75. package/dashboard/dist/assets/{pen-line-Bh_WKYHm.js → pen-line-Ch7sphzZ.js} +1 -1
  76. package/dashboard/dist/assets/pencil-_yRMHmGT.js +6 -0
  77. package/dashboard/dist/assets/{proxy-BKxDAKTj.js → proxy-D72Y8a4Y.js} +1 -1
  78. package/dashboard/dist/assets/{search-SieXnOgr.js → search-BS6fI6Bg.js} +1 -1
  79. package/dashboard/dist/assets/{shallow-Bme1JY57.js → shallow-BXasQBvr.js} +1 -1
  80. package/dashboard/dist/assets/table-CeGlFjlP.js +6 -0
  81. package/dashboard/dist/assets/{terminal-BB3Xfuv5.js → terminal-BJic2yW-.js} +1 -1
  82. package/dashboard/dist/assets/{trash-2-C8f4vFFM.js → trash-2-Czz4X8Fb.js} +1 -1
  83. package/dashboard/dist/assets/{zap-4uwlzVm0.js → zap-C3H0jVFA.js} +1 -1
  84. package/dashboard/dist/index.html +2 -2
  85. package/dashboard/dist-server/dashboard/src/server/agents/agent-manager.js +16 -1
  86. package/dashboard/dist-server/dashboard/src/server/agents/agent-manager.js.map +1 -1
  87. package/dashboard/dist-server/dashboard/src/server/agents/delegate-broker-monitor.js +1 -2
  88. package/dashboard/dist-server/dashboard/src/server/agents/delegate-broker-monitor.js.map +1 -1
  89. package/dashboard/dist-server/dashboard/src/server/commander/commander-prompts.d.ts +1 -1
  90. package/dashboard/dist-server/dashboard/src/server/commander/commander-prompts.js +2 -1
  91. package/dashboard/dist-server/dashboard/src/server/commander/commander-prompts.js.map +1 -1
  92. package/dashboard/dist-server/dashboard/src/server/index.js +3 -0
  93. package/dashboard/dist-server/dashboard/src/server/index.js.map +1 -1
  94. package/dashboard/dist-server/dashboard/src/server/routes/collab.js +124 -0
  95. package/dashboard/dist-server/dashboard/src/server/routes/collab.js.map +1 -1
  96. package/dashboard/dist-server/dashboard/src/server/ws/handlers/team-handler.d.ts +10 -0
  97. package/dashboard/dist-server/dashboard/src/server/ws/handlers/team-handler.js +73 -0
  98. package/dashboard/dist-server/dashboard/src/server/ws/handlers/team-handler.js.map +1 -0
  99. package/dashboard/dist-server/dashboard/src/shared/collab-types.d.ts +31 -0
  100. package/dashboard/dist-server/dashboard/src/shared/collab-types.js +28 -0
  101. package/dashboard/dist-server/dashboard/src/shared/collab-types.js.map +1 -1
  102. package/dashboard/dist-server/dashboard/src/shared/constants.js +5 -0
  103. package/dashboard/dist-server/dashboard/src/shared/constants.js.map +1 -1
  104. package/dashboard/dist-server/dashboard/src/shared/coordinate-types.d.ts +22 -0
  105. package/dashboard/dist-server/dashboard/src/shared/issue-types.d.ts +12 -0
  106. package/dashboard/dist-server/dashboard/src/shared/issue-types.js +12 -0
  107. package/dashboard/dist-server/dashboard/src/shared/issue-types.js.map +1 -1
  108. package/dashboard/dist-server/dashboard/src/shared/team-types.d.ts +1 -0
  109. package/dashboard/dist-server/dashboard/src/shared/team-types.js +7 -0
  110. package/dashboard/dist-server/dashboard/src/shared/team-types.js.map +1 -1
  111. package/dashboard/dist-server/dashboard/src/shared/ws-protocol.d.ts +27 -1
  112. package/dashboard/dist-server/dashboard/src/shared/ws-protocol.js.map +1 -1
  113. package/dashboard/dist-server/shared/agent-types.d.ts +4 -0
  114. package/dashboard/dist-server/src/hooks/constants.d.ts +1 -1
  115. package/dashboard/dist-server/src/hooks/constants.js +2 -2
  116. package/dashboard/dist-server/src/hooks/constants.js.map +1 -1
  117. package/dist/shared/agent-types.d.ts +4 -0
  118. package/dist/shared/agent-types.d.ts.map +1 -1
  119. package/dist/src/commands/install-backend.d.ts.map +1 -1
  120. package/dist/src/commands/install-backend.js +29 -18
  121. package/dist/src/commands/install-backend.js.map +1 -1
  122. package/dist/src/hooks/__tests__/statusline-visual-test.js +23 -1
  123. package/dist/src/hooks/__tests__/statusline-visual-test.js.map +1 -1
  124. package/dist/src/hooks/constants.d.ts +1 -1
  125. package/dist/src/hooks/constants.d.ts.map +1 -1
  126. package/dist/src/hooks/constants.js +2 -2
  127. package/dist/src/hooks/constants.js.map +1 -1
  128. package/dist/src/hooks/skill-context.d.ts +3 -0
  129. package/dist/src/hooks/skill-context.d.ts.map +1 -1
  130. package/dist/src/hooks/skill-context.js +95 -9
  131. package/dist/src/hooks/skill-context.js.map +1 -1
  132. package/dist/src/hooks/statusline.d.ts.map +1 -1
  133. package/dist/src/hooks/statusline.js +6 -3
  134. package/dist/src/hooks/statusline.js.map +1 -1
  135. package/dist/src/tools/merge-validator.d.ts.map +1 -1
  136. package/dist/src/tools/merge-validator.js +114 -16
  137. package/dist/src/tools/merge-validator.js.map +1 -1
  138. package/package.json +1 -1
  139. package/shared/agent-types.ts +4 -0
  140. package/templates/worktree-scope.json +9 -10
  141. package/templates/worktrees.json +26 -27
  142. package/workflows/brainstorm.md +10 -1
  143. package/workflows/debug.md +16 -6
  144. package/workflows/fork.md +100 -36
  145. package/workflows/integration-test.md +14 -2
  146. package/workflows/issue.md +14 -4
  147. package/workflows/learn.md +19 -5
  148. package/workflows/maestro.md +1 -0
  149. package/workflows/merge.md +113 -55
  150. package/workflows/retrospective.md +61 -22
  151. package/workflows/review.md +17 -4
  152. package/workflows/test.md +12 -2
  153. package/workflows/ui-style.md +9 -2
  154. package/dashboard/dist/assets/ChatInput-Bvr-FeEq.js +0 -49
  155. package/dashboard/dist/assets/ChatPage-D9zTkJZo.js +0 -22
  156. package/dashboard/dist/assets/KanbanPage-C8USth6H.js +0 -21
  157. package/dashboard/dist/assets/RequirementBoardPage-Bf1trzqs.js +0 -11
  158. package/dashboard/dist/assets/SpecsPage-9lwxKT27.js +0 -36
  159. package/dashboard/dist/assets/SupervisorPage-SusdfHFq.js +0 -6
  160. package/dashboard/dist/assets/TeamsPage-DsuM6OwC.js +0 -6
  161. package/dashboard/dist/assets/arrow-left-Bqtb2hle.js +0 -6
  162. package/dashboard/dist/assets/index-DWG-WrzT.js +0 -231
  163. package/dashboard/dist/assets/index-GUNJodSR.css +0 -1
  164. package/dashboard/dist/assets/table-llyEtj-7.js +0 -6
@@ -1,119 +1,119 @@
1
- ---
2
- name: workflow-verifier
3
- description: Goal-backward verification across three layers (existence, substance, connection)
4
- allowed-tools:
5
- - Read
6
- - Glob
7
- - Grep
8
- - Bash
9
- ---
10
-
11
- # Workflow Verifier
12
-
13
- ## Role
14
- You perform goal-backward verification of completed work using a three-layer checking approach. You verify that artifacts exist, contain real substance, and are properly connected to the rest of the system. You also validate each task's convergence criteria individually. You are read-only and never modify project files.
15
-
16
- ## Search Tools
17
- @~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
18
-
19
- ## Process
20
-
21
- 1. **Load goals** -- Read the phase/task goals, success criteria, must_haves, and `convergence.criteria` from each task JSON
22
- 2. **Layer 1 - Existence** -- Verify all expected artifacts exist:
23
- - Files created as specified in task `files[].path` where `files[].action` is "create"
24
- - Functions/classes/modules present at `files[].target`
25
- - Configuration entries added
26
- 3. **Layer 2 - Substance** -- Verify artifacts are non-trivial:
27
- - Files contain meaningful implementation (not stubs or TODOs)
28
- - Functions have real logic (not empty bodies or pass-through)
29
- - Tests actually test behavior (not empty test cases)
30
- 4. **Layer 3 - Connection** -- Verify artifacts are properly wired:
31
- - Imports resolve correctly
32
- - New modules are registered/exported
33
- - Routes are mounted, handlers are connected
34
- - Configuration is loaded and used
35
- 5. **Per-task convergence validation** -- For each completed task, verify every item in `convergence.criteria`:
36
- - Run `convergence.verification` command if defined
37
- - Check each criterion individually (pass/fail with evidence)
38
- - Cross-reference with task summaries in `.summaries/`
39
- 6. **Check must_haves** -- Verify each must_have category:
40
- - `truths`: Invariants that must hold
41
- - `artifacts`: Files/outputs that must exist
42
- - `key_links`: Connections that must be wired
43
- 7. **Write report** -- Output verification.json with results
44
-
45
- ## Input
46
- - Phase or task goals with must_haves definition
47
- - `.task/TASK-{NNN}.json` files with `convergence.criteria` to validate
48
- - Completed code/artifacts to verify
49
- - Task summaries from `.summaries/`
50
- - **Project specs** — `maestro spec load --category validation`: verification criteria, acceptance standards. Must verify code complies with loaded constraints.
51
-
52
- ## Output
53
- `verification.json`:
54
- ```json
55
- {
56
- "phase": "<phase-id>",
57
- "status": "pass|fail",
58
- "layers": {
59
- "existence": {"pass": true, "checks": [...]},
60
- "substance": {"pass": true, "checks": [...]},
61
- "connection": {"pass": false, "checks": [...]}
62
- },
63
- "convergence_check": {
64
- "TASK-001": {
65
- "status": "pass",
66
- "criteria": [
67
- {"criterion": "File src/tools/new-tool.ts exports NewTool class", "pass": true, "evidence": "grep confirms export at line 15"},
68
- {"criterion": "npm run build completes without errors", "pass": true, "evidence": "build exit code 0"}
69
- ]
70
- },
71
- "TASK-002": {
72
- "status": "fail",
73
- "criteria": [
74
- {"criterion": "GET /api/health returns 200", "pass": true, "evidence": "curl test passed"},
75
- {"criterion": "Response includes version field", "pass": false, "evidence": "Response body missing 'version' key"}
76
- ]
77
- }
78
- },
79
- "must_haves": {
80
- "truths": [{"claim": "...", "verified": true}],
81
- "artifacts": [{"path": "...", "exists": true, "substantial": true}],
82
- "key_links": [{"from": "...", "to": "...", "connected": false}]
83
- },
84
- "gaps": [
85
- {"layer": "connection", "description": "Router not mounted in app.ts", "severity": "high", "task": "TASK-002"}
86
- ]
87
- }
88
- ```
89
-
90
- ## Constraints
91
- - Read-only; never modify project files
92
- - Every check must have evidence (file:line reference or command output)
93
- - Layer 2 checks must go beyond file existence (actually read content)
94
- - Layer 3 checks must trace import/require chains
95
- - Verify each `convergence.criteria` item from task JSON individually
96
- - Report gaps with severity (high/medium/low), specific location, and originating task ID
97
- - Do not suggest fixes; only identify gaps
98
-
99
- ## Schema Reference
100
- - **Task schema**: `templates/task.json` -- Used to locate `convergence.criteria` and `files` for verification
101
- - Key fields consumed during verification:
102
- - `convergence.criteria` -- Array of testable conditions to check per task (replaces deprecated `done_when`)
103
- - `convergence.verification` -- Command or steps to run for automated checking
104
- - `files[].{path, action, target}` -- Expected file operations to verify
105
- - `status` -- Top-level task status (only verify tasks with status "completed")
106
- - **Verification template**: `templates/verification.json` -- Output format reference
107
-
108
- ## Output Location
109
- - **Phase-scoped verification**: `.workflow/phases/{NN}-{slug}/verification.json`
110
- - **Scratch verification**: `.workflow/scratch/{slug}/verification.json`
111
- - **Per-task verification**: Embedded in the `convergence_check` block within verification.json (not separate files)
112
-
113
- ## Error Behavior
114
- - **Task JSON missing or malformed**: Skip task, log as gap with severity "high" and description "Task definition missing or unreadable"
115
- - **convergence.verification command fails**: Log command error output as evidence, mark criterion as "fail"
116
- - **Cannot determine pass/fail for a criterion**: Mark as "inconclusive" with explanation; count as fail for overall status
117
- - **Build/test environment unavailable**: Log as gap with severity "medium", skip automated checks, perform static checks only
118
- - **All tasks pass all layers**: Set status to "pass" and report clean verification
119
- - **Any gap found**: Set status to "fail" regardless of gap severity; list all gaps for resolution
1
+ ---
2
+ name: workflow-verifier
3
+ description: Goal-backward verification across three layers (existence, substance, connection)
4
+ allowed-tools:
5
+ - Read
6
+ - Glob
7
+ - Grep
8
+ - Bash
9
+ ---
10
+
11
+ # Workflow Verifier
12
+
13
+ ## Role
14
+ You perform goal-backward verification of completed work using a three-layer checking approach. You verify that artifacts exist, contain real substance, and are properly connected to the rest of the system. You also validate each task's convergence criteria individually. You are read-only and never modify project files.
15
+
16
+ ## Search Tools
17
+ @~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
18
+
19
+ ## Process
20
+
21
+ 1. **Load goals** -- Read the phase/task goals, success criteria, must_haves, and `convergence.criteria` from each task JSON
22
+ 2. **Layer 1 - Existence** -- Verify all expected artifacts exist:
23
+ - Files created as specified in task `files[].path` where `files[].action` is "create"
24
+ - Functions/classes/modules present at `files[].target`
25
+ - Configuration entries added
26
+ 3. **Layer 2 - Substance** -- Verify artifacts are non-trivial:
27
+ - Files contain meaningful implementation (not stubs or TODOs)
28
+ - Functions have real logic (not empty bodies or pass-through)
29
+ - Tests actually test behavior (not empty test cases)
30
+ 4. **Layer 3 - Connection** -- Verify artifacts are properly wired:
31
+ - Imports resolve correctly
32
+ - New modules are registered/exported
33
+ - Routes are mounted, handlers are connected
34
+ - Configuration is loaded and used
35
+ 5. **Per-task convergence validation** -- For each completed task, verify every item in `convergence.criteria`:
36
+ - Run `convergence.verification` command if defined
37
+ - Check each criterion individually (pass/fail with evidence)
38
+ - Cross-reference with task summaries in `.summaries/`
39
+ 6. **Check must_haves** -- Verify each must_have category:
40
+ - `truths`: Invariants that must hold
41
+ - `artifacts`: Files/outputs that must exist
42
+ - `key_links`: Connections that must be wired
43
+ 7. **Write report** -- Output verification.json with results
44
+
45
+ ## Input
46
+ - Phase or task goals with must_haves definition
47
+ - `.task/TASK-{NNN}.json` files with `convergence.criteria` to validate
48
+ - Completed code/artifacts to verify
49
+ - Task summaries from `.summaries/`
50
+ - **Project specs** — `maestro spec load --category validation`: verification criteria, acceptance standards. Must verify code complies with loaded constraints.
51
+
52
+ ## Output
53
+ `verification.json`:
54
+ ```json
55
+ {
56
+ "phase": "<phase-id>",
57
+ "status": "pass|fail",
58
+ "layers": {
59
+ "existence": {"pass": true, "checks": [...]},
60
+ "substance": {"pass": true, "checks": [...]},
61
+ "connection": {"pass": false, "checks": [...]}
62
+ },
63
+ "convergence_check": {
64
+ "TASK-001": {
65
+ "status": "pass",
66
+ "criteria": [
67
+ {"criterion": "File src/tools/new-tool.ts exports NewTool class", "pass": true, "evidence": "grep confirms export at line 15"},
68
+ {"criterion": "npm run build completes without errors", "pass": true, "evidence": "build exit code 0"}
69
+ ]
70
+ },
71
+ "TASK-002": {
72
+ "status": "fail",
73
+ "criteria": [
74
+ {"criterion": "GET /api/health returns 200", "pass": true, "evidence": "curl test passed"},
75
+ {"criterion": "Response includes version field", "pass": false, "evidence": "Response body missing 'version' key"}
76
+ ]
77
+ }
78
+ },
79
+ "must_haves": {
80
+ "truths": [{"claim": "...", "verified": true}],
81
+ "artifacts": [{"path": "...", "exists": true, "substantial": true}],
82
+ "key_links": [{"from": "...", "to": "...", "connected": false}]
83
+ },
84
+ "gaps": [
85
+ {"layer": "connection", "description": "Router not mounted in app.ts", "severity": "high", "task": "TASK-002"}
86
+ ]
87
+ }
88
+ ```
89
+
90
+ ## Constraints
91
+ - Read-only; never modify project files
92
+ - Every check must have evidence (file:line reference or command output)
93
+ - Layer 2 checks must go beyond file existence (actually read content)
94
+ - Layer 3 checks must trace import/require chains
95
+ - Verify each `convergence.criteria` item from task JSON individually
96
+ - Report gaps with severity (high/medium/low), specific location, and originating task ID
97
+ - Do not suggest fixes; only identify gaps
98
+
99
+ ## Schema Reference
100
+ - **Task schema**: `templates/task.json` -- Used to locate `convergence.criteria` and `files` for verification
101
+ - Key fields consumed during verification:
102
+ - `convergence.criteria` -- Array of testable conditions to check per task (replaces deprecated `done_when`)
103
+ - `convergence.verification` -- Command or steps to run for automated checking
104
+ - `files[].{path, action, target}` -- Expected file operations to verify
105
+ - `status` -- Top-level task status (only verify tasks with status "completed")
106
+ - **Verification template**: `templates/verification.json` -- Output format reference
107
+
108
+ ## Output Location
109
+ - **Scratch verification**: `.workflow/scratch/{slug}/verification.json`
110
+ - **Legacy fallback**: `.workflow/phases/{NN}-{slug}/` paths are still recognized for backward compatibility
111
+ - **Per-task verification**: Embedded in the `convergence_check` block within verification.json (not separate files)
112
+
113
+ ## Error Behavior
114
+ - **Task JSON missing or malformed**: Skip task, log as gap with severity "high" and description "Task definition missing or unreadable"
115
+ - **convergence.verification command fails**: Log command error output as evidence, mark criterion as "fail"
116
+ - **Cannot determine pass/fail for a criterion**: Mark as "inconclusive" with explanation; count as fail for overall status
117
+ - **Build/test environment unavailable**: Log as gap with severity "medium", skip automated checks, perform static checks only
118
+ - **All tasks pass all layers**: Set status to "pass" and report clean verification
119
+ - **Any gap found**: Set status to "fail" regardless of gap severity; list all gaps for resolution
@@ -52,7 +52,7 @@ Arguments: $ARGUMENTS
52
52
  - `.workflow/learning/lessons.jsonl` — Existing insights for dedup
53
53
  - `maestro wiki list --type spec --json` — Spec entries (decision lens)
54
54
  - `.workflow/specs/architecture-constraints.md` — Documented architectural decisions (decision lens)
55
- - `.workflow/phases/*/context.md` — Phase context with Locked/Free/Deferred decisions (decision lens)
55
+ - Phase context with Locked/Free/Deferred decisions (decision lens) — resolve via `state.json.artifacts[]` scratch paths, fallback to `.workflow/phases/*/context.md`
56
56
  </context>
57
57
 
58
58
  <execution>
@@ -146,7 +146,7 @@ git log --oneline --all --grep="decision\|chose\|decided\|architecture" -20
146
146
 
147
147
  Also read:
148
148
  - `.workflow/specs/architecture-constraints.md` — grep for `<spec-entry category="arch"` blocks
149
- - `.workflow/phases/*/context.md` — scan for "Locked:", "Deferred:" sections
149
+ - Phase context files — resolve via `state.json.artifacts[]` scratch paths (fallback: `.workflow/phases/*/context.md`) — scan for "Locked:", "Deferred:" sections
150
150
  - `.workflow/learning/lessons.jsonl` — filter `category == "decision"`
151
151
 
152
152
  Apply scope filter (--phase, --tag, --id).
@@ -28,7 +28,7 @@ Arguments: $ARGUMENTS
28
28
  - File path → analyze that file's content
29
29
  - Wiki ID (`<type>-<slug>`) → fetch via `maestro wiki get`
30
30
  - `HEAD` or `staged` → analyze current git diff (`git diff HEAD` or `git diff --staged`)
31
- - Phase number (e.g., `3`) → analyze phase plan from `.workflow/phases/{NN}-*/plan.json`
31
+ - Phase number (e.g., `3`) → resolve via `state.json.artifacts[]` to find plan in scratch dir; fallback to `.workflow/phases/{NN}-*/plan.json`
32
32
 
33
33
  **Flags:**
34
34
  - `--mode review` — 3-persona parallel review (default)
@@ -54,7 +54,7 @@ Arguments: $ARGUMENTS
54
54
  - Wiki ID: `maestro wiki get <id>`
55
55
  - `HEAD`: `git diff HEAD` (unstaged + staged changes)
56
56
  - `staged`: `git diff --staged`
57
- - Phase N: Read `.workflow/phases/{NN}-*/plan.json`
57
+ - Phase N: Resolve via `state.json.artifacts.find(a => a.type === 'plan' && a.phase === N)` → read `.workflow/{artifact.path}/plan.json`; fallback to `.workflow/phases/{NN}-*/plan.json`
58
58
  - If unresolvable, AskUserQuestion for clarification
59
59
 
60
60
  ### Stage 2: Load Context
@@ -32,6 +32,7 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
32
32
  **Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
33
33
  **All output** goes to `.workflow/scratch/brainstorm-{slug}-{date}/`.
34
34
  **Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
35
+ **Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
35
36
 
36
37
  **Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
37
38
 
@@ -1,111 +1,133 @@
1
- ---
2
- name: maestro-fork
3
- description: Create a worktree for milestone-level parallel development, or sync existing worktree with main
4
- argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
5
- allowed-tools:
6
- - Read
7
- - Write
8
- - Edit
9
- - Bash
10
- - Glob
11
- - Grep
12
- - Agent
13
- - AskUserQuestion
14
- ---
15
- <purpose>
16
- Create a git worktree for an entire milestone, enabling inter-milestone parallel development. All phases within the milestone are owned by the worktree and executed sequentially inside it.
17
-
18
- Since `.workflow/` is gitignored, this command explicitly copies project context and all milestone phase directories into the worktree. Per-phase parallelism within a milestone is NOT supported.
19
-
20
- Also supports `--sync` mode to pull latest main branch changes and shared artifacts into an active worktree (prevents source and artifact drift for long-lived worktrees).
21
-
22
- Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree.
23
- </purpose>
24
-
25
- <required_reading>
26
- @~/.maestro/workflows/fork.md
27
- </required_reading>
28
-
29
- <deferred_reading>
30
- - [worktrees.json](~/.maestro/templates/worktrees.json) — read when updating registry
31
- - [worktree-scope.json](~/.maestro/templates/worktree-scope.json) — read when writing scope marker
32
- </deferred_reading>
33
-
34
- <context>
35
- $ARGUMENTS -- milestone name and optional flags.
36
-
37
- **Modes:**
38
-
39
- | Mode | Trigger | Behavior |
40
- |------|---------|----------|
41
- | Fork | `-m 2` or `2` | Create worktree for all phases in milestone 2 |
42
- | Sync | `-m 2 --sync` | Sync existing milestone 2 worktree with main branch |
43
-
44
- **Flags:**
45
- - `-m <N>` or bare `<N>`: Milestone number (1-based, maps to `state.json.milestones[]`)
46
- - `--base <branch>`: Override base branch for worktree creation (default: HEAD)
47
- - `--sync`: Sync mode — pull main into existing worktree, re-copy shared artifacts
48
-
49
- **Milestone resolution:** `state.json.milestones[N-1]` → `{name, title, phases: [...]}`
50
-
51
- **Worktree layout:**
52
- ```
53
- .worktrees/m{N}-{slug}/
54
- ├── .workflow/
55
- │ ├── worktree-scope.json (scope marker — lists all owned phases)
56
- │ ├── state.json (scoped to this milestone)
57
- │ ├── project.md (read-only copy)
58
- │ ├── roadmap.md (read-only copy)
59
- │ ├── config.json (read-only copy)
60
- │ ├── specs/ (read-only copy)
61
- │ └── phases/
62
- │ ├── {NN}-{slug}/ (owned — all phases in milestone)
63
- └── {dep}-{dep-slug}/ (read-only dependency reference from prior milestones)
64
- └── <source code> (git worktree checkout)
65
- ```
66
- </context>
67
-
68
- <execution>
69
- Follow '~/.maestro/workflows/fork.md' completely.
70
-
71
- **Next-step routing on completion:**
72
-
73
- Fork mode:
74
- - Enter worktree → `cd {wt.path} && /maestro-analyze {first_phase}`
75
- - Automated → `maestro delegate "run full lifecycle for milestone" --cd {wt.path} --mode write`
76
- - Status Skill({ skill: "manage-status" })
77
-
78
- Sync mode:
79
- - Sync complete resume work in worktree
80
- - Conflicts found resolve manually, then retry
81
- </execution>
82
-
83
- <error_codes>
84
- | Code | Severity | Condition | Recovery |
85
- |------|----------|-----------|----------|
86
- | E001 | error | Project not initialized | Run maestro-init first |
87
- | E002 | error | No roadmap found | Run maestro-roadmap first |
88
- | E003 | error | Running inside a worktree | Run from main worktree |
89
- | E004 | error | No milestone number provided | Provide `-m <N>` |
90
- | E005 | error | No milestones defined in state.json | Run maestro-roadmap first |
91
- | E006 | error | Milestone number out of range | Check available milestones |
92
- | E007 | error | No active worktree for milestone (--sync) | Check worktrees.json |
93
- | E008 | error | Milestone already has active worktree | Merge or cleanup first |
94
- </error_codes>
95
-
96
- <success_criteria>
97
- Fork mode:
98
- - [ ] Milestone phases identified from roadmap
99
- - [ ] Git worktree created with branch (`milestone/{slug}`)
100
- - [ ] `.workflow/` context copied into worktree (all milestone phases + dependency phases)
101
- - [ ] `worktree-scope.json` written with all owned phase numbers
102
- - [ ] Scoped `state.json` written (current_phase = first pending phase)
103
- - [ ] `worktrees.json` registry updated in main worktree
104
- - [ ] Milestone phase indexes marked as "forked" in main worktree
105
- - [ ] Summary displayed with next-step commands
106
-
107
- Sync mode:
108
- - [ ] Git merge main into worktree branch
109
- - [ ] Shared artifacts re-copied (project.md, roadmap.md, config.json, specs/)
110
- - [ ] Conflicts reported if any
111
- </success_criteria>
1
+ ---
2
+ name: maestro-fork
3
+ description: Create a worktree for milestone-level parallel development, or sync existing worktree with main
4
+ argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
5
+ allowed-tools:
6
+ - Read
7
+ - Write
8
+ - Edit
9
+ - Bash
10
+ - Glob
11
+ - Grep
12
+ - Agent
13
+ - AskUserQuestion
14
+ ---
15
+ <purpose>
16
+ Create a git worktree for an entire milestone, enabling inter-milestone parallel development. The worktree scope is milestone-level — all scratch artifacts for that milestone are owned by the worktree.
17
+
18
+ Since `.workflow/` is gitignored, this command explicitly copies project context and existing milestone scratch artifacts into the worktree. Per-phase parallelism within a milestone is NOT supported.
19
+
20
+ Also supports `--sync` mode to pull latest main branch changes and shared artifacts into an active worktree (prevents source and artifact drift for long-lived worktrees).
21
+
22
+ Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree.
23
+ </purpose>
24
+
25
+ <required_reading>
26
+ @~/.maestro/workflows/fork.md
27
+ </required_reading>
28
+
29
+ <deferred_reading>
30
+ - [worktrees.json](~/.maestro/templates/worktrees.json) — read when updating registry
31
+ - [worktree-scope.json](~/.maestro/templates/worktree-scope.json) — read when writing scope marker
32
+ </deferred_reading>
33
+
34
+ <context>
35
+ $ARGUMENTS -- milestone name and optional flags.
36
+
37
+ **Modes:**
38
+
39
+ | Mode | Trigger | Behavior |
40
+ |------|---------|----------|
41
+ | Fork | `-m 2` or `2` | Create worktree for milestone 2 |
42
+ | Sync | `-m 2 --sync` | Sync existing milestone 2 worktree with main branch |
43
+
44
+ **Flags:**
45
+ - `-m <N>` or bare `<N>`: Milestone number (1-based, maps to `state.json.milestones[]`)
46
+ - `--base <branch>`: Override base branch for worktree creation (default: HEAD)
47
+ - `--sync`: Sync mode — pull main into existing worktree, re-copy shared artifacts
48
+
49
+ **Milestone resolution:** `state.json.milestones[N-1]` → `{id, name, status}`
50
+
51
+ **Worktree layout:**
52
+ ```
53
+ .worktrees/m{N}-{slug}/
54
+ ├── .workflow/
55
+ │ ├── worktree-scope.json (milestone scope marker)
56
+ │ ├── state.json (scoped only this milestone's artifacts)
57
+ │ ├── project.md (read-only copy)
58
+ │ ├── roadmap.md (read-only copy)
59
+ │ ├── config.json (read-only copy)
60
+ │ ├── specs/ (read-only copy)
61
+ │ └── scratch/ (milestone's existing + new artifacts)
62
+ │ ├── analyze-auth-2026-04-20/
63
+ ├── plan-auth-2026-04-20/
64
+ └── ...
65
+ └── <source code> (git worktree checkout)
66
+ ```
67
+
68
+ **Artifact scoping:**
69
+ Fork copies scratch artifacts that belong to the target milestone (filtered from `state.json.artifacts[]` where `milestone == target`). New work in the worktree creates scratch artifacts normally; they are registered in the worktree's local `state.json`.
70
+ </context>
71
+
72
+ <execution>
73
+ Follow '~/.maestro/workflows/fork.md' completely.
74
+
75
+ **Fork flow:**
76
+ 1. Validate: project initialized, roadmap exists, not inside worktree, milestone not already forked
77
+ 2. Resolve milestone: `state.json.milestones[N-1]`
78
+ 3. Create git worktree: `git worktree add -b milestone/{slug} .worktrees/m{N}-{slug} HEAD`
79
+ 4. Copy `.workflow/` into worktree:
80
+ - Shared files (read-only): `project.md`, `roadmap.md`, `config.json`, `specs/`
81
+ - Milestone scratch artifacts: filter `state.json.artifacts[]` by `milestone == target`, copy each `scratch/{path}`
82
+ 5. Write scope marker: `worktree-scope.json` with milestone number and main path
83
+ 6. Write scoped `state.json`: only this milestone's artifacts, `current_milestone` set
84
+ 7. Update main: `worktrees.json` registry, mark milestone as `"forked"` in `state.json.milestones[]`
85
+
86
+ **Sync flow:**
87
+ 1. Find worktree from `worktrees.json`
88
+ 2. `cd worktree && git merge main`
89
+ 3. Re-copy shared files: `project.md`, `roadmap.md`, `config.json`, `specs/`
90
+ 4. Report conflicts if any
91
+
92
+ **Next-step routing on completion:**
93
+
94
+ Fork mode:
95
+ - Enter worktree → `cd {wt.path} && /maestro-analyze`
96
+ - Automated → `maestro delegate "run full lifecycle for milestone" --cd {wt.path} --mode write`
97
+ - Status → Skill({ skill: "manage-status" })
98
+
99
+ Sync mode:
100
+ - Sync complete resume work in worktree
101
+ - Conflicts found resolve manually, then retry
102
+ </execution>
103
+
104
+ <error_codes>
105
+ | Code | Severity | Condition | Recovery |
106
+ |------|----------|-----------|----------|
107
+ | E001 | error | Project not initialized | Run maestro-init first |
108
+ | E002 | error | No roadmap found | Run maestro-roadmap first |
109
+ | E003 | error | Running inside a worktree | Run from main worktree |
110
+ | E004 | error | No milestone number provided | Provide `-m <N>` |
111
+ | E005 | error | No milestones defined in state.json | Run maestro-roadmap first |
112
+ | E006 | error | Milestone number out of range | Check available milestones |
113
+ | E007 | error | No active worktree for milestone (--sync) | Check worktrees.json |
114
+ | E008 | error | Milestone already has active worktree | Merge or cleanup first |
115
+ </error_codes>
116
+
117
+ <success_criteria>
118
+ Fork mode:
119
+ - [ ] Milestone resolved from state.json.milestones[]
120
+ - [ ] Git worktree created with branch (`milestone/{slug}`)
121
+ - [ ] Shared `.workflow/` files copied (project.md, roadmap.md, config.json, specs/)
122
+ - [ ] Milestone scratch artifacts copied (filtered from artifact registry)
123
+ - [ ] `worktree-scope.json` written with milestone scope
124
+ - [ ] Scoped `state.json` written (only this milestone's artifacts)
125
+ - [ ] `worktrees.json` registry updated in main worktree
126
+ - [ ] Milestone marked as `"forked"` in main `state.json.milestones[]`
127
+ - [ ] Summary displayed with next-step commands
128
+
129
+ Sync mode:
130
+ - [ ] Git merge main into worktree branch
131
+ - [ ] Shared artifacts re-copied (project.md, roadmap.md, config.json, specs/)
132
+ - [ ] Conflicts reported if any
133
+ </success_criteria>