@josstei/maestro 1.6.4-nightly.20260430

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 (655) hide show
  1. package/.agents/plugins/marketplace.json +20 -0
  2. package/CHANGELOG.md +486 -0
  3. package/EXAMPLES.md +255 -0
  4. package/GEMINI.md +251 -0
  5. package/LICENSE +201 -0
  6. package/QWEN.md +274 -0
  7. package/README.md +220 -0
  8. package/agents/accessibility_specialist.md +20 -0
  9. package/agents/analytics_engineer.md +22 -0
  10. package/agents/api_designer.md +19 -0
  11. package/agents/architect.md +19 -0
  12. package/agents/cloud_architect.md +19 -0
  13. package/agents/cobol_engineer.md +22 -0
  14. package/agents/code_reviewer.md +17 -0
  15. package/agents/coder.md +22 -0
  16. package/agents/compliance_reviewer.md +19 -0
  17. package/agents/content_strategist.md +19 -0
  18. package/agents/copywriter.md +19 -0
  19. package/agents/data_engineer.md +22 -0
  20. package/agents/database_administrator.md +21 -0
  21. package/agents/db2_dba.md +21 -0
  22. package/agents/debugger.md +19 -0
  23. package/agents/design_system_engineer.md +22 -0
  24. package/agents/devops_engineer.md +23 -0
  25. package/agents/hlasm_assembler_specialist.md +22 -0
  26. package/agents/i18n_specialist.md +21 -0
  27. package/agents/ibm_i_specialist.md +22 -0
  28. package/agents/integration_engineer.md +23 -0
  29. package/agents/ml_engineer.md +23 -0
  30. package/agents/mlops_engineer.md +23 -0
  31. package/agents/mobile_engineer.md +23 -0
  32. package/agents/observability_engineer.md +23 -0
  33. package/agents/performance_engineer.md +21 -0
  34. package/agents/platform_engineer.md +24 -0
  35. package/agents/product_manager.md +20 -0
  36. package/agents/prompt_engineer.md +22 -0
  37. package/agents/refactor.md +22 -0
  38. package/agents/release_manager.md +22 -0
  39. package/agents/security_engineer.md +21 -0
  40. package/agents/seo_specialist.md +21 -0
  41. package/agents/site_reliability_engineer.md +21 -0
  42. package/agents/solutions_architect.md +19 -0
  43. package/agents/technical_writer.md +21 -0
  44. package/agents/tester.md +23 -0
  45. package/agents/ux_designer.md +20 -0
  46. package/agents/zos_sysprog.md +21 -0
  47. package/bin/maestro-mcp-server.js +10 -0
  48. package/claude/.claude-plugin/plugin.json +21 -0
  49. package/claude/.mcp.json +11 -0
  50. package/claude/README.md +191 -0
  51. package/claude/agents/accessibility-specialist.md +36 -0
  52. package/claude/agents/analytics-engineer.md +38 -0
  53. package/claude/agents/api-designer.md +33 -0
  54. package/claude/agents/architect.md +33 -0
  55. package/claude/agents/cloud-architect.md +33 -0
  56. package/claude/agents/cobol-engineer.md +38 -0
  57. package/claude/agents/code-reviewer.md +31 -0
  58. package/claude/agents/coder.md +38 -0
  59. package/claude/agents/compliance-reviewer.md +33 -0
  60. package/claude/agents/content-strategist.md +33 -0
  61. package/claude/agents/copywriter.md +33 -0
  62. package/claude/agents/data-engineer.md +37 -0
  63. package/claude/agents/database-administrator.md +37 -0
  64. package/claude/agents/db2-dba.md +37 -0
  65. package/claude/agents/debugger.md +32 -0
  66. package/claude/agents/design-system-engineer.md +38 -0
  67. package/claude/agents/devops-engineer.md +39 -0
  68. package/claude/agents/hlasm-assembler-specialist.md +38 -0
  69. package/claude/agents/i18n-specialist.md +37 -0
  70. package/claude/agents/ibm-i-specialist.md +38 -0
  71. package/claude/agents/integration-engineer.md +39 -0
  72. package/claude/agents/ml-engineer.md +39 -0
  73. package/claude/agents/mlops-engineer.md +39 -0
  74. package/claude/agents/mobile-engineer.md +39 -0
  75. package/claude/agents/observability-engineer.md +39 -0
  76. package/claude/agents/performance-engineer.md +34 -0
  77. package/claude/agents/platform-engineer.md +40 -0
  78. package/claude/agents/product-manager.md +34 -0
  79. package/claude/agents/prompt-engineer.md +38 -0
  80. package/claude/agents/refactor.md +38 -0
  81. package/claude/agents/release-manager.md +38 -0
  82. package/claude/agents/security-engineer.md +37 -0
  83. package/claude/agents/seo-specialist.md +37 -0
  84. package/claude/agents/site-reliability-engineer.md +37 -0
  85. package/claude/agents/solutions-architect.md +33 -0
  86. package/claude/agents/technical-writer.md +37 -0
  87. package/claude/agents/tester.md +39 -0
  88. package/claude/agents/ux-designer.md +34 -0
  89. package/claude/agents/zos-sysprog.md +37 -0
  90. package/claude/hooks/claude-hooks.json +48 -0
  91. package/claude/mcp/maestro-server.js +9 -0
  92. package/claude/mcp-config.example.json +9 -0
  93. package/claude/scripts/adapters/claude-adapter.js +7 -0
  94. package/claude/scripts/hook-runner.js +8 -0
  95. package/claude/scripts/policy-enforcer.js +294 -0
  96. package/claude/skills/a11y-audit/SKILL.md +26 -0
  97. package/claude/skills/archive/SKILL.md +24 -0
  98. package/claude/skills/code-review/SKILL.md +7 -0
  99. package/claude/skills/compliance-check/SKILL.md +26 -0
  100. package/claude/skills/debug-workflow/SKILL.md +27 -0
  101. package/claude/skills/delegation/SKILL.md +7 -0
  102. package/claude/skills/design-dialogue/SKILL.md +7 -0
  103. package/claude/skills/execute/SKILL.md +38 -0
  104. package/claude/skills/execution/SKILL.md +7 -0
  105. package/claude/skills/implementation-planning/SKILL.md +7 -0
  106. package/claude/skills/orchestrate/SKILL.md +38 -0
  107. package/claude/skills/perf-check/SKILL.md +26 -0
  108. package/claude/skills/resume-session/SKILL.md +38 -0
  109. package/claude/skills/review-code/SKILL.md +27 -0
  110. package/claude/skills/security-audit/SKILL.md +28 -0
  111. package/claude/skills/seo-audit/SKILL.md +26 -0
  112. package/claude/skills/session-management/SKILL.md +7 -0
  113. package/claude/skills/status/SKILL.md +22 -0
  114. package/claude/skills/validation/SKILL.md +7 -0
  115. package/claude/src/agents/accessibility-specialist.md +163 -0
  116. package/claude/src/agents/analytics-engineer.md +182 -0
  117. package/claude/src/agents/api-designer.md +124 -0
  118. package/claude/src/agents/architect.md +120 -0
  119. package/claude/src/agents/cloud-architect.md +134 -0
  120. package/claude/src/agents/cobol-engineer.md +127 -0
  121. package/claude/src/agents/code-reviewer.md +123 -0
  122. package/claude/src/agents/coder.md +132 -0
  123. package/claude/src/agents/compliance-reviewer.md +219 -0
  124. package/claude/src/agents/content-strategist.md +111 -0
  125. package/claude/src/agents/copywriter.md +113 -0
  126. package/claude/src/agents/data-engineer.md +130 -0
  127. package/claude/src/agents/database-administrator.md +126 -0
  128. package/claude/src/agents/db2-dba.md +124 -0
  129. package/claude/src/agents/debugger.md +133 -0
  130. package/claude/src/agents/design-system-engineer.md +258 -0
  131. package/claude/src/agents/devops-engineer.md +138 -0
  132. package/claude/src/agents/hlasm-assembler-specialist.md +134 -0
  133. package/claude/src/agents/i18n-specialist.md +241 -0
  134. package/claude/src/agents/ibm-i-specialist.md +132 -0
  135. package/claude/src/agents/integration-engineer.md +133 -0
  136. package/claude/src/agents/ml-engineer.md +115 -0
  137. package/claude/src/agents/mlops-engineer.md +116 -0
  138. package/claude/src/agents/mobile-engineer.md +115 -0
  139. package/claude/src/agents/observability-engineer.md +133 -0
  140. package/claude/src/agents/performance-engineer.md +139 -0
  141. package/claude/src/agents/platform-engineer.md +129 -0
  142. package/claude/src/agents/product-manager.md +170 -0
  143. package/claude/src/agents/prompt-engineer.md +129 -0
  144. package/claude/src/agents/refactor.md +138 -0
  145. package/claude/src/agents/release-manager.md +132 -0
  146. package/claude/src/agents/security-engineer.md +143 -0
  147. package/claude/src/agents/seo-specialist.md +129 -0
  148. package/claude/src/agents/site-reliability-engineer.md +131 -0
  149. package/claude/src/agents/solutions-architect.md +137 -0
  150. package/claude/src/agents/technical-writer.md +129 -0
  151. package/claude/src/agents/tester.md +135 -0
  152. package/claude/src/agents/ux-designer.md +168 -0
  153. package/claude/src/agents/zos-sysprog.md +134 -0
  154. package/claude/src/config/setting-resolver.js +32 -0
  155. package/claude/src/core/agent-registry.js +67 -0
  156. package/claude/src/core/canonical-source.js +39 -0
  157. package/claude/src/core/env-file-parser.js +82 -0
  158. package/claude/src/core/feature-blocks.js +34 -0
  159. package/claude/src/core/logger.js +12 -0
  160. package/claude/src/core/markdown-state.js +36 -0
  161. package/claude/src/core/policy-rules.js +32 -0
  162. package/claude/src/core/project-root-resolver.js +184 -0
  163. package/claude/src/core/stdin-reader.js +77 -0
  164. package/claude/src/core/version.js +50 -0
  165. package/claude/src/entry-points/core-command-registry.js +37 -0
  166. package/claude/src/entry-points/preamble-builders.js +54 -0
  167. package/claude/src/entry-points/registry.js +199 -0
  168. package/claude/src/entry-points/templates/claude-core-command.md.tmpl +38 -0
  169. package/claude/src/entry-points/templates/claude-skill.md.tmpl +18 -0
  170. package/claude/src/entry-points/templates/codex-core-command.md.tmpl +16 -0
  171. package/claude/src/entry-points/templates/codex-skill.md.tmpl +11 -0
  172. package/claude/src/entry-points/templates/gemini-command.toml.tmpl +17 -0
  173. package/claude/src/entry-points/templates/gemini-core-command.toml.tmpl +30 -0
  174. package/claude/src/generated/agent-registry.json +630 -0
  175. package/claude/src/generated/hook-registry.json +18 -0
  176. package/claude/src/generated/resource-registry.json +16 -0
  177. package/claude/src/hooks/logic/after-agent-logic.js +54 -0
  178. package/claude/src/hooks/logic/before-agent-logic.js +57 -0
  179. package/claude/src/hooks/logic/hook-state.js +127 -0
  180. package/claude/src/hooks/logic/session-end-logic.js +17 -0
  181. package/claude/src/hooks/logic/session-start-logic.js +25 -0
  182. package/claude/src/lib/discovery/index.js +172 -0
  183. package/claude/src/lib/errors/index.js +104 -0
  184. package/claude/src/lib/framework-detection.js +50 -0
  185. package/claude/src/lib/frontmatter/index.js +262 -0
  186. package/claude/src/lib/io/index.js +96 -0
  187. package/claude/src/lib/naming/index.js +94 -0
  188. package/claude/src/lib/validation/index.js +124 -0
  189. package/claude/src/lib/yaml-emit.js +38 -0
  190. package/claude/src/mcp/content/provider.js +68 -0
  191. package/claude/src/mcp/content/runtime-content.js +188 -0
  192. package/claude/src/mcp/contracts/cache-path-rejector.js +39 -0
  193. package/claude/src/mcp/contracts/downstream-context.js +106 -0
  194. package/claude/src/mcp/contracts/plan-schema.js +148 -0
  195. package/claude/src/mcp/contracts/workspace-marker.js +61 -0
  196. package/claude/src/mcp/core/create-server.js +76 -0
  197. package/claude/src/mcp/core/line-reader.js +35 -0
  198. package/claude/src/mcp/core/project-root-cache.js +120 -0
  199. package/claude/src/mcp/core/protocol-dispatcher.js +274 -0
  200. package/claude/src/mcp/core/recovery-hints.js +43 -0
  201. package/claude/src/mcp/core/tool-outcome.js +77 -0
  202. package/claude/src/mcp/core/tool-registry.js +82 -0
  203. package/claude/src/mcp/handlers/assess-task-complexity.js +108 -0
  204. package/claude/src/mcp/handlers/blocker-parser.js +34 -0
  205. package/claude/src/mcp/handlers/design-gate.js +393 -0
  206. package/claude/src/mcp/handlers/get-agent.js +54 -0
  207. package/claude/src/mcp/handlers/get-runtime-context.js +49 -0
  208. package/claude/src/mcp/handlers/get-skill-content.js +51 -0
  209. package/claude/src/mcp/handlers/initialize-workspace.js +45 -0
  210. package/claude/src/mcp/handlers/reconciliation.js +224 -0
  211. package/claude/src/mcp/handlers/resolve-settings.js +39 -0
  212. package/claude/src/mcp/handlers/session-state-core.js +108 -0
  213. package/claude/src/mcp/handlers/session-state-tools.js +562 -0
  214. package/claude/src/mcp/handlers/validate-plan.js +76 -0
  215. package/claude/src/mcp/maestro-server.js +122 -0
  216. package/claude/src/mcp/runtime/runtime-config-map.js +70 -0
  217. package/claude/src/mcp/tool-packs/content/index.js +80 -0
  218. package/claude/src/mcp/tool-packs/contracts.js +30 -0
  219. package/claude/src/mcp/tool-packs/index.js +15 -0
  220. package/claude/src/mcp/tool-packs/session/index.js +243 -0
  221. package/claude/src/mcp/tool-packs/workspace/index.js +98 -0
  222. package/claude/src/mcp/utils/extension-root.js +31 -0
  223. package/claude/src/mcp/validation/agent-checker.js +81 -0
  224. package/claude/src/mcp/validation/dag-checker.js +214 -0
  225. package/claude/src/mcp/validation/file-overlap-checker.js +63 -0
  226. package/claude/src/mcp/validation/schema-checker.js +108 -0
  227. package/claude/src/platforms/claude/runtime-config.js +60 -0
  228. package/claude/src/platforms/shared/adapters/claude-adapter.js +36 -0
  229. package/claude/src/platforms/shared/adapters/conventions.js +29 -0
  230. package/claude/src/platforms/shared/adapters/exit-codes.js +6 -0
  231. package/claude/src/platforms/shared/adapters/factory.js +40 -0
  232. package/claude/src/platforms/shared/agent-names.js +15 -0
  233. package/claude/src/platforms/shared/hook-runner.js +52 -0
  234. package/claude/src/references/architecture.md +139 -0
  235. package/claude/src/references/orchestration-steps.md +193 -0
  236. package/claude/src/skills/shared/code-review/SKILL.md +145 -0
  237. package/claude/src/skills/shared/delegation/SKILL.md +387 -0
  238. package/claude/src/skills/shared/delegation/protocols/agent-base-protocol.md +145 -0
  239. package/claude/src/skills/shared/delegation/protocols/filesystem-safety-protocol.md +31 -0
  240. package/claude/src/skills/shared/design-dialogue/SKILL.md +284 -0
  241. package/claude/src/skills/shared/execution/SKILL.md +258 -0
  242. package/claude/src/skills/shared/implementation-planning/SKILL.md +307 -0
  243. package/claude/src/skills/shared/session-management/SKILL.md +314 -0
  244. package/claude/src/skills/shared/validation/SKILL.md +204 -0
  245. package/claude/src/state/session-state.js +113 -0
  246. package/claude/src/templates/design-document.md +95 -0
  247. package/claude/src/templates/implementation-plan.md +86 -0
  248. package/claude/src/templates/session-state.md +68 -0
  249. package/claude/src/version.json +3 -0
  250. package/commands/maestro/a11y-audit.toml +22 -0
  251. package/commands/maestro/archive.toml +23 -0
  252. package/commands/maestro/compliance-check.toml +22 -0
  253. package/commands/maestro/debug.toml +23 -0
  254. package/commands/maestro/execute.toml +30 -0
  255. package/commands/maestro/orchestrate.toml +30 -0
  256. package/commands/maestro/perf-check.toml +22 -0
  257. package/commands/maestro/resume.toml +38 -0
  258. package/commands/maestro/review.toml +23 -0
  259. package/commands/maestro/security-audit.toml +24 -0
  260. package/commands/maestro/seo-audit.toml +22 -0
  261. package/commands/maestro/status.toml +21 -0
  262. package/docs/architecture.md +323 -0
  263. package/docs/cicd.md +658 -0
  264. package/docs/flow.md +266 -0
  265. package/docs/maestro-cheatsheet.md +207 -0
  266. package/docs/overview.md +141 -0
  267. package/docs/runtime-claude.md +190 -0
  268. package/docs/runtime-codex.md +197 -0
  269. package/docs/runtime-gemini.md +173 -0
  270. package/docs/runtime-qwen.md +150 -0
  271. package/docs/usage.md +315 -0
  272. package/gemini-extension.json +56 -0
  273. package/hooks/adapters/gemini-adapter.js +2 -0
  274. package/hooks/adapters/qwen-adapter.js +2 -0
  275. package/hooks/hook-runner.js +3 -0
  276. package/hooks/hooks.json +56 -0
  277. package/mcp/maestro-server.js +4 -0
  278. package/package.json +93 -0
  279. package/plugins/maestro/.app.json +3 -0
  280. package/plugins/maestro/.codex-plugin/plugin.json +41 -0
  281. package/plugins/maestro/.mcp.json +16 -0
  282. package/plugins/maestro/README.md +57 -0
  283. package/plugins/maestro/references/runtime-guide.md +125 -0
  284. package/plugins/maestro/skills/a11y-audit/SKILL.md +16 -0
  285. package/plugins/maestro/skills/archive/SKILL.md +16 -0
  286. package/plugins/maestro/skills/code-review/SKILL.md +6 -0
  287. package/plugins/maestro/skills/compliance-check/SKILL.md +16 -0
  288. package/plugins/maestro/skills/debug-workflow/SKILL.md +16 -0
  289. package/plugins/maestro/skills/delegation/SKILL.md +6 -0
  290. package/plugins/maestro/skills/design-dialogue/SKILL.md +6 -0
  291. package/plugins/maestro/skills/execute/SKILL.md +16 -0
  292. package/plugins/maestro/skills/execution/SKILL.md +6 -0
  293. package/plugins/maestro/skills/implementation-planning/SKILL.md +6 -0
  294. package/plugins/maestro/skills/orchestrate/SKILL.md +16 -0
  295. package/plugins/maestro/skills/perf-check/SKILL.md +16 -0
  296. package/plugins/maestro/skills/resume-session/SKILL.md +16 -0
  297. package/plugins/maestro/skills/review-code/SKILL.md +16 -0
  298. package/plugins/maestro/skills/security-audit/SKILL.md +16 -0
  299. package/plugins/maestro/skills/seo-audit/SKILL.md +16 -0
  300. package/plugins/maestro/skills/session-management/SKILL.md +6 -0
  301. package/plugins/maestro/skills/status/SKILL.md +14 -0
  302. package/plugins/maestro/skills/validation/SKILL.md +6 -0
  303. package/plugins/maestro/src/agents/accessibility-specialist.md +163 -0
  304. package/plugins/maestro/src/agents/analytics-engineer.md +182 -0
  305. package/plugins/maestro/src/agents/api-designer.md +124 -0
  306. package/plugins/maestro/src/agents/architect.md +120 -0
  307. package/plugins/maestro/src/agents/cloud-architect.md +134 -0
  308. package/plugins/maestro/src/agents/cobol-engineer.md +127 -0
  309. package/plugins/maestro/src/agents/code-reviewer.md +123 -0
  310. package/plugins/maestro/src/agents/coder.md +132 -0
  311. package/plugins/maestro/src/agents/compliance-reviewer.md +219 -0
  312. package/plugins/maestro/src/agents/content-strategist.md +111 -0
  313. package/plugins/maestro/src/agents/copywriter.md +113 -0
  314. package/plugins/maestro/src/agents/data-engineer.md +130 -0
  315. package/plugins/maestro/src/agents/database-administrator.md +126 -0
  316. package/plugins/maestro/src/agents/db2-dba.md +124 -0
  317. package/plugins/maestro/src/agents/debugger.md +133 -0
  318. package/plugins/maestro/src/agents/design-system-engineer.md +258 -0
  319. package/plugins/maestro/src/agents/devops-engineer.md +138 -0
  320. package/plugins/maestro/src/agents/hlasm-assembler-specialist.md +134 -0
  321. package/plugins/maestro/src/agents/i18n-specialist.md +241 -0
  322. package/plugins/maestro/src/agents/ibm-i-specialist.md +132 -0
  323. package/plugins/maestro/src/agents/integration-engineer.md +133 -0
  324. package/plugins/maestro/src/agents/ml-engineer.md +115 -0
  325. package/plugins/maestro/src/agents/mlops-engineer.md +116 -0
  326. package/plugins/maestro/src/agents/mobile-engineer.md +115 -0
  327. package/plugins/maestro/src/agents/observability-engineer.md +133 -0
  328. package/plugins/maestro/src/agents/performance-engineer.md +139 -0
  329. package/plugins/maestro/src/agents/platform-engineer.md +129 -0
  330. package/plugins/maestro/src/agents/product-manager.md +170 -0
  331. package/plugins/maestro/src/agents/prompt-engineer.md +129 -0
  332. package/plugins/maestro/src/agents/refactor.md +138 -0
  333. package/plugins/maestro/src/agents/release-manager.md +132 -0
  334. package/plugins/maestro/src/agents/security-engineer.md +143 -0
  335. package/plugins/maestro/src/agents/seo-specialist.md +129 -0
  336. package/plugins/maestro/src/agents/site-reliability-engineer.md +131 -0
  337. package/plugins/maestro/src/agents/solutions-architect.md +137 -0
  338. package/plugins/maestro/src/agents/technical-writer.md +129 -0
  339. package/plugins/maestro/src/agents/tester.md +135 -0
  340. package/plugins/maestro/src/agents/ux-designer.md +168 -0
  341. package/plugins/maestro/src/agents/zos-sysprog.md +134 -0
  342. package/plugins/maestro/src/config/setting-resolver.js +32 -0
  343. package/plugins/maestro/src/core/agent-registry.js +67 -0
  344. package/plugins/maestro/src/core/canonical-source.js +39 -0
  345. package/plugins/maestro/src/core/env-file-parser.js +82 -0
  346. package/plugins/maestro/src/core/feature-blocks.js +34 -0
  347. package/plugins/maestro/src/core/logger.js +12 -0
  348. package/plugins/maestro/src/core/markdown-state.js +36 -0
  349. package/plugins/maestro/src/core/policy-rules.js +32 -0
  350. package/plugins/maestro/src/core/project-root-resolver.js +184 -0
  351. package/plugins/maestro/src/core/stdin-reader.js +77 -0
  352. package/plugins/maestro/src/core/version.js +50 -0
  353. package/plugins/maestro/src/entry-points/core-command-registry.js +37 -0
  354. package/plugins/maestro/src/entry-points/preamble-builders.js +54 -0
  355. package/plugins/maestro/src/entry-points/registry.js +199 -0
  356. package/plugins/maestro/src/entry-points/templates/claude-core-command.md.tmpl +38 -0
  357. package/plugins/maestro/src/entry-points/templates/claude-skill.md.tmpl +18 -0
  358. package/plugins/maestro/src/entry-points/templates/codex-core-command.md.tmpl +16 -0
  359. package/plugins/maestro/src/entry-points/templates/codex-skill.md.tmpl +11 -0
  360. package/plugins/maestro/src/entry-points/templates/gemini-command.toml.tmpl +17 -0
  361. package/plugins/maestro/src/entry-points/templates/gemini-core-command.toml.tmpl +30 -0
  362. package/plugins/maestro/src/generated/agent-registry.json +630 -0
  363. package/plugins/maestro/src/generated/hook-registry.json +18 -0
  364. package/plugins/maestro/src/generated/resource-registry.json +16 -0
  365. package/plugins/maestro/src/hooks/logic/after-agent-logic.js +54 -0
  366. package/plugins/maestro/src/hooks/logic/before-agent-logic.js +57 -0
  367. package/plugins/maestro/src/hooks/logic/hook-state.js +127 -0
  368. package/plugins/maestro/src/hooks/logic/session-end-logic.js +17 -0
  369. package/plugins/maestro/src/hooks/logic/session-start-logic.js +25 -0
  370. package/plugins/maestro/src/lib/discovery/index.js +172 -0
  371. package/plugins/maestro/src/lib/errors/index.js +104 -0
  372. package/plugins/maestro/src/lib/framework-detection.js +50 -0
  373. package/plugins/maestro/src/lib/frontmatter/index.js +262 -0
  374. package/plugins/maestro/src/lib/io/index.js +96 -0
  375. package/plugins/maestro/src/lib/naming/index.js +94 -0
  376. package/plugins/maestro/src/lib/validation/index.js +124 -0
  377. package/plugins/maestro/src/lib/yaml-emit.js +38 -0
  378. package/plugins/maestro/src/mcp/content/provider.js +68 -0
  379. package/plugins/maestro/src/mcp/content/runtime-content.js +188 -0
  380. package/plugins/maestro/src/mcp/contracts/cache-path-rejector.js +39 -0
  381. package/plugins/maestro/src/mcp/contracts/downstream-context.js +106 -0
  382. package/plugins/maestro/src/mcp/contracts/plan-schema.js +148 -0
  383. package/plugins/maestro/src/mcp/contracts/workspace-marker.js +61 -0
  384. package/plugins/maestro/src/mcp/core/create-server.js +76 -0
  385. package/plugins/maestro/src/mcp/core/line-reader.js +35 -0
  386. package/plugins/maestro/src/mcp/core/project-root-cache.js +120 -0
  387. package/plugins/maestro/src/mcp/core/protocol-dispatcher.js +274 -0
  388. package/plugins/maestro/src/mcp/core/recovery-hints.js +43 -0
  389. package/plugins/maestro/src/mcp/core/tool-outcome.js +77 -0
  390. package/plugins/maestro/src/mcp/core/tool-registry.js +82 -0
  391. package/plugins/maestro/src/mcp/handlers/assess-task-complexity.js +108 -0
  392. package/plugins/maestro/src/mcp/handlers/blocker-parser.js +34 -0
  393. package/plugins/maestro/src/mcp/handlers/design-gate.js +393 -0
  394. package/plugins/maestro/src/mcp/handlers/get-agent.js +54 -0
  395. package/plugins/maestro/src/mcp/handlers/get-runtime-context.js +49 -0
  396. package/plugins/maestro/src/mcp/handlers/get-skill-content.js +51 -0
  397. package/plugins/maestro/src/mcp/handlers/initialize-workspace.js +45 -0
  398. package/plugins/maestro/src/mcp/handlers/reconciliation.js +224 -0
  399. package/plugins/maestro/src/mcp/handlers/resolve-settings.js +39 -0
  400. package/plugins/maestro/src/mcp/handlers/session-state-core.js +108 -0
  401. package/plugins/maestro/src/mcp/handlers/session-state-tools.js +562 -0
  402. package/plugins/maestro/src/mcp/handlers/validate-plan.js +76 -0
  403. package/plugins/maestro/src/mcp/maestro-server.js +122 -0
  404. package/plugins/maestro/src/mcp/runtime/runtime-config-map.js +70 -0
  405. package/plugins/maestro/src/mcp/tool-packs/content/index.js +80 -0
  406. package/plugins/maestro/src/mcp/tool-packs/contracts.js +30 -0
  407. package/plugins/maestro/src/mcp/tool-packs/index.js +15 -0
  408. package/plugins/maestro/src/mcp/tool-packs/session/index.js +243 -0
  409. package/plugins/maestro/src/mcp/tool-packs/workspace/index.js +98 -0
  410. package/plugins/maestro/src/mcp/utils/extension-root.js +31 -0
  411. package/plugins/maestro/src/mcp/validation/agent-checker.js +81 -0
  412. package/plugins/maestro/src/mcp/validation/dag-checker.js +214 -0
  413. package/plugins/maestro/src/mcp/validation/file-overlap-checker.js +63 -0
  414. package/plugins/maestro/src/mcp/validation/schema-checker.js +108 -0
  415. package/plugins/maestro/src/platforms/codex/runtime-config.js +58 -0
  416. package/plugins/maestro/src/platforms/shared/adapters/conventions.js +29 -0
  417. package/plugins/maestro/src/platforms/shared/adapters/exit-codes.js +6 -0
  418. package/plugins/maestro/src/platforms/shared/adapters/factory.js +40 -0
  419. package/plugins/maestro/src/platforms/shared/agent-names.js +15 -0
  420. package/plugins/maestro/src/platforms/shared/hook-runner.js +52 -0
  421. package/plugins/maestro/src/references/architecture.md +139 -0
  422. package/plugins/maestro/src/references/orchestration-steps.md +193 -0
  423. package/plugins/maestro/src/skills/shared/code-review/SKILL.md +145 -0
  424. package/plugins/maestro/src/skills/shared/delegation/SKILL.md +387 -0
  425. package/plugins/maestro/src/skills/shared/delegation/protocols/agent-base-protocol.md +145 -0
  426. package/plugins/maestro/src/skills/shared/delegation/protocols/filesystem-safety-protocol.md +31 -0
  427. package/plugins/maestro/src/skills/shared/design-dialogue/SKILL.md +284 -0
  428. package/plugins/maestro/src/skills/shared/execution/SKILL.md +258 -0
  429. package/plugins/maestro/src/skills/shared/implementation-planning/SKILL.md +307 -0
  430. package/plugins/maestro/src/skills/shared/session-management/SKILL.md +314 -0
  431. package/plugins/maestro/src/skills/shared/validation/SKILL.md +204 -0
  432. package/plugins/maestro/src/state/session-state.js +113 -0
  433. package/plugins/maestro/src/templates/design-document.md +95 -0
  434. package/plugins/maestro/src/templates/implementation-plan.md +86 -0
  435. package/plugins/maestro/src/templates/session-state.md +68 -0
  436. package/plugins/maestro/src/version.json +3 -0
  437. package/policies/maestro.toml +44 -0
  438. package/qwen/agents/accessibility_specialist.md +18 -0
  439. package/qwen/agents/analytics_engineer.md +20 -0
  440. package/qwen/agents/api_designer.md +17 -0
  441. package/qwen/agents/architect.md +17 -0
  442. package/qwen/agents/cloud_architect.md +17 -0
  443. package/qwen/agents/cobol_engineer.md +20 -0
  444. package/qwen/agents/code_reviewer.md +15 -0
  445. package/qwen/agents/coder.md +20 -0
  446. package/qwen/agents/compliance_reviewer.md +17 -0
  447. package/qwen/agents/content_strategist.md +17 -0
  448. package/qwen/agents/copywriter.md +17 -0
  449. package/qwen/agents/data_engineer.md +20 -0
  450. package/qwen/agents/database_administrator.md +19 -0
  451. package/qwen/agents/db2_dba.md +19 -0
  452. package/qwen/agents/debugger.md +17 -0
  453. package/qwen/agents/design_system_engineer.md +20 -0
  454. package/qwen/agents/devops_engineer.md +21 -0
  455. package/qwen/agents/hlasm_assembler_specialist.md +20 -0
  456. package/qwen/agents/i18n_specialist.md +19 -0
  457. package/qwen/agents/ibm_i_specialist.md +20 -0
  458. package/qwen/agents/integration_engineer.md +21 -0
  459. package/qwen/agents/ml_engineer.md +21 -0
  460. package/qwen/agents/mlops_engineer.md +21 -0
  461. package/qwen/agents/mobile_engineer.md +21 -0
  462. package/qwen/agents/observability_engineer.md +21 -0
  463. package/qwen/agents/performance_engineer.md +19 -0
  464. package/qwen/agents/platform_engineer.md +22 -0
  465. package/qwen/agents/product_manager.md +18 -0
  466. package/qwen/agents/prompt_engineer.md +20 -0
  467. package/qwen/agents/refactor.md +20 -0
  468. package/qwen/agents/release_manager.md +20 -0
  469. package/qwen/agents/security_engineer.md +19 -0
  470. package/qwen/agents/seo_specialist.md +19 -0
  471. package/qwen/agents/site_reliability_engineer.md +19 -0
  472. package/qwen/agents/solutions_architect.md +17 -0
  473. package/qwen/agents/technical_writer.md +19 -0
  474. package/qwen/agents/tester.md +21 -0
  475. package/qwen/agents/ux_designer.md +18 -0
  476. package/qwen/agents/zos_sysprog.md +19 -0
  477. package/qwen/hooks.json +56 -0
  478. package/qwen-extension.json +56 -0
  479. package/scripts/check-layer-boundaries.js +74 -0
  480. package/scripts/generate.js +155 -0
  481. package/scripts/install-codex-plugin.js +167 -0
  482. package/scripts/install-git-hooks.js +43 -0
  483. package/scripts/npm-publish-idempotent.js +338 -0
  484. package/scripts/package-release-artifacts.js +156 -0
  485. package/scripts/release-artifact-manifest.js +378 -0
  486. package/scripts/release-version-metadata.js +129 -0
  487. package/scripts/update-versions.js +33 -0
  488. package/scripts/verify-npm-pack.js +85 -0
  489. package/scripts/verify-release-artifacts.js +95 -0
  490. package/src/agents/accessibility-specialist.md +163 -0
  491. package/src/agents/analytics-engineer.md +182 -0
  492. package/src/agents/api-designer.md +124 -0
  493. package/src/agents/architect.md +120 -0
  494. package/src/agents/cloud-architect.md +134 -0
  495. package/src/agents/cobol-engineer.md +127 -0
  496. package/src/agents/code-reviewer.md +123 -0
  497. package/src/agents/coder.md +132 -0
  498. package/src/agents/compliance-reviewer.md +219 -0
  499. package/src/agents/content-strategist.md +111 -0
  500. package/src/agents/copywriter.md +113 -0
  501. package/src/agents/data-engineer.md +130 -0
  502. package/src/agents/database-administrator.md +126 -0
  503. package/src/agents/db2-dba.md +124 -0
  504. package/src/agents/debugger.md +133 -0
  505. package/src/agents/design-system-engineer.md +258 -0
  506. package/src/agents/devops-engineer.md +138 -0
  507. package/src/agents/hlasm-assembler-specialist.md +134 -0
  508. package/src/agents/i18n-specialist.md +241 -0
  509. package/src/agents/ibm-i-specialist.md +132 -0
  510. package/src/agents/integration-engineer.md +133 -0
  511. package/src/agents/ml-engineer.md +115 -0
  512. package/src/agents/mlops-engineer.md +116 -0
  513. package/src/agents/mobile-engineer.md +115 -0
  514. package/src/agents/observability-engineer.md +133 -0
  515. package/src/agents/performance-engineer.md +139 -0
  516. package/src/agents/platform-engineer.md +129 -0
  517. package/src/agents/product-manager.md +170 -0
  518. package/src/agents/prompt-engineer.md +129 -0
  519. package/src/agents/refactor.md +138 -0
  520. package/src/agents/release-manager.md +132 -0
  521. package/src/agents/security-engineer.md +143 -0
  522. package/src/agents/seo-specialist.md +129 -0
  523. package/src/agents/site-reliability-engineer.md +131 -0
  524. package/src/agents/solutions-architect.md +137 -0
  525. package/src/agents/technical-writer.md +129 -0
  526. package/src/agents/tester.md +135 -0
  527. package/src/agents/ux-designer.md +168 -0
  528. package/src/agents/zos-sysprog.md +134 -0
  529. package/src/config/setting-resolver.js +32 -0
  530. package/src/core/agent-registry.js +67 -0
  531. package/src/core/canonical-source.js +39 -0
  532. package/src/core/env-file-parser.js +82 -0
  533. package/src/core/feature-blocks.js +34 -0
  534. package/src/core/logger.js +12 -0
  535. package/src/core/markdown-state.js +36 -0
  536. package/src/core/policy-rules.js +32 -0
  537. package/src/core/project-root-resolver.js +184 -0
  538. package/src/core/stdin-reader.js +77 -0
  539. package/src/core/version.js +50 -0
  540. package/src/entry-points/core-command-registry.js +37 -0
  541. package/src/entry-points/preamble-builders.js +54 -0
  542. package/src/entry-points/registry.js +199 -0
  543. package/src/entry-points/templates/claude-core-command.md.tmpl +38 -0
  544. package/src/entry-points/templates/claude-skill.md.tmpl +18 -0
  545. package/src/entry-points/templates/codex-core-command.md.tmpl +16 -0
  546. package/src/entry-points/templates/codex-skill.md.tmpl +11 -0
  547. package/src/entry-points/templates/gemini-command.toml.tmpl +17 -0
  548. package/src/entry-points/templates/gemini-core-command.toml.tmpl +30 -0
  549. package/src/generated/agent-registry.json +630 -0
  550. package/src/generated/hook-registry.json +18 -0
  551. package/src/generated/resource-registry.json +16 -0
  552. package/src/generator/entry-point-expander.js +182 -0
  553. package/src/generator/file-writer.js +167 -0
  554. package/src/generator/generation-session.js +62 -0
  555. package/src/generator/manifest-curator.js +31 -0
  556. package/src/generator/manifest-expander.js +256 -0
  557. package/src/generator/payload-builder.js +217 -0
  558. package/src/generator/registry-scanner.js +130 -0
  559. package/src/generator/stale-pruner.js +101 -0
  560. package/src/hooks/logic/after-agent-logic.js +54 -0
  561. package/src/hooks/logic/before-agent-logic.js +57 -0
  562. package/src/hooks/logic/hook-state.js +127 -0
  563. package/src/hooks/logic/session-end-logic.js +17 -0
  564. package/src/hooks/logic/session-start-logic.js +25 -0
  565. package/src/lib/discovery/index.js +172 -0
  566. package/src/lib/errors/index.js +104 -0
  567. package/src/lib/framework-detection.js +50 -0
  568. package/src/lib/frontmatter/index.js +262 -0
  569. package/src/lib/io/index.js +96 -0
  570. package/src/lib/naming/index.js +94 -0
  571. package/src/lib/validation/index.js +124 -0
  572. package/src/lib/yaml-emit.js +38 -0
  573. package/src/manifest.js +11 -0
  574. package/src/mcp/content/provider.js +68 -0
  575. package/src/mcp/content/runtime-content.js +188 -0
  576. package/src/mcp/contracts/cache-path-rejector.js +39 -0
  577. package/src/mcp/contracts/downstream-context.js +106 -0
  578. package/src/mcp/contracts/plan-schema.js +148 -0
  579. package/src/mcp/contracts/workspace-marker.js +61 -0
  580. package/src/mcp/core/create-server.js +76 -0
  581. package/src/mcp/core/line-reader.js +35 -0
  582. package/src/mcp/core/project-root-cache.js +120 -0
  583. package/src/mcp/core/protocol-dispatcher.js +274 -0
  584. package/src/mcp/core/recovery-hints.js +43 -0
  585. package/src/mcp/core/tool-outcome.js +77 -0
  586. package/src/mcp/core/tool-registry.js +82 -0
  587. package/src/mcp/handlers/assess-task-complexity.js +108 -0
  588. package/src/mcp/handlers/blocker-parser.js +34 -0
  589. package/src/mcp/handlers/design-gate.js +393 -0
  590. package/src/mcp/handlers/get-agent.js +54 -0
  591. package/src/mcp/handlers/get-runtime-context.js +49 -0
  592. package/src/mcp/handlers/get-skill-content.js +51 -0
  593. package/src/mcp/handlers/initialize-workspace.js +45 -0
  594. package/src/mcp/handlers/reconciliation.js +224 -0
  595. package/src/mcp/handlers/resolve-settings.js +39 -0
  596. package/src/mcp/handlers/session-state-core.js +108 -0
  597. package/src/mcp/handlers/session-state-tools.js +562 -0
  598. package/src/mcp/handlers/validate-plan.js +76 -0
  599. package/src/mcp/maestro-server.js +122 -0
  600. package/src/mcp/runtime/runtime-config-map.js +70 -0
  601. package/src/mcp/tool-packs/content/index.js +80 -0
  602. package/src/mcp/tool-packs/contracts.js +30 -0
  603. package/src/mcp/tool-packs/index.js +15 -0
  604. package/src/mcp/tool-packs/session/index.js +243 -0
  605. package/src/mcp/tool-packs/workspace/index.js +98 -0
  606. package/src/mcp/utils/extension-root.js +31 -0
  607. package/src/mcp/validation/agent-checker.js +81 -0
  608. package/src/mcp/validation/dag-checker.js +214 -0
  609. package/src/mcp/validation/file-overlap-checker.js +63 -0
  610. package/src/mcp/validation/schema-checker.js +108 -0
  611. package/src/platforms/claude/metadata.js +96 -0
  612. package/src/platforms/claude/runtime-config.js +60 -0
  613. package/src/platforms/codex/metadata.js +107 -0
  614. package/src/platforms/codex/runtime-config.js +58 -0
  615. package/src/platforms/gemini/metadata.js +27 -0
  616. package/src/platforms/gemini/runtime-config.js +62 -0
  617. package/src/platforms/metadata-shared.js +133 -0
  618. package/src/platforms/metadata.js +29 -0
  619. package/src/platforms/qwen/metadata.js +27 -0
  620. package/src/platforms/qwen/runtime-config.js +62 -0
  621. package/src/platforms/shared/adapters/claude-adapter.js +36 -0
  622. package/src/platforms/shared/adapters/conventions.js +29 -0
  623. package/src/platforms/shared/adapters/exit-codes.js +6 -0
  624. package/src/platforms/shared/adapters/factory.js +40 -0
  625. package/src/platforms/shared/adapters/gemini-adapter.js +34 -0
  626. package/src/platforms/shared/adapters/qwen-adapter.js +93 -0
  627. package/src/platforms/shared/agent-names.js +15 -0
  628. package/src/platforms/shared/hook-runner.js +52 -0
  629. package/src/references/architecture.md +139 -0
  630. package/src/references/orchestration-steps.md +193 -0
  631. package/src/scripts/ensure-workspace.js +14 -0
  632. package/src/scripts/read-active-session.js +26 -0
  633. package/src/scripts/read-setting.js +18 -0
  634. package/src/scripts/read-state.js +17 -0
  635. package/src/scripts/write-state.js +22 -0
  636. package/src/skills/shared/code-review/SKILL.md +145 -0
  637. package/src/skills/shared/delegation/SKILL.md +387 -0
  638. package/src/skills/shared/delegation/protocols/agent-base-protocol.md +145 -0
  639. package/src/skills/shared/delegation/protocols/filesystem-safety-protocol.md +31 -0
  640. package/src/skills/shared/design-dialogue/SKILL.md +284 -0
  641. package/src/skills/shared/execution/SKILL.md +258 -0
  642. package/src/skills/shared/implementation-planning/SKILL.md +307 -0
  643. package/src/skills/shared/session-management/SKILL.md +314 -0
  644. package/src/skills/shared/validation/SKILL.md +204 -0
  645. package/src/state/session-state.js +113 -0
  646. package/src/templates/design-document.md +95 -0
  647. package/src/templates/implementation-plan.md +86 -0
  648. package/src/templates/session-state.md +68 -0
  649. package/src/transforms/agent-stub.js +29 -0
  650. package/src/transforms/extract-examples.js +63 -0
  651. package/src/transforms/index.js +35 -0
  652. package/src/transforms/parse-frontmatter.js +23 -0
  653. package/src/transforms/rebuild-frontmatter.js +147 -0
  654. package/src/transforms/skill-discovery-stub.js +27 -0
  655. package/src/transforms/skill-metadata.js +14 -0
@@ -0,0 +1,145 @@
1
+ ---
2
+ name: code-review
3
+ description: Standalone code review methodology for structured, severity-classified code assessment
4
+ ---
5
+
6
+ # Code Review Skill
7
+
8
+ Activate this skill when performing standalone code reviews via the runtime-specific Maestro review entrypoint or during orchestration quality gates (post-phase checks and final completion gate). This skill provides the methodology for scoping, executing, and reporting code reviews.
9
+
10
+ ## Scope Detection Protocol
11
+
12
+ Determine review scope using the following priority order:
13
+
14
+ 1. **User-specified paths**: If the user provides file paths or glob patterns, expand glob patterns using the `glob` tool to resolve them to concrete file paths before delegating to the `code-reviewer` agent
15
+ 2. **Staged changes**: If `git diff --staged` produces output, review staged changes
16
+ 3. **Last commit diff**: If no staged changes exist, review the last commit via `git diff HEAD~1`
17
+ 4. **Fallback**: If none of the above yield content, ask the user to specify scope
18
+
19
+ Always confirm the detected scope with the user before proceeding.
20
+
21
+ If scope is provided as file paths and a git diff is empty for some paths (for example, new unstaged files), include those files' current contents directly in review context so they are still reviewed.
22
+
23
+ ## Review Orchestration
24
+
25
+ ### Delegation Flow
26
+
27
+ 1. Detect review scope using the protocol above
28
+ 2. Gather the full diff content for the detected scope, and include current file contents when diff content is unavailable for scoped files
29
+ 3. Delegate to the `code-reviewer` agent with:
30
+ - The full diff content
31
+ - File paths involved
32
+ - Any user-provided focus areas or concerns
33
+ 4. Process the agent's Task Report
34
+ 5. Present findings to the user in the structured output format below
35
+
36
+ ### Context Enrichment
37
+
38
+ When delegating to the `code-reviewer` agent, include:
39
+ - The diff content (not just file names)
40
+ - Surrounding context for modified sections (10 lines before/after when available)
41
+ - Project language and framework information (detected from package.json, Cargo.toml, go.mod, etc.)
42
+
43
+ ## Severity Classification
44
+
45
+ ### Critical
46
+ Issues that could cause security vulnerabilities, data loss, or system crashes:
47
+ - SQL/NoSQL injection vectors
48
+ - Authentication/authorization bypasses
49
+ - Unvalidated user input at system boundaries
50
+ - Resource leaks (unclosed connections, file handles)
51
+ - Race conditions with data corruption potential
52
+
53
+ ### Major
54
+ Issues that cause bugs, design flaws, or significant maintainability problems:
55
+ - Logic errors in business rules
56
+ - Missing error handling on external calls
57
+ - SOLID principle violations that impact extensibility
58
+ - Incorrect API contracts or type mismatches
59
+ - Missing null/undefined checks on external data
60
+
61
+ ### Minor
62
+ Issues related to style, naming, or minor convention violations:
63
+ - Naming inconsistencies
64
+ - Code style deviations from project conventions
65
+ - Suboptimal but correct implementations
66
+ - Missing type annotations where inference is insufficient
67
+
68
+ ### Suggestion
69
+ Optional improvements that enhance readability or maintainability:
70
+ - Alternative patterns that improve clarity
71
+ - Performance optimizations with marginal impact
72
+ - Structural improvements for future extensibility
73
+
74
+ ## Output Format
75
+
76
+ Present findings in a structured table followed by a summary:
77
+
78
+ ```
79
+ ## Code Review Results
80
+
81
+ **Scope**: [description of what was reviewed]
82
+ **Files Reviewed**: [count]
83
+ **Total Findings**: [count by severity]
84
+
85
+ ### Findings
86
+
87
+ | # | Severity | File | Line | Description | Suggested Fix |
88
+ |---|----------|------|------|-------------|---------------|
89
+ | 1 | Critical | path/to/file.ts | 42 | [description] | [fix] |
90
+ | 2 | Major | path/to/file.ts | 87 | [description] | [fix] |
91
+
92
+ ### Summary
93
+
94
+ [1-2 paragraph summary of overall code quality, patterns observed, and priority actions]
95
+ ```
96
+
97
+ ## Verification Rule
98
+
99
+ Every finding **must**:
100
+ - Reference a specific file and line number
101
+ - Be verified against the actual code (not assumed from patterns)
102
+ - Include a concrete suggested fix or action
103
+ - Be classified with a severity that matches the classification criteria above
104
+
105
+ Do NOT report:
106
+ - Speculative issues based on assumptions about runtime behavior
107
+ - Style preferences not established by the project's conventions
108
+ - Issues in code outside the review scope
109
+
110
+ ## Review Scope Calibration
111
+
112
+ Calibrate the depth and focus of review based on the type of change being reviewed:
113
+
114
+ ### Calibration Rules
115
+ - **New files**: Full review across all dimensions — architecture fit, pattern compliance, security, naming conventions, error handling, testability, dependency direction
116
+ - **Modified files (behavior change)**: Focus on the diff — correctness of new behavior, regression risk, contract compliance with existing interfaces, edge case handling in new code paths
117
+ - **Modified files (refactoring)**: Focus on behavior preservation — verify same inputs produce same outputs, no unintended side effects introduced, no behavior changes disguised as refactoring
118
+ - **Deleted files**: Dependency verification — confirm no remaining code imports from, references, or depends on the deleted files. Check for orphaned tests that tested the deleted code.
119
+ - **Configuration changes**: Environment impact assessment — does this change affect production? Staging? Local development? All environments? Are there secrets or credentials involved?
120
+
121
+ ### Application
122
+ When reviewing a diff that contains multiple change types (new files + modifications + deletions), apply the appropriate calibration to each file independently. Do not apply "new file" depth to a file that only had a minor modification.
123
+
124
+ ## Finding Deduplication Protocol
125
+
126
+ When reviewing multiple files, identify and consolidate findings that share the same root cause.
127
+
128
+ ### Deduplication Rules
129
+ - If the same pattern violation appears in 3+ files, report it **once** as a systemic finding with the list of all affected locations — not as N separate findings
130
+ - A systemic finding includes: the pattern being violated, why it matters, the full list of affected file:line locations, and a single remediation recommendation that addresses all instances
131
+ - Unique findings (appearing in only 1-2 files) are reported individually as normal
132
+
133
+ ### Deduplication Format
134
+ ```
135
+ ### Systemic Finding: [Pattern Violation Name]
136
+ - **Severity**: [Critical | Major | Minor | Suggestion]
137
+ - **Description**: [What the pattern violation is and why it matters]
138
+ - **Affected Locations**:
139
+ - `path/to/file1.ext:line` — [brief context]
140
+ - `path/to/file2.ext:line` — [brief context]
141
+ - `path/to/file3.ext:line` — [brief context]
142
+ - **Remediation**: [Single recommendation that addresses all instances]
143
+ ```
144
+
145
+ This produces cleaner, more actionable review output by surfacing systemic issues as patterns rather than repeating the same finding across multiple files.
@@ -0,0 +1,387 @@
1
+ ---
2
+ name: delegation
3
+ description: Agent delegation best practices for constructing effective subagent prompts with proper scoping
4
+ ---
5
+
6
+ # Delegation Skill
7
+
8
+ Activate this skill when delegating work to subagents during orchestration execution. This skill provides the templates, rules, and patterns for constructing effective delegation prompts that produce consistent, high-quality results.
9
+
10
+ ## Protocol Injection
11
+
12
+ Before constructing any delegation prompt, inject the shared agent base protocol:
13
+
14
+ ### Injection Steps
15
+ 1. Load `agent-base-protocol` via `get_skill_content`
16
+ 2. Load `filesystem-safety-protocol` via `get_skill_content`
17
+ 3. Prepend both protocols to the delegation prompt (base protocol first, then filesystem safety) — these appear before the task-specific content
18
+ 4. For each phase listed in the current phase's `blocked_by`, read `phases[].downstream_context` from session state and include it in the prompt
19
+ 5. If any required `downstream_context` is missing, include an explicit placeholder noting the missing dependency context (never omit silently)
20
+
21
+ The injected protocol ensures every agent follows consistent pre-work procedures and output formatting regardless of their specialization.
22
+
23
+ ### Context Chain Construction
24
+
25
+ Every delegation prompt must include a context chain that connects the current phase to prior work:
26
+
27
+ **Phase Context**: Include Downstream Context blocks from all completed phases that the current phase depends on (identified via `blocked_by` relationships in the implementation plan and sourced from session state `phases[].downstream_context`):
28
+ ```
29
+ Context from completed phases:
30
+ - Phase [N] ([agent]): [Downstream Context summary]
31
+ - Interfaces introduced: [list with file locations]
32
+ - Patterns established: [list]
33
+ - Integration points: [specific files, functions, endpoints]
34
+ - Warnings: [list]
35
+ ```
36
+
37
+ **Accumulated Patterns**: Naming conventions, directory organization patterns, and architectural decisions established by earlier phases. This ensures phase 5 does not contradict patterns set in phase 2.
38
+
39
+ **File Manifest**: Complete list of files created or modified in prior phases, so the agent knows what already exists and can import from or extend those files.
40
+
41
+ **Missing Context Fallback**: If a blocked dependency has no stored downstream context, include a visible placeholder entry in the prompt:
42
+ `- Phase [N] ([agent]): Downstream Context missing in session state — verify dependency output before implementation`
43
+
44
+ ### Downstream Consumer Declaration
45
+
46
+ Every delegation prompt must declare who will consume the agent's output:
47
+ ```
48
+ Your output will be consumed by: [downstream agent name(s)] who need [specific information they require]
49
+ ```
50
+
51
+ This primes the agent to structure their Downstream Context section for maximum utility to the next agent in the chain.
52
+
53
+ ## Settings Override Application
54
+
55
+ Before constructing any delegation prompt, resolve configurable parameters:
56
+
57
+ 1. Read the agent's base definition frontmatter (`temperature`, `max_turns`, `timeout_mins`, `tools`)
58
+ 2. Do not invent Maestro-level model, temperature, turn, or timeout overrides. Native delegation uses agent frontmatter defaults plus any runtime-level agent configuration already active in the session.
59
+ 3. Include only task-relevant execution context in the prompt metadata
60
+ 4. If the agent appears in `MAESTRO_DISABLED_AGENTS`, do not construct a delegation prompt — report to the orchestrator that the agent is disabled
61
+
62
+ ## Delegation Prompt Template
63
+
64
+ Every delegation to a subagent must follow this structure:
65
+
66
+ ```
67
+ Task: [One-line description of what to accomplish]
68
+
69
+ Progress: Phase [N] of [M]: [Phase Name]
70
+
71
+ Files to modify:
72
+ - /absolute/path/to/file1.ext: [Specific change required]
73
+ - /absolute/path/to/file2.ext: [Specific change required]
74
+
75
+ Files to create:
76
+ - /absolute/path/to/new-file.ext: [Purpose and key contents]
77
+
78
+ Deliverables:
79
+ - [Concrete output 1]
80
+ - [Concrete output 2]
81
+
82
+ Validation: [command to run after completion, e.g., "npm run lint && npm run test"]
83
+
84
+ Context:
85
+ [Relevant information from the design document or previous phases]
86
+
87
+ Do NOT:
88
+ - [Explicit exclusion 1]
89
+ - [Explicit exclusion 2]
90
+ - Modify any files not listed above
91
+ ```
92
+
93
+ ## Scope Boundary Rules
94
+
95
+ ### Absolute Paths
96
+ Always provide absolute file paths in delegation prompts. Never use relative paths or expect agents to search for files.
97
+
98
+ ### Specific Deliverables
99
+ Define exactly what the agent should produce. Vague instructions like "implement the feature" lead to inconsistent results. Instead: "Create UserService class with createUser(), getUserById(), and deleteUser() methods implementing the IUserService interface."
100
+
101
+ ### Validation Criteria
102
+ Include the exact command(s) to run after completion. The agent should run these and report results. Examples:
103
+ - `npm run lint && npm run test`
104
+ - `cargo build && cargo test`
105
+ - `go vet ./... && go test ./...`
106
+ - `python -m pytest tests/`
107
+
108
+ ### No Interactive Commands in Delegation Prompts
109
+ Never include interactive CLI commands in delegation prompts. Subagents run autonomously without user input. Interactive commands will hang indefinitely.
110
+
111
+ <ANTI-PATTERN>
112
+ WRONG — Delegation prompt includes interactive scaffolding:
113
+ "Run `npx create-next-app@latest . --typescript --tailwind`"
114
+ "Run `npm init` to create package.json"
115
+
116
+ CORRECT — Delegation prompt specifies direct file creation:
117
+ "Create package.json with the following content: ..."
118
+ "Create tsconfig.json, tailwind.config.ts, and src/app/layout.tsx directly"
119
+ </ANTI-PATTERN>
120
+
121
+ ### Exclusions
122
+ Explicitly state what the agent must NOT do:
123
+ - Files it must not modify
124
+ - Dependencies it must not add
125
+ - Patterns it must not introduce
126
+ - Scope it must not exceed
127
+
128
+ ## Agent Selection Guide
129
+
130
+ | Task Domain | Agent | Key Capability |
131
+ |-------------|-------|---------------|
132
+ | System architecture, component design | `architect` | Read-only analysis, architecture patterns |
133
+ | Cloud architecture, multi-region topology | `cloud-architect` | Read-only cloud/IaC architecture |
134
+ | Enterprise integration architecture | `solutions-architect` | Read-only cross-team architecture |
135
+ | API contracts, endpoint design | `api-designer` | Read-only, REST/GraphQL expertise |
136
+ | Feature implementation, coding | `coder` | Full read/write/shell access |
137
+ | Code quality assessment | `code-reviewer` | Read-only, verified findings |
138
+ | Database schema, queries, ETL | `data-engineer` | Full read/write/shell access |
139
+ | RDBMS tuning, indexes, migration safety | `database-administrator` | Read + shell for database analysis |
140
+ | DB2 operations and tuning | `db2-dba` | Read + shell for DB2-specific work |
141
+ | Bug investigation, root cause | `debugger` | Read + shell for investigation |
142
+ | CI/CD, infrastructure, deployment | `devops-engineer` | Full read/write/shell access |
143
+ | Internal platforms, paved paths | `platform-engineer` | Full platform implementation access |
144
+ | B2B APIs, ETL, message brokers | `integration-engineer` | Full integration implementation access |
145
+ | SLOs, runbooks, reliability | `site-reliability-engineer` | Read + shell reliability analysis |
146
+ | Metrics, logs, traces, dashboards | `observability-engineer` | Full observability implementation access |
147
+ | Performance analysis, profiling | `performance-engineer` | Read + shell for profiling |
148
+ | Code restructuring, modernization | `refactor` | Read/write/shell, skill activation |
149
+ | Security assessment, vulnerability | `security-engineer` | Read + shell for scanning |
150
+ | Test creation, TDD, coverage | `tester` | Full read/write/shell access |
151
+ | Documentation, READMEs, guides | `technical-writer` | Read/write, no shell |
152
+ | Release notes, changelogs, rollout | `release-manager` | Read/write for release artifacts |
153
+ | Technical SEO auditing | `seo-specialist` | Read + shell + web search/fetch |
154
+ | Marketing copy, content writing | `copywriter` | Read/write |
155
+ | Content planning, strategy | `content-strategist` | Read + web search/fetch |
156
+ | User experience design | `ux-designer` | Read/write + web search |
157
+ | WCAG compliance auditing | `accessibility-specialist` | Read + shell + web search |
158
+ | Requirements, product strategy | `product-manager` | Read/write + web search |
159
+ | Tracking, measurement | `analytics-engineer` | Full read/write/shell access |
160
+ | Internationalization | `i18n-specialist` | Full read/write/shell access |
161
+ | Design tokens, theming | `design-system-engineer` | Full read/write/shell access |
162
+ | Legal, regulatory compliance | `compliance-reviewer` | Read + web search/fetch |
163
+ | Mobile platform work | `mobile-engineer` | Full mobile implementation access |
164
+ | Model training and inference integration | `ml-engineer` | Full ML implementation access |
165
+ | Model operations and model CI/CD | `mlops-engineer` | Full MLOps implementation access |
166
+ | Prompt design, few-shot, RAG tuning | `prompt-engineer` | Read/write prompt and eval design |
167
+ | Mainframe COBOL, JCL, CICS/IMS | `cobol-engineer` | Full mainframe implementation access |
168
+ | IBM HLASM for z/OS | `hlasm-assembler-specialist` | Full assembly implementation access |
169
+ | IBM i RPG/CL, DB2 for i | `ibm-i-specialist` | Full IBM i implementation access |
170
+ | z/OS systems programming, JCL, RACF | `zos-sysprog` | Read + shell for z/OS system work |
171
+
172
+ ## Agent Tool Dispatch Contract
173
+
174
+ Delegate to the assigned agent using the dispatch pattern from `get_runtime_context` (loaded at session start, step 0). Every Maestro agent in the Agent Roster carries its frontmatter configuration:
175
+
176
+ - `temperature`: Controls output determinism (e.g., coder uses 0.2 for precise code)
177
+ - `max_turns`: Prevents runaway sessions (e.g., 25 turns for implementation agents)
178
+ - `tools`: Restricts the agent to its authorized tool surface (e.g., read-only agents cannot use file-writing tools)
179
+ - Body: Contains the agent's specialized methodology and decision frameworks
180
+
181
+ Using a generic/default agent tool bypasses all of this — it uses default temperature, has no turn limit, no tool restrictions, and no specialized methodology. Never use a generic agent tool for Maestro phase delegations.
182
+
183
+ Every delegation must include the required header fields:
184
+
185
+ ```
186
+ Agent: <agent_name>
187
+ Phase: <id>/<total>
188
+ Batch: <batch_id> (or "single" for sequential)
189
+ Session: <session_id>
190
+ ```
191
+
192
+ **Sequential dispatch**: Invoke the agent using your runtime's dispatch mechanism with the full delegation prompt.
193
+
194
+ **Parallel dispatch**: Emit contiguous agent dispatch calls in a single turn for all agents in the ready batch. Each call includes the same header format with the shared batch ID.
195
+
196
+ Call `get_agent` with the agent name (as it appears in the implementation plan or Agent Roster) to load the agent methodology body, declared tool restrictions, and the runtime-specific `tool_name`. Use the returned `tool_name` as the dispatch target when invoking the agent tool. Runtime-local agent files remain registration stubs only; do not rely on them for the full methodology body.
197
+
198
+ ## Parallel Delegation
199
+
200
+ Parallel delegation uses the runtime's native subagent scheduler. The orchestrator emits contiguous agent tool calls inside a single turn; it does not write prompt files, spawn subprocesses, or call shell-based dispatch helpers.
201
+
202
+ ### Native Batch Construction
203
+
204
+ For each agent in a ready batch:
205
+
206
+ 1. Build a full delegation prompt using the same template as sequential delegation
207
+ 2. Include the required header:
208
+ - `Agent: <agent_name>`
209
+ - `Phase: <id>/<total>`
210
+ - `Batch: <batch_id>`
211
+ - `Session: <session_id>`
212
+ 3. Keep prompts self-contained with explicit files, deliverables, validation commands, exclusions, and dependency context
213
+ 4. Emit only contiguous agent tool calls for the current batch turn — no shell commands, file writes, or narration between them
214
+
215
+ Native parallel batches may pause if an agent asks a follow-up question. Scope prompts tightly enough that questions are rare.
216
+
217
+ ### Tool Restriction Enforcement
218
+
219
+ Maestro enforces tool permissions at two levels:
220
+
221
+ **Level 1: Native enforcement (primary)**
222
+
223
+ Tool permissions are enforced natively via each agent's registered frontmatter stub. Use the `tools` array returned by `get_agent` when you mirror that restriction in the prompt. This works for both sequential and parallel delegation.
224
+
225
+ **Level 2: Prompt-based enforcement (defense-in-depth)**
226
+
227
+ Native tool permissions remain the primary boundary. As defense-in-depth, every delegation prompt should still include an explicit tool restriction block so the agent sees its allowed surface in plain language.
228
+
229
+ 1. Agent Base Protocol (load `agent-base-protocol` via `get_skill_content`)
230
+ 2. Filesystem Safety Protocol (load `filesystem-safety-protocol` via `get_skill_content`)
231
+ 3. **TOOL RESTRICTIONS block (immediately here, before any task content)**
232
+ 4. **FILE WRITING RULES block (immediately after tool restrictions)**
233
+ 5. Context chain from prior phases
234
+ 6. Task-specific instructions
235
+ 7. Scope boundaries and prohibitions
236
+
237
+ The tool restriction block template:
238
+
239
+ ```
240
+ TOOL RESTRICTIONS (MANDATORY):
241
+ You are authorized to use ONLY the following tools: [list from agent frontmatter].
242
+ Do NOT use any tools not listed above. Specifically:
243
+ - Do NOT use `write_file` or `replace` unless explicitly authorized above
244
+ - Do NOT use `run_shell_command` unless explicitly authorized above
245
+ - Do NOT create, modify, or delete files unless authorized above
246
+ Violation of these restrictions constitutes a security boundary breach.
247
+ ```
248
+
249
+ Populate the tool list from the `tools` array returned by `get_agent` for the delegated agent.
250
+
251
+ The file writing rules block template:
252
+
253
+ ```
254
+ FILE WRITING RULES (MANDATORY):
255
+ Use ONLY `write_file` to create files and `replace` to modify files.
256
+ Do NOT use `run_shell_command` with cat, echo, printf, heredocs, or shell redirection (>, >>) to write file content.
257
+ Shell interpretation corrupts YAML, Markdown, and special characters. This rule has NO exceptions.
258
+ ```
259
+
260
+ This block reinforces the Agent Base Protocol's File Writing Rule directly in every delegation prompt, ensuring agents see the prohibition even if they skim the injected protocols.
261
+
262
+ ### Non-Overlapping File Ownership
263
+ When delegating to multiple agents in parallel, ensure no two agents are assigned the same file. Each file must have exactly one owner in a parallel batch.
264
+
265
+ ### Batch Completion Gates
266
+ All agents in a parallel batch must complete before:
267
+ - The next batch of phases begins
268
+ - Shared/container files are updated
269
+ - Validation checkpoints run
270
+ - The orchestrator creates a git commit for the batch
271
+
272
+ ### Conflict Prevention
273
+ - Assign non-overlapping file sets to each agent
274
+ - Reserve shared files (barrel exports, configuration, dependency manifests) for a single agent or a post-batch update step
275
+ - If two phases must modify the same file, they cannot run in parallel — execute them sequentially
276
+ - Parallel agents must NOT create git commits — the orchestrator commits after validating the batch
277
+
278
+ ## Hook Integration
279
+
280
+ Maestro hooks fire at agent boundaries during delegation, providing context injection and output validation. Understanding hook behavior is essential for constructing correct delegation prompts.
281
+
282
+ ### Agent Tracking
283
+
284
+ Before each agent dispatch, a hook tracks which agent is currently executing:
285
+
286
+ - Preferred signal: the required `Agent: <agent_name>` header in the delegation prompt
287
+ - Legacy fallbacks: `MAESTRO_CURRENT_AGENT` from the environment, then regex-based detection of patterns like `delegate to <agent>` or `@<agent>`
288
+
289
+ The detected agent name is persisted to `${MAESTRO_HOOKS_DIR:-<os.tmpdir()>/maestro-hooks-<uid>}/<session-id>/active-agent` and cleared by the post-delegation hook on every allowed response (both successful validation and retry allow-through). On deny (malformed output), the active agent is preserved to enable re-validation on retry.
290
+
291
+ ### Session Context Injection
292
+
293
+ When an active orchestration session exists, the pre-delegation hook parses `<MAESTRO_STATE_DIR>/state/active-session.md` and injects a compact context line into the agent's turn:
294
+
295
+ ```
296
+ Active session: current_phase=3, status=in_progress
297
+ ```
298
+
299
+ This gives delegated agents awareness of where they sit in the orchestration workflow without requiring explicit context in every delegation prompt. The injection is automatic and requires no action from the orchestrator.
300
+
301
+ ### Handoff Format Enforcement
302
+
303
+ After completion, the post-delegation hook validates that every subagent response contains both required handoff sections:
304
+
305
+ - `## Task Report` (or `# Task Report`)
306
+ - `## Downstream Context` (or `# Downstream Context`)
307
+
308
+ If either heading is missing:
309
+
310
+ 1. **First failure**: The hook blocks the response and requests a retry with a diagnostic message specifying which section is missing.
311
+ 2. **Second failure** (`stop_hook_active=true`, mapped to `stopHookActive` in JS): The hook allows the malformed response through to prevent infinite retry loops, logging a warning.
312
+
313
+ This enforcement is the runtime complement to the Output Handoff Contract defined in the agent-base-protocol. Delegation prompts do not need to re-state the retry mechanism — the hook handles it transparently.
314
+
315
+ **Exception**: The TechLead/orchestrator agent is excluded from validation. Only delegated subagents are subject to format enforcement.
316
+
317
+ ## Delegation Constraints (per runtime)
318
+
319
+ Read `delegation.constraints` from `get_runtime_context` before constructing any agent dispatch. Apply constraints to the dispatch:
320
+
321
+ - `fork_full_context_incompatible_with`: list of field names. If the runtime is invoking a fork-style delegation with full-history inheritance, do NOT pass any of these fields. For Codex, this means omitting `agent_type`, `model`, and `reasoning_effort` whenever `fork_context: true` or `fork_turns: "all"` is used.
322
+ - `result_surface: "synchronous"`: the parent receives the child's full text response in the dispatch return value. Parse the Task Report and Downstream Context directly from that text.
323
+ - `result_surface: "deferred"`: the parent receives only identifiers. The parent MUST poll for completion (`wait_agent` or equivalent) with a bounded timeout. On timeout or empty return, invoke the Recovery Protocol in the execution skill.
324
+ - `child_cannot_prompt_user: true`: child agents cannot call the user-prompt tool. All user questions must surface through the Blocker Protocol below.
325
+
326
+ ## Blocker Protocol (child-agent question surfacing)
327
+
328
+ **MANDATORY** when `delegation.constraints.child_cannot_prompt_user` is true (Codex today). **RECOMMENDED** uniformly so the orchestrator remains the single approval point across runtimes.
329
+
330
+ Every agent's Task Report may include a `## Blockers` section, placed between `## Task Report` and `## Downstream Context`:
331
+
332
+ ## Blockers
333
+ - BLOCKER: [question the agent cannot resolve]
334
+ Context: [why this question arose]
335
+ Required to proceed: [what answer unlocks continuation]
336
+
337
+ When parsing an agent response:
338
+
339
+ 1. If `## Blockers` is present and non-empty, do NOT call `transition_phase`. Keep the phase `in_progress`.
340
+ 2. Aggregate blockers across the batch (if parallel).
341
+ 3. Ask the user via the runtime's user-prompt tool.
342
+ 4. Re-delegate the phase with the answer added to the Context block. The agent re-tries with the new information.
343
+ 5. On the next return, re-parse and proceed.
344
+
345
+ An agent that returns neither a handoff nor a blocker is considered incomplete. Invoke the Recovery Protocol in the execution skill.
346
+
347
+ ## Validation Criteria Templates
348
+
349
+ ### For Implementation Agents (`coder`, `data-engineer`, `devops-engineer`)
350
+ ```
351
+ Validation: [build command] && [lint command] && [test command]
352
+ ```
353
+
354
+ ### For Refactoring Agents (`refactor`)
355
+ ```
356
+ Validation: [build command] && [test command]
357
+ Verify: No behavior changes — all existing tests must still pass
358
+ ```
359
+
360
+ ### For Test Agents (`tester`)
361
+ ```
362
+ Validation: [test command]
363
+ Verify: All new tests pass, report coverage metrics
364
+ ```
365
+
366
+ ### For Assessment Agents (`architect`, `api-designer`, `code-reviewer`, `debugger`, `performance-engineer`, `security-engineer`, `seo-specialist`, `accessibility-specialist`, `content-strategist`, `compliance-reviewer`)
367
+ ```
368
+ Validation: N/A (assessment-only — no write tools)
369
+ Verify: Findings reference specific files and line numbers
370
+ ```
371
+
372
+ ### For Documentation Agents (`technical-writer`, `copywriter`)
373
+ ```
374
+ Validation: Verify all links resolve, code examples are syntactically valid
375
+ ```
376
+
377
+ ### For Design and Product Agents (`ux-designer`, `product-manager`)
378
+ ```
379
+ Validation: N/A (design and requirements artifacts)
380
+ Verify: Deliverables reference user needs and acceptance criteria
381
+ ```
382
+
383
+ ### For Implementation Specialists (`analytics-engineer`, `i18n-specialist`, `design-system-engineer`)
384
+ ```
385
+ Validation: [build command] && [lint command] && [test command]
386
+ Verify: Domain-specific integration validated (tracking fires, locales render, tokens apply)
387
+ ```