diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 9fcdafdf..9fd485a5 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,14 +5,14 @@ }, "metadata": { "description": "Maestro multi-agent orchestration platform for Claude Code", - "version": "1.6.3" + "version": "1.6.4" }, "plugins": [ { "name": "maestro", "source": "./claude", "description": "Multi-agent development orchestration platform — 39 specialists, 4-phase orchestration, native parallel subagents, persistent sessions, and standalone review/debug/security/perf/seo/a11y/compliance commands", - "version": "1.6.3", + "version": "1.6.4", "author": { "name": "josstei", "email": "hello@josstei.dev", diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index f6aa16a9..497f3dba 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -11,6 +11,7 @@ assignees: '' - [ ] Gemini CLI - [ ] Claude Code - [ ] Codex +- [ ] Qwen Code ## Maestro Version @@ -20,7 +21,7 @@ assignees: '' - **OS**: - **Node.js version**: -- **Runtime version**: +- **Runtime version**: ## Description diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 69360e23..bb9cddcd 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -25,6 +25,7 @@ assignees: '' - [ ] Gemini CLI - [ ] Claude Code - [ ] Codex +- [ ] Qwen Code - [ ] All runtimes - [ ] Build/generator only diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4ad9d702..8479a5fd 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -30,6 +30,7 @@ - [ ] Gemini CLI - [ ] Claude Code - [ ] Codex +- [ ] Qwen Code - [ ] None (internal/build only) ## Testing Notes diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 200d507a..27a5fb17 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -7,3 +7,4 @@ Related documentation: - [docs/runtime-gemini.md](docs/runtime-gemini.md) - [docs/runtime-claude.md](docs/runtime-claude.md) - [docs/runtime-codex.md](docs/runtime-codex.md) +- [docs/runtime-qwen.md](docs/runtime-qwen.md) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a11ab04..ec42bd9a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.6.4] - 2026-04-30 + ### Added - **Maestro cheatsheet**: added an English quick-reference guide covering supported runtimes, common commands, workflow concepts, and suggested reading order. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 529c5b62..03c89433 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ Thank you for your interest in contributing to Maestro. This guide covers everyt ## Prerequisites - **Node.js 20+** -- **One supported runtime**: [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or [Codex](https://github.com/openai/codex) +- **One supported runtime**: [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or [Qwen Code](https://github.com/QwenLM/qwen-code) - [Just](https://github.com/casey/just) command runner (optional but recommended) ## Development Setup @@ -16,12 +16,14 @@ cd maestro-orchestrate npm install ``` -`npm install` runs a `prepare` script that points `core.hooksPath` at `.githooks/`, activating the local `pre-commit`, `commit-msg`, and `pre-push` hooks for this checkout. If you install with `--ignore-scripts` or another tool that skips lifecycle scripts, activate the hooks manually: +`npm install` installs dependencies only. Local git hook activation is explicit so package, pack, and publish flows do not mutate hook configuration. To activate the repo-local `pre-commit`, `commit-msg`, and `pre-push` hooks for this checkout, run: ```bash -git config core.hooksPath .githooks +npm run install-hooks ``` +Equivalent manual command: `git config core.hooksPath .githooks`. + The hooks are best-effort — CI re-validates everything on PR submission and on direct pushes to `main`. ## Key Commands @@ -36,7 +38,7 @@ All commands are available via `just` or `npm`: | `just test-transforms` | Run only transform unit tests | | `just test-integration` | Run only integration tests | | `just check` | Generate + verify zero drift (`git diff --exit-code`) | -| `just ci` | Full CI equivalent: check + test | +| `just ci` | Full CI equivalent: check + check-layers + test | | `just dry-run` | Preview changes without writing | | `just diff` | Show unified diff of pending changes | @@ -53,6 +55,7 @@ All hand-maintained code lives in `src/`. Everything outside `src/` at the runti | `agents/`, `commands/`, `hooks/`, `mcp/`, `policies/` (repo root) | Gemini CLI | | `claude/` | Claude Code | | `plugins/maestro/` | Codex | +| `qwen/` plus root `qwen-extension.json` and `QWEN.md` | Qwen Code | The generator pipeline reads `src/manifest.js` and applies transforms from `src/transforms/` to produce runtime-specific output. @@ -163,7 +166,7 @@ This project uses [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) forma ## Reporting Bugs and Requesting Features -Use the [issue templates](.github/ISSUE_TEMPLATE/) to file bug reports or feature requests. Include your runtime (Gemini CLI, Claude Code, or Codex), Node.js version, and steps to reproduce. +Use the [issue templates](.github/ISSUE_TEMPLATE/) to file bug reports or feature requests. Include your runtime (Gemini CLI, Claude Code, Codex, or Qwen Code), Node.js version, and steps to reproduce. ## Code Review diff --git a/EXAMPLES.md b/EXAMPLES.md index 06f05f51..5896ccc0 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -247,9 +247,9 @@ Source: `justfile`, `package.json` ```bash # edit README.md, EXAMPLES.md, docs/*.md, or canonical src/ docs as appropriate node --test tests/unit/doc-drift-guard.test.js -just check +node scripts/generate.js --diff ``` -Expected outcome: user-facing docs remain aligned with command names, runtime counts, MCP tool names, and generated-output rules. +Expected outcome: user-facing docs remain aligned with command names, runtime counts, MCP tool names, and generated-output rules, and the generator reports no additional pending runtime output. In CI or a clean worktree, `just check` covers the same drift check with `git diff --exit-code`. Source: `tests/unit/doc-drift-guard.test.js` diff --git a/GEMINI.md b/GEMINI.md index c3e8b26d..4789ba60 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -76,7 +76,7 @@ For each domain, determine if the task has needs that warrant specialist involve | Domain | Signal questions | Candidate agents | | --- | --- | --- | -| Engineering | Does the task involve code, infrastructure, or data? | `architect`, `api_designer`, `coder`, `code_reviewer`, `tester`, `refactor`, `data_engineer`, `debugger`, `devops_engineer`, `performance_engineer`, `security_engineer`, `technical_writer` | +| Engineering | Does the task involve code, infrastructure, APIs, data, or delivery? | `architect`, `api_designer`, `coder`, `code_reviewer`, `tester`, `refactor`, `data_engineer`, `database_administrator`, `debugger`, `devops_engineer`, `integration_engineer`, `platform_engineer`, `cloud_architect`, `solutions_architect`, `site_reliability_engineer`, `observability_engineer`, `performance_engineer`, `security_engineer`, `technical_writer`, `release_manager` | | Product | Are requirements unclear, or does success depend on user outcomes? | `product_manager` | | Design | Does the deliverable have a user-facing interface or interaction? | `ux_designer`, `accessibility_specialist`, `design_system_engineer` | | Content | Does the task produce or modify user-visible text, copy, or media? | `content_strategist`, `copywriter` | @@ -84,13 +84,16 @@ For each domain, determine if the task has needs that warrant specialist involve | Compliance | Does the task handle user data, payments, or operate in a regulated domain? | `compliance_reviewer` | | Internationalization | Must the deliverable support multiple locales? | `i18n_specialist` | | Analytics | Does success need to be measured, or does the feature need instrumentation? | `analytics_engineer` | +| ML/AI | Does the task involve model training, inference, prompts, or model operations? | `ml_engineer`, `mlops_engineer`, `prompt_engineer` | +| Mobile | Does the task target iOS, Android, React Native, Flutter, or mobile release constraints? | `mobile_engineer` | +| Mainframe / IBM | Does the task involve COBOL, JCL, DB2 for z/OS or IBM i, HLASM, RACF, CICS, IMS, or USS? | `cobol_engineer`, `db2_dba`, `zos_sysprog`, `hlasm_assembler_specialist`, `ibm_i_specialist` | Skip domains where the answer is clearly "no." For relevant domains, include appropriate agents in the phase plan alongside engineering agents. Domain agents participate at whatever phase makes sense — design, implementation, or post-build audit — based on the specific task. Apply domain analysis proportional to `task_complexity`: - `simple`: Engineering domain only. Skip other domains unless explicitly requested. - `medium`: Engineering + domains with clear signals from the task description. -- `complex`: Full 8-domain sweep (current behavior). +- `complex`: Full domain sweep (current behavior). ## Native Parallel Contract @@ -141,7 +144,7 @@ CORRECT — Delegating via the agent's own tool: When building delegation prompts: -1. Call the agent's registered tool by its exact name from the Agent Roster (e.g., `coder`, `tester`, `design_system_engineer`). Use `get_agent` to load the full methodology body and declared tool restrictions for the matching kebab-case agent. +1. Call the agent's registered tool by its exact name from the Agent Roster (e.g., `coder`, `tester`, `design_system_engineer`). Use `get_agent` to load the full methodology body, declared tool restrictions, and runtime `tool_name` for the matching canonical agent. 2. Do not rely on Maestro-level model, temperature, turn, or timeout overrides. Use agent frontmatter and runtime-level agent configuration for native tuning. 3. Inject shared protocols from `get_skill_content` with resources: `["agent-base-protocol", "filesystem-safety-protocol"]`. 4. Include dependency downstream context from session state. @@ -189,30 +192,47 @@ All agent names use **snake_case** (underscores, not hyphens). When delegating, ## Agent Roster -| Agent | Focus | Key Tool Profile | +| Agent | Focus | Capability Tier | | --- | --- | --- | -| `architect` | System design | Read tools + web search/fetch | -| `api_designer` | API contracts | Read tools + web search/fetch | -| `code_reviewer` | Code quality review | Read-only | -| `coder` | Feature implementation | Read/write/shell + todos + skill activation | -| `data_engineer` | Schema/data/queries | Read/write/shell + todos + web search | -| `debugger` | Root cause analysis | Read + shell + todos | -| `devops_engineer` | CI/CD and infra | Read/write/shell + todos + web search/fetch | -| `performance_engineer` | Performance profiling | Read + shell + todos + web search/fetch | -| `refactor` | Structural refactoring | Read/write/shell + todos + skill activation | -| `security_engineer` | Security auditing | Read + shell + todos + web search/fetch | -| `technical_writer` | Documentation | Read/write + todos + web search | -| `tester` | Test implementation | Read/write/shell + todos + skill activation + web search | -| `seo_specialist` | Technical SEO auditing | Read + shell + web search/fetch + todos | -| `copywriter` | Marketing copy & content | Read/write | -| `content_strategist` | Content planning & strategy | Read + web search/fetch | -| `ux_designer` | User experience design | Read/write + web search | -| `accessibility_specialist` | WCAG compliance auditing | Read + shell + web search + todos | -| `product_manager` | Requirements & product strategy | Read/write + web search | -| `analytics_engineer` | Tracking & measurement | Read/write/shell + web search + todos | -| `i18n_specialist` | Internationalization | Read/write/shell + todos | -| `design_system_engineer` | Design tokens & theming | Read/write/shell + todos + skill activation | -| `compliance_reviewer` | Legal & regulatory compliance | Read + web search/fetch | +| `accessibility_specialist` | WCAG compliance auditing, ARIA review | Read + shell | +| `analytics_engineer` | Event tracking, conversion funnels | Full access | +| `api_designer` | API contracts and endpoint design | Read-only | +| `architect` | System design and architecture decisions | Read-only | +| `cloud_architect` | AWS/GCP/Azure topology, IaC, multi-region design | Read-only | +| `cobol_engineer` | Mainframe COBOL, JCL, CICS/IMS on z/OS | Full access | +| `code_reviewer` | Code quality review and bug identification | Read-only | +| `coder` | Feature implementation | Full access | +| `compliance_reviewer` | Legal and regulatory compliance | Read-only | +| `content_strategist` | Content planning and strategy | Read-only | +| `copywriter` | Marketing copy and landing-page content | Read + write | +| `data_engineer` | Schema design, queries, and data pipelines | Full access | +| `database_administrator` | RDBMS tuning, indexes, and migration safety | Read + shell | +| `db2_dba` | DB2 for z/OS and LUW, REORG, RUNSTATS, bind/rebind | Read + shell | +| `debugger` | Root cause analysis and defect investigation | Read + shell | +| `design_system_engineer` | Design tokens and theming | Full access | +| `devops_engineer` | CI/CD, containerization, and deployment | Full access | +| `hlasm_assembler_specialist` | IBM HLASM for z/OS, macros, SVCs | Full access | +| `i18n_specialist` | Internationalization and locale management | Full access | +| `ibm_i_specialist` | IBM i RPG/CL, DB2 for i, OS/400 | Full access | +| `integration_engineer` | B2B APIs, ETL, and message brokers | Full access | +| `ml_engineer` | Model training, feature pipelines, and evaluation | Full access | +| `mlops_engineer` | Model registry, CI/CD for models, drift detection | Full access | +| `mobile_engineer` | iOS/Android/React Native/Flutter platform work | Full access | +| `observability_engineer` | Metrics, logs, traces, OpenTelemetry, dashboards | Full access | +| `performance_engineer` | Performance profiling and optimization | Read + shell | +| `platform_engineer` | Internal developer platforms and paved paths | Full access | +| `product_manager` | Requirements and product strategy | Read + write | +| `prompt_engineer` | LLM prompt design, few-shot, and RAG tuning | Read + write | +| `refactor` | Structural refactoring and technical debt | Full access | +| `release_manager` | Release notes, changelogs, rollout planning | Read + write | +| `security_engineer` | Security assessment and vulnerability analysis | Read + shell | +| `seo_specialist` | Technical SEO auditing and structured data | Read + shell | +| `site_reliability_engineer` | SLOs, error budgets, runbooks, postmortems | Read + shell | +| `solutions_architect` | Enterprise integration and cross-team architecture | Read-only | +| `technical_writer` | Documentation and technical writing | Read + write | +| `tester` | Test implementation and coverage analysis | Full access | +| `ux_designer` | User experience design | Read + write | +| `zos_sysprog` | z/OS systems programming, JCL, USS, RACF | Read + shell | ## Hooks diff --git a/OVERVIEW.md b/OVERVIEW.md index fe1a0d72..59903fcb 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -8,3 +8,4 @@ Related documentation: - [docs/runtime-gemini.md](docs/runtime-gemini.md) - [docs/runtime-claude.md](docs/runtime-claude.md) - [docs/runtime-codex.md](docs/runtime-codex.md) +- [docs/runtime-qwen.md](docs/runtime-qwen.md) diff --git a/QWEN.md b/QWEN.md index 1bc76ab6..9f6f26df 100644 --- a/QWEN.md +++ b/QWEN.md @@ -34,20 +34,33 @@ Before running orchestration commands: - Extension settings from `qwen-extension.json` are exposed as `MAESTRO_*` env vars via Qwen Code extension settings; honor them as runtime source of truth. - Maestro slash commands are file commands loaded from `commands/maestro/*.toml`; they are expected to resolve as `/maestro:*`. -- Hook entries must remain `type: "command"` in `hooks/hooks.json` for compatibility with current Qwen Code hook validation. +- Hook entries must remain `type: "command"` in `qwen/hooks.json` for compatibility with current Qwen Code hook validation. - Extension workflows run only when the extension is linked/enabled and workspace trust allows extension assets. - Keep `ask_user_question` header fields short (aim for 16 characters or fewer) to fit the UI chip display. Short headers like `Database`, `Auth`, `Approach` work best. - The extension contributes deny/ask policy rules from `policies/maestro.toml`. Treat these as safety rails that complement, but do not replace, prompt-level instructions. ## Qwen Tool Name Mapping -This extension was authored for Qwen Code. When following agent methodology files that reference Gemini tool names, use the following mapping: +This extension was authored for Qwen Code. When following agent methodology files that reference canonical tool names, use the runtime mapping from `src/platforms/qwen/runtime-config.js`: | Source (raw file) | Qwen tool | |---|---| +| `read_file` | `read_file` | +| `read_many_files` | `read_many_files` | +| `list_directory` | `list_directory` | +| `glob` | `glob` | +| `grep_search` | `grep_search` | +| `google_web_search` | `web_search` | +| `web_fetch` | `web_fetch` | +| `write_file` | `write_file` | +| `replace` | `edit` | +| `run_shell_command` | `run_shell_command` | | `ask_user` | `ask_user_question` | - -**Known residual gap:** Other Gemini tool names (e.g., `google_web_search`, `write_todos`, `activate_skill`) may still appear in raw source agent files. Where encountered, apply the same mapping principle if the Qwen-equivalent tool exists and is semantically equivalent. Do not assume equivalence for tools with different invocation semantics — verify behavior first. +| `write_todos` | `todo_write` | +| `activate_skill` | `skill` | +| `enter_plan_mode` | `enter_plan_mode` | +| `exit_plan_mode` | `exit_plan_mode` | +| `codebase_investigator` | `codebase_investigator` | ## Context Budget @@ -86,7 +99,7 @@ For each domain, determine if the task has needs that warrant specialist involve | Domain | Signal questions | Candidate agents | | --- | --- | --- | -| Engineering | Does the task involve code, infrastructure, or data? | `architect`, `api_designer`, `coder`, `code_reviewer`, `tester`, `refactor`, `data_engineer`, `debugger`, `devops_engineer`, `performance_engineer`, `security_engineer`, `technical_writer` | +| Engineering | Does the task involve code, infrastructure, APIs, data, or delivery? | `architect`, `api_designer`, `coder`, `code_reviewer`, `tester`, `refactor`, `data_engineer`, `database_administrator`, `debugger`, `devops_engineer`, `integration_engineer`, `platform_engineer`, `cloud_architect`, `solutions_architect`, `site_reliability_engineer`, `observability_engineer`, `performance_engineer`, `security_engineer`, `technical_writer`, `release_manager` | | Product | Are requirements unclear, or does success depend on user outcomes? | `product_manager` | | Design | Does the deliverable have a user-facing interface or interaction? | `ux_designer`, `accessibility_specialist`, `design_system_engineer` | | Content | Does the task produce or modify user-visible text, copy, or media? | `content_strategist`, `copywriter` | @@ -94,13 +107,16 @@ For each domain, determine if the task has needs that warrant specialist involve | Compliance | Does the task handle user data, payments, or operate in a regulated domain? | `compliance_reviewer` | | Internationalization | Must the deliverable support multiple locales? | `i18n_specialist` | | Analytics | Does success need to be measured, or does the feature need instrumentation? | `analytics_engineer` | +| ML/AI | Does the task involve model training, inference, prompts, or model operations? | `ml_engineer`, `mlops_engineer`, `prompt_engineer` | +| Mobile | Does the task target iOS, Android, React Native, Flutter, or mobile release constraints? | `mobile_engineer` | +| Mainframe / IBM | Does the task involve COBOL, JCL, DB2 for z/OS or IBM i, HLASM, RACF, CICS, IMS, or USS? | `cobol_engineer`, `db2_dba`, `zos_sysprog`, `hlasm_assembler_specialist`, `ibm_i_specialist` | Skip domains where the answer is clearly "no." For relevant domains, include appropriate agents in the phase plan alongside engineering agents. Domain agents participate at whatever phase makes sense — design, implementation, or post-build audit — based on the specific task. Apply domain analysis proportional to `task_complexity`: - `simple`: Engineering domain only. Skip other domains unless explicitly requested. - `medium`: Engineering + domains with clear signals from the task description. -- `complex`: Full 8-domain sweep (current behavior). +- `complex`: Full domain sweep (current behavior). ## Native Parallel Contract @@ -151,7 +167,7 @@ CORRECT — Delegating via the agent's own tool: When building delegation prompts: -1. Call the agent's registered tool by its exact name from the Agent Roster (e.g., `coder`, `tester`, `design_system_engineer`). Use `get_agent` to load the full methodology body and declared tool restrictions for the matching kebab-case agent. +1. Call the agent's registered tool by its exact name from the Agent Roster (e.g., `coder`, `tester`, `design_system_engineer`). Use `get_agent` to load the full methodology body, declared tool restrictions, and runtime `tool_name` for the matching canonical agent. 2. Do not rely on Maestro-level model, temperature, turn, or timeout overrides. Use agent frontmatter and runtime-level agent configuration for native tuning. 3. Inject shared protocols from `get_skill_content` with resources: `["agent-base-protocol", "filesystem-safety-protocol"]`. 4. Include dependency downstream context from session state. @@ -199,30 +215,47 @@ All agent names use **snake_case** (underscores, not hyphens). When delegating, ## Agent Roster -| Agent | Focus | Key Tool Profile | +| Agent | Focus | Capability Tier | | --- | --- | --- | -| `architect` | System design | Read tools + web search/fetch | -| `api_designer` | API contracts | Read tools + web search/fetch | -| `code_reviewer` | Code quality review | Read-only | -| `coder` | Feature implementation | Read/write/shell + todos + skill activation | -| `data_engineer` | Schema/data/queries | Read/write/shell + todos + web search | -| `debugger` | Root cause analysis | Read + shell + todos | -| `devops_engineer` | CI/CD and infra | Read/write/shell + todos + web search/fetch | -| `performance_engineer` | Performance profiling | Read + shell + todos + web search/fetch | -| `refactor` | Structural refactoring | Read/write/shell + todos + skill activation | -| `security_engineer` | Security auditing | Read + shell + todos + web search/fetch | -| `technical_writer` | Documentation | Read/write + todos + web search | -| `tester` | Test implementation | Read/write/shell + todos + skill activation + web search | -| `seo_specialist` | Technical SEO auditing | Read + shell + web search/fetch + todos | -| `copywriter` | Marketing copy & content | Read/write | -| `content_strategist` | Content planning & strategy | Read + web search/fetch | -| `ux_designer` | User experience design | Read/write + web search | -| `accessibility_specialist` | WCAG compliance auditing | Read + shell + web search + todos | -| `product_manager` | Requirements & product strategy | Read/write + web search | -| `analytics_engineer` | Tracking & measurement | Read/write/shell + web search + todos | -| `i18n_specialist` | Internationalization | Read/write/shell + todos | -| `design_system_engineer` | Design tokens & theming | Read/write/shell + todos + skill activation | -| `compliance_reviewer` | Legal & regulatory compliance | Read + web search/fetch | +| `accessibility_specialist` | WCAG compliance auditing, ARIA review | Read + shell | +| `analytics_engineer` | Event tracking, conversion funnels | Full access | +| `api_designer` | API contracts and endpoint design | Read-only | +| `architect` | System design and architecture decisions | Read-only | +| `cloud_architect` | AWS/GCP/Azure topology, IaC, multi-region design | Read-only | +| `cobol_engineer` | Mainframe COBOL, JCL, CICS/IMS on z/OS | Full access | +| `code_reviewer` | Code quality review and bug identification | Read-only | +| `coder` | Feature implementation | Full access | +| `compliance_reviewer` | Legal and regulatory compliance | Read-only | +| `content_strategist` | Content planning and strategy | Read-only | +| `copywriter` | Marketing copy and landing-page content | Read + write | +| `data_engineer` | Schema design, queries, and data pipelines | Full access | +| `database_administrator` | RDBMS tuning, indexes, and migration safety | Read + shell | +| `db2_dba` | DB2 for z/OS and LUW, REORG, RUNSTATS, bind/rebind | Read + shell | +| `debugger` | Root cause analysis and defect investigation | Read + shell | +| `design_system_engineer` | Design tokens and theming | Full access | +| `devops_engineer` | CI/CD, containerization, and deployment | Full access | +| `hlasm_assembler_specialist` | IBM HLASM for z/OS, macros, SVCs | Full access | +| `i18n_specialist` | Internationalization and locale management | Full access | +| `ibm_i_specialist` | IBM i RPG/CL, DB2 for i, OS/400 | Full access | +| `integration_engineer` | B2B APIs, ETL, and message brokers | Full access | +| `ml_engineer` | Model training, feature pipelines, and evaluation | Full access | +| `mlops_engineer` | Model registry, CI/CD for models, drift detection | Full access | +| `mobile_engineer` | iOS/Android/React Native/Flutter platform work | Full access | +| `observability_engineer` | Metrics, logs, traces, OpenTelemetry, dashboards | Full access | +| `performance_engineer` | Performance profiling and optimization | Read + shell | +| `platform_engineer` | Internal developer platforms and paved paths | Full access | +| `product_manager` | Requirements and product strategy | Read + write | +| `prompt_engineer` | LLM prompt design, few-shot, and RAG tuning | Read + write | +| `refactor` | Structural refactoring and technical debt | Full access | +| `release_manager` | Release notes, changelogs, rollout planning | Read + write | +| `security_engineer` | Security assessment and vulnerability analysis | Read + shell | +| `seo_specialist` | Technical SEO auditing and structured data | Read + shell | +| `site_reliability_engineer` | SLOs, error budgets, runbooks, postmortems | Read + shell | +| `solutions_architect` | Enterprise integration and cross-team architecture | Read-only | +| `technical_writer` | Documentation and technical writing | Read + write | +| `tester` | Test implementation and coverage analysis | Full access | +| `ux_designer` | User experience design | Read + write | +| `zos_sysprog` | z/OS systems programming, JCL, USS, RACF | Read + shell | ## Hooks diff --git a/README.md b/README.md index 422e6597..e6de9d5e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Maestro -[![Version](https://img.shields.io/badge/version-1.6.3-blue)](https://github.com/josstei/maestro-orchestrate/releases) +[![Version](https://img.shields.io/badge/version-1.6.4-blue)](https://github.com/josstei/maestro-orchestrate/releases) [![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE) [![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-extension-orange)](https://github.com/google-gemini/gemini-cli) [![Claude Code](https://img.shields.io/badge/Claude_Code-plugin-blue)](https://docs.anthropic.com/en/docs/claude-code) diff --git a/SECURITY.md b/SECURITY.md index 8a027d87..7dd66267 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -17,7 +17,7 @@ Include as much of the following as possible: - Description of the vulnerability - Steps to reproduce or proof of concept -- Affected versions and runtimes (Gemini CLI, Claude Code, Codex) +- Affected versions and runtimes (Gemini CLI, Claude Code, Codex, Qwen Code) - Potential impact ## Response Timeline @@ -38,7 +38,7 @@ The following areas are in scope for security reports: Out of scope: -- Vulnerabilities in upstream runtimes (Gemini CLI, Claude Code, Codex) themselves +- Vulnerabilities in upstream runtimes (Gemini CLI, Claude Code, Codex, Qwen Code) themselves - Social engineering - Denial of service against local development environments diff --git a/USAGE.md b/USAGE.md index c0d6aca8..b3039f1d 100644 --- a/USAGE.md +++ b/USAGE.md @@ -6,3 +6,4 @@ Runtime-specific references: - [docs/runtime-gemini.md](docs/runtime-gemini.md) - [docs/runtime-claude.md](docs/runtime-claude.md) - [docs/runtime-codex.md](docs/runtime-codex.md) +- [docs/runtime-qwen.md](docs/runtime-qwen.md) diff --git a/claude/.claude-plugin/plugin.json b/claude/.claude-plugin/plugin.json index d21b7b86..277600cc 100644 --- a/claude/.claude-plugin/plugin.json +++ b/claude/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "maestro", - "version": "1.6.3", + "version": "1.6.4", "description": "Multi-agent development orchestration platform — 39 specialists, 4-phase orchestration, native parallel subagents, persistent sessions, and standalone review/debug/security/perf/seo/a11y/compliance commands", "author": { "name": "josstei", diff --git a/claude/README.md b/claude/README.md index bf48c4aa..91a6c5f7 100644 --- a/claude/README.md +++ b/claude/README.md @@ -1,6 +1,6 @@ # Maestro — Claude Code Plugin -[![Version](https://img.shields.io/badge/version-1.6.3-blue)](https://github.com/josstei/maestro-orchestrate/releases) +[![Version](https://img.shields.io/badge/version-1.6.4-blue)](https://github.com/josstei/maestro-orchestrate/releases) [![License](https://img.shields.io/badge/license-Apache-2.0-green)](LICENSE) [![Claude Code](https://img.shields.io/badge/Claude_Code-plugin-orange)](https://docs.anthropic.com/en/docs/claude-code) diff --git a/claude/src/platforms/shared/agent-names.js b/claude/src/platforms/shared/agent-names.js index 086551d4..98a80e2e 100644 --- a/claude/src/platforms/shared/agent-names.js +++ b/claude/src/platforms/shared/agent-names.js @@ -1,10 +1,15 @@ module.exports = { agentNames: [ 'accessibility-specialist', 'analytics-engineer', 'api-designer', 'architect', - 'code-reviewer', 'coder', 'compliance-reviewer', 'content-strategist', - 'copywriter', 'data-engineer', 'debugger', 'design-system-engineer', - 'devops-engineer', 'i18n-specialist', 'performance-engineer', 'product-manager', - 'refactor', 'security-engineer', 'seo-specialist', 'technical-writer', - 'tester', 'ux-designer', + 'cloud-architect', 'cobol-engineer', 'code-reviewer', 'coder', + 'compliance-reviewer', 'content-strategist', 'copywriter', 'data-engineer', + 'database-administrator', 'db2-dba', 'debugger', 'design-system-engineer', + 'devops-engineer', 'hlasm-assembler-specialist', 'i18n-specialist', + 'ibm-i-specialist', 'integration-engineer', 'ml-engineer', 'mlops-engineer', + 'mobile-engineer', 'observability-engineer', 'performance-engineer', + 'platform-engineer', 'product-manager', 'prompt-engineer', 'refactor', + 'release-manager', 'security-engineer', 'seo-specialist', + 'site-reliability-engineer', 'solutions-architect', 'technical-writer', + 'tester', 'ux-designer', 'zos-sysprog', ], }; diff --git a/claude/src/skills/shared/delegation/SKILL.md b/claude/src/skills/shared/delegation/SKILL.md index 1e19cdb8..88e8f584 100644 --- a/claude/src/skills/shared/delegation/SKILL.md +++ b/claude/src/skills/shared/delegation/SKILL.md @@ -130,17 +130,26 @@ Explicitly state what the agent must NOT do: | Task Domain | Agent | Key Capability | |-------------|-------|---------------| | System architecture, component design | `architect` | Read-only analysis, architecture patterns | +| Cloud architecture, multi-region topology | `cloud-architect` | Read-only cloud/IaC architecture | +| Enterprise integration architecture | `solutions-architect` | Read-only cross-team architecture | | API contracts, endpoint design | `api-designer` | Read-only, REST/GraphQL expertise | | Feature implementation, coding | `coder` | Full read/write/shell access | | Code quality assessment | `code-reviewer` | Read-only, verified findings | | Database schema, queries, ETL | `data-engineer` | Full read/write/shell access | +| RDBMS tuning, indexes, migration safety | `database-administrator` | Read + shell for database analysis | +| DB2 operations and tuning | `db2-dba` | Read + shell for DB2-specific work | | Bug investigation, root cause | `debugger` | Read + shell for investigation | | CI/CD, infrastructure, deployment | `devops-engineer` | Full read/write/shell access | +| Internal platforms, paved paths | `platform-engineer` | Full platform implementation access | +| B2B APIs, ETL, message brokers | `integration-engineer` | Full integration implementation access | +| SLOs, runbooks, reliability | `site-reliability-engineer` | Read + shell reliability analysis | +| Metrics, logs, traces, dashboards | `observability-engineer` | Full observability implementation access | | Performance analysis, profiling | `performance-engineer` | Read + shell for profiling | | Code restructuring, modernization | `refactor` | Read/write/shell, skill activation | | Security assessment, vulnerability | `security-engineer` | Read + shell for scanning | | Test creation, TDD, coverage | `tester` | Full read/write/shell access | | Documentation, READMEs, guides | `technical-writer` | Read/write, no shell | +| Release notes, changelogs, rollout | `release-manager` | Read/write for release artifacts | | Technical SEO auditing | `seo-specialist` | Read + shell + web search/fetch | | Marketing copy, content writing | `copywriter` | Read/write | | Content planning, strategy | `content-strategist` | Read + web search/fetch | @@ -151,6 +160,14 @@ Explicitly state what the agent must NOT do: | Internationalization | `i18n-specialist` | Full read/write/shell access | | Design tokens, theming | `design-system-engineer` | Full read/write/shell access | | Legal, regulatory compliance | `compliance-reviewer` | Read + web search/fetch | +| Mobile platform work | `mobile-engineer` | Full mobile implementation access | +| Model training and inference integration | `ml-engineer` | Full ML implementation access | +| Model operations and model CI/CD | `mlops-engineer` | Full MLOps implementation access | +| Prompt design, few-shot, RAG tuning | `prompt-engineer` | Read/write prompt and eval design | +| Mainframe COBOL, JCL, CICS/IMS | `cobol-engineer` | Full mainframe implementation access | +| IBM HLASM for z/OS | `hlasm-assembler-specialist` | Full assembly implementation access | +| IBM i RPG/CL, DB2 for i | `ibm-i-specialist` | Full IBM i implementation access | +| z/OS systems programming, JCL, RACF | `zos-sysprog` | Read + shell for z/OS system work | ## Agent Tool Dispatch Contract @@ -269,7 +286,7 @@ Before each agent dispatch, a hook tracks which agent is currently executing: - Preferred signal: the required `Agent: ` header in the delegation prompt - Legacy fallbacks: `MAESTRO_CURRENT_AGENT` from the environment, then regex-based detection of patterns like `delegate to ` or `@` -The detected agent name is persisted to `/tmp/maestro-hooks//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. +The detected agent name is persisted to `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//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. ### Session Context Injection diff --git a/claude/src/skills/shared/design-dialogue/SKILL.md b/claude/src/skills/shared/design-dialogue/SKILL.md index ebbba70c..60cef0fa 100644 --- a/claude/src/skills/shared/design-dialogue/SKILL.md +++ b/claude/src/skills/shared/design-dialogue/SKILL.md @@ -257,7 +257,7 @@ Apply depth-gated reasoning enrichment to design section content during the conv The write path depends on whether your runtime provides a Plan Mode surface (check `get_runtime_context`, loaded at session start, step 0): -- **Plan Mode active**: Some runtimes restrict writes to a temporary staging directory during Plan Mode. Write the design document there. After `exit_plan_mode` approval in Phase 2, copy it to the permanent location. +- **Plan Mode active**: Some runtimes restrict writes to a temporary staging directory during Plan Mode. Write the design document there first, then exit Plan Mode and complete the design approval handoff. When the runtime's Plan Mode path is not visible to the MCP server, use the `record_design_approval` content variant so the server materializes the canonical copy under `/plans/`. - **Plan Mode not active or not available**: Write directly to the permanent location. If your runtime does not provide Plan Mode, track design progress using the plan-update mechanism from runtime context and use the user-prompt tool from runtime context for section approvals and final signoff. Permanent location: `/plans/YYYY-MM-DD--design.md` (where `` resolves from `MAESTRO_STATE_DIR`, default `docs/maestro`). diff --git a/claude/src/skills/shared/execution/SKILL.md b/claude/src/skills/shared/execution/SKILL.md index 1ed110a0..167b4eea 100644 --- a/claude/src/skills/shared/execution/SKILL.md +++ b/claude/src/skills/shared/execution/SKILL.md @@ -121,7 +121,7 @@ Hooks fire automatically at agent boundaries. The orchestrator does not invoke t The hooks system tracks which agent is currently executing. Before each agent dispatch, a hook resolves the active agent identity from the required `Agent:` header first, then falls back to legacy env/regex detection, and injects compact session context. After completion, a hook validates that the response contains both `Task Report` and `Downstream Context`; it requests one retry on the first malformed response. -The hook state directory under `/tmp/maestro-hooks//` is transient and separate from orchestration state. +The hook state directory under `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//` is transient and separate from orchestration state. ## Sequential Execution Protocol diff --git a/claude/src/skills/shared/implementation-planning/SKILL.md b/claude/src/skills/shared/implementation-planning/SKILL.md index 8b194191..463ad295 100644 --- a/claude/src/skills/shared/implementation-planning/SKILL.md +++ b/claude/src/skills/shared/implementation-planning/SKILL.md @@ -77,12 +77,12 @@ Before finalizing agent assignments, verify each phase's agent can deliver its r | Phase Deliverable | Required Tier | Compatible Agents | |-------------------|--------------|-------------------| -| Creates/modifies files | Full Access or Read+Write | coder, data-engineer, devops-engineer, tester, refactor, design-system-engineer, i18n-specialist, analytics-engineer, technical-writer, product-manager, ux-designer, copywriter | -| Runs shell commands | Full Access or Read+Shell | coder, data-engineer, devops-engineer, tester, refactor, design-system-engineer, i18n-specialist, analytics-engineer, debugger, performance-engineer, security-engineer, seo-specialist, accessibility-specialist | +| Creates/modifies files | Full Access or Read+Write | analytics-engineer, cobol-engineer, coder, copywriter, data-engineer, design-system-engineer, devops-engineer, hlasm-assembler-specialist, i18n-specialist, ibm-i-specialist, integration-engineer, ml-engineer, mlops-engineer, mobile-engineer, observability-engineer, platform-engineer, product-manager, prompt-engineer, refactor, release-manager, technical-writer, tester, ux-designer | +| Runs shell commands | Full Access or Read+Shell | accessibility-specialist, analytics-engineer, cobol-engineer, coder, data-engineer, database-administrator, db2-dba, debugger, design-system-engineer, devops-engineer, hlasm-assembler-specialist, i18n-specialist, ibm-i-specialist, integration-engineer, ml-engineer, mlops-engineer, mobile-engineer, observability-engineer, performance-engineer, platform-engineer, refactor, security-engineer, seo-specialist, site-reliability-engineer, tester, zos-sysprog | | Analysis/review only | Any tier | All agents | -Read-Only agents (architect, api-designer, code-reviewer, content-strategist, compliance-reviewer) +Read-Only agents (architect, api-designer, cloud-architect, code-reviewer, compliance-reviewer, content-strategist, solutions-architect) CANNOT be assigned to phases that create or modify files. If a phase requires file creation and domain expertise from a Read-Only agent, split it: the Read-Only agent produces a spec or analysis, then a write-capable agent (typically coder) implements the files based on that output. @@ -180,17 +180,26 @@ If `validate_plan` is available, review its `parallelization_profile` and `redun | Task Domain | Primary Agent | Secondary Agent | Rationale | |-------------|--------------|-----------------|-----------| | System design, architecture | `architect` | - | Read-only analysis, design expertise | +| Cloud architecture, multi-region topology | `cloud-architect` | `devops-engineer` | Architecture first, implementation second | +| Enterprise integration architecture | `solutions-architect` | `integration-engineer` | Cross-team design before implementation | | API contracts, endpoints | `api-designer` | `coder` | Design then implement | | Feature implementation | `coder` | - | Full implementation access | | Code quality review | `code-reviewer` | - | Read-only verification | | Database schema, queries | `data-engineer` | - | Schema + implementation | +| RDBMS tuning, indexes, migration safety | `database-administrator` | `data-engineer` | DBA analysis before schema/code changes | +| DB2 administration | `db2-dba` | `data-engineer` | DB2-specific operations and design | | Bug investigation | `debugger` | - | Read + shell for investigation | | CI/CD, infrastructure | `devops-engineer` | - | Full DevOps access | +| Internal platforms, paved paths | `platform-engineer` | `devops-engineer` | Platform conventions and implementation | +| B2B integrations, ETL, message brokers | `integration-engineer` | - | Full integration implementation | +| SLOs, runbooks, reliability | `site-reliability-engineer` | `observability-engineer` | Reliability assessment plus telemetry implementation | +| Observability, metrics, traces | `observability-engineer` | - | Full telemetry implementation | | Performance analysis | `performance-engineer` | - | Read + shell for profiling | | Code restructuring | `refactor` | - | Write + shell access (for validation) | | Security assessment | `security-engineer` | - | Read + shell for scanning | | Test creation | `tester` | - | Full test implementation | | Documentation | `technical-writer` | - | Write access for docs | +| Release notes, changelogs, rollout | `release-manager` | - | Write access for release artifacts | | Technical SEO audit | `seo-specialist` | - | Read + shell + web search | | Marketing copy, content | `copywriter` | - | Read/write | | Content planning | `content-strategist` | - | Read + web search/fetch | @@ -201,6 +210,14 @@ If `validate_plan` is available, review its `parallelization_profile` and `redun | Internationalization | `i18n-specialist` | `coder` | Implement then localize | | Design tokens, theming | `design-system-engineer` | `coder` | Tokens then consume | | Legal, regulatory | `compliance-reviewer` | - | Read + web search/fetch | +| Mobile platform work | `mobile-engineer` | `tester` | Mobile implementation plus validation | +| Model training, inference integration | `ml-engineer` | `tester` | ML implementation plus evaluation | +| Model registry, drift, model CI/CD | `mlops-engineer` | `devops-engineer` | Model operations and deployment | +| Prompt design, few-shot, RAG tuning | `prompt-engineer` | `coder` | Prompt spec before integration | +| Mainframe COBOL, JCL, CICS/IMS | `cobol-engineer` | `tester` | Mainframe implementation and validation | +| IBM HLASM for z/OS | `hlasm-assembler-specialist` | - | Assembly implementation | +| IBM i RPG/CL, DB2 for i | `ibm-i-specialist` | - | IBM i implementation | +| z/OS systems programming, JCL, RACF | `zos-sysprog` | `security-engineer` | System-level analysis and controls | ### Assignment Rules 1. Match the primary task domain to the agent specialization @@ -216,32 +233,19 @@ Estimate token consumption per phase based on: - Agent's max_turns limit as upper bound - Historical averages: ~500 input tokens per file read, ~200 output tokens per file written -### Cost Estimation +### Resource Estimation -#### Per-Phase Cost Factors -- **Model tier**: Pro agents (~$0.01/1K input, ~$0.04/1K output) vs Flash agents (~$0.001/1K input, ~$0.004/1K output) -- **Input complexity**: Number of files read, average file size, context from previous phases -- **Output complexity**: Lines of code generated, number of files created/modified -- **Retry budget**: Add 50% buffer per phase for potential retries (max 2 retries) +Do not invent provider pricing or model tiers. Agent model selection is runtime-owned through agent frontmatter and runtime configuration. Estimate execution size in stable, codebase-derived terms instead: -#### Estimation Formula -``` -Phase Cost = (input_tokens × input_rate + output_tokens × output_rate) × retry_multiplier -``` - -Where: -- `input_tokens` = files_to_read × 500 + context_tokens -- `output_tokens` = files_to_write × 200 + validation_output -- `retry_multiplier` = 1.5 (accounts for up to 2 retries) +- **Input complexity**: number of files likely to be read, average file size, and prior-phase context +- **Output complexity**: number of files created or modified, validation output volume, and expected handoff detail +- **Retry budget**: note phases likely to need retries because of broad file ownership, external dependencies, or uncertain validation -#### Plan-Level Cost Summary -Include this table in every implementation plan: +Include a lightweight plan-level resource summary when useful: -| Phase | Agent | Model | Est. Input | Est. Output | Est. Cost | -|-------|-------|-------|-----------|------------|----------| -| 1 | [agent] | [model] | [tokens] | [tokens] | [$X.XX] | -| ... | ... | ... | ... | ... | ... | -| **Total** | | | **[sum]** | **[sum]** | **[$X.XX]** | +| Phase | Agent | Est. Files Read | Est. Files Written | Retry Risk | Notes | +|-------|-------|-----------------|--------------------|------------|-------| +| 1 | [agent] | [N] | [N] | LOW/MEDIUM/HIGH | [why] | ## Plan Document Generation @@ -296,7 +300,7 @@ After writing the implementation plan: 1. Confirm the file path to the user 2. Present the dependency graph and execution strategy 3. Highlight parallel execution opportunities -4. Provide token budget estimates +4. Provide resource estimates when useful 5. If your runtime provides Plan Mode, call `exit_plan_mode` with the plan path to present the plan for user approval. If Plan Mode is not available, present the completed plan for user approval using the user-prompt tool from runtime context. 6. Ensure the approved plan is at `/plans/YYYY-MM-DD--impl-plan.md` as the permanent project reference (copy from the staging directory if Plan Mode was used) 7. Ask if the user is ready to proceed to execution (Phase 3) diff --git a/claude/src/skills/shared/session-management/SKILL.md b/claude/src/skills/shared/session-management/SKILL.md index 595e7720..fc9fcd6e 100644 --- a/claude/src/skills/shared/session-management/SKILL.md +++ b/claude/src/skills/shared/session-management/SKILL.md @@ -18,12 +18,12 @@ Detection: check whether MCP state tools appear in your available tools. If they ## Hook-Level Session State -Maestro hooks maintain a separate, transient state directory at `/tmp/maestro-hooks//` that is distinct from orchestration state in ``: +Maestro hooks maintain a separate, transient state directory under `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//` that is distinct from orchestration state in ``: | Concern | Orchestration State | Hook State | | --- | --- | --- | -| Location | `/state/` | `/tmp/maestro-hooks//` (Unix) or `/maestro-hooks//` (Windows) | -| Lifecycle | Created in Phase 2, archived in Phase 4 | Directory created by the session-start hook when an active session exists; active-agent file written by the pre-delegation hook and cleared by the post-delegation hook; stale directories pruned by both session-start and pre-delegation hooks | +| Location | `/state/` | `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//` | +| Lifecycle | Created at execution setup, archived in Phase 4 | Directory created by the session-start hook when an active session exists; active-agent file written by the pre-delegation hook and cleared by the post-delegation hook; stale directories pruned by both session-start and pre-delegation hooks | | Contents | Session metadata, phase tracking, token usage, file manifests | Active agent tracking file (`active-agent`) | | Persistence | Survives session restarts (supports `/maestro:resume`) | Ephemeral — lost on session end or system reboot | | Managed by | Orchestrator via session-management skill | The runtime's pre-delegation and post-delegation hooks | @@ -35,7 +35,7 @@ The orchestrator does not read or write hook-level state directly. It interacts ## Session Creation Protocol ### When to Create -For Standard workflow, create a new session when beginning Phase 2 (Team Assembly & Planning) of orchestration, after the design document has been approved. For Express workflow, create a session after the structured brief is approved (see Express Workflow section in the orchestrator template). +For Standard workflow, create a new session at execution setup after the design document and implementation plan are approved and the execution mode gate has resolved. For Express workflow, create a session after the structured brief is approved (see Express Workflow section in the orchestrator template). ### Session ID Format `YYYY-MM-DD-` diff --git a/claude/src/version.json b/claude/src/version.json index 5fe39fde..db43f847 100644 --- a/claude/src/version.json +++ b/claude/src/version.json @@ -1,3 +1,3 @@ { - "version": "1.6.3" + "version": "1.6.4" } diff --git a/docs/architecture.md b/docs/architecture.md index 91bd3939..5abe9c5b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -80,7 +80,7 @@ Each runtime (`src/platforms/*/runtime-config.js`) declares: | `agentNaming` | `snake_case` | `kebab-case` | `kebab-case` | `snake_case` | | `delegation.pattern` | `{{agent}}(query: "...")` | `Agent(subagent_type: "maestro:{{agent}}", prompt: "...")` | `spawn_agent(...)` | `{{agent}}(query: "...")` | | `env.extensionPath` | `extensionPath` | `CLAUDE_PLUGIN_ROOT` | `.` (relative) | `extensionPath` | -| `env.workspacePath` | `workspacePath` | `CLAUDE_PROJECT_DIR` | `MAESTRO_WORKSPACE_PATH` | `workspacePath` | +| `env.workspacePath` | `null` (manifest injects `MAESTRO_WORKSPACE_PATH=${workspacePath}`) | `CLAUDE_PROJECT_DIR` | `MAESTRO_WORKSPACE_PATH` | `workspacePath` | ### Entry-Point Registry @@ -97,7 +97,7 @@ Plus 3 core commands (orchestrate, execute, resume) maintained separately in `sr ## MCP Server Architecture -The MCP server is authored directly in modular source under `src/mcp/`. Gemini and Claude runtime roots expose thin public wrappers at `mcp/maestro-server.js` that resolve into the nearest generator-owned `src/mcp/maestro-server.js` payload. Codex has no in-plugin wrapper — it spawns the server via `npx` against the versioned `@josstei/maestro` npm package and the `maestro-mcp-server` bin (`bin/maestro-mcp-server.js`) declared in `package.json`. +The MCP server is authored directly in modular source under `src/mcp/`. Gemini and Qwen share the repo-root public wrapper at `mcp/maestro-server.js`; their manifests set `MAESTRO_RUNTIME` to select the runtime config. Claude exposes its own thin wrapper at `claude/mcp/maestro-server.js` so detached plugin installs can fall back to `claude/src/`. Codex has no in-plugin wrapper — it spawns the server via `npx` against the versioned `@josstei/maestro` npm package and the `maestro-mcp-server` bin (`bin/maestro-mcp-server.js`) declared in `package.json`. ### Module Structure @@ -145,7 +145,7 @@ The content tools (`get_agent`, `get_skill_content`) are filesystem-only in ever - Codex: `primary=filesystem`, `fallback=none` - Qwen: `primary=filesystem`, `fallback=none` -Gemini's and Claude's thin entrypoints at `mcp/maestro-server.js` use direct `require()` calls to resolve `src/mcp/maestro-server.js`. Gemini's entrypoint sets `MAESTRO_RUNTIME=gemini` and requires `../src/mcp/maestro-server` directly. Claude uses dual-resolution: it prefers the repo-level `src/mcp/maestro-server.js` via `fs.existsSync()` and falls back to the bundled detached payload (`claude/src/mcp/maestro-server.js`) when running outside the repo. Codex spawns `bin/maestro-mcp-server.js` via a release-versioned `npx -p @josstei/maestro@ maestro-mcp-server` invocation (declared in `plugins/maestro/.mcp.json`); the bin sets `MAESTRO_RUNTIME=codex` and `MAESTRO_EXTENSION_PATH`, then requires `../src/mcp/maestro-server`. +Gemini and Qwen use the shared repo-root entrypoint at `mcp/maestro-server.js`, which requires `../src/mcp/maestro-server` directly. Their generated manifests set `MAESTRO_RUNTIME=gemini` or `MAESTRO_RUNTIME=qwen` before launch. Claude uses dual-resolution: it prefers the repo-level `src/mcp/maestro-server.js` via `fs.existsSync()` and falls back to the bundled detached payload (`claude/src/mcp/maestro-server.js`) when running outside the repo. Codex spawns `bin/maestro-mcp-server.js` via a release-versioned `npx -p @josstei/maestro@ maestro-mcp-server` invocation (declared in `plugins/maestro/.mcp.json`); the bin sets `MAESTRO_RUNTIME=codex` and `MAESTRO_EXTENSION_PATH`, then requires `../src/mcp/maestro-server`. This makes one architectural rule explicit: @@ -156,9 +156,10 @@ This makes one architectural rule explicit: ### MCP Server Packaging -Gemini and Claude keep a public entrypoint at `mcp/maestro-server.js`; Codex invokes the server via `npx` against a published bin. All three are thin wrappers around `src/mcp/maestro-server.js`: +Gemini and Qwen share the repo-root public entrypoint at `mcp/maestro-server.js`, Claude keeps a runtime-local public entrypoint at `claude/mcp/maestro-server.js`, and Codex invokes the server via `npx` against a published bin. All are thin wrappers around `src/mcp/maestro-server.js`: -- **Gemini** (`mcp/maestro-server.js`): sets `MAESTRO_RUNTIME=gemini`, directly requires `../src/mcp/maestro-server` and calls `.main()` +- **Gemini** (`mcp/maestro-server.js`): launched with `MAESTRO_RUNTIME=gemini`, directly requires `../src/mcp/maestro-server` and calls `.main()` +- **Qwen** (`mcp/maestro-server.js`): launched with `MAESTRO_RUNTIME=qwen` from `qwen-extension.json`, using the same shared entrypoint as Gemini - **Claude** (`claude/mcp/maestro-server.js`): sets `MAESTRO_RUNTIME=claude`, uses `fs.existsSync()` to prefer repo `../../src/mcp/maestro-server.js` with fallback to bundled `../src/mcp/maestro-server.js` - **Codex** (`bin/maestro-mcp-server.js` invoked via `npx -y -p @josstei/maestro@ maestro-mcp-server` per `plugins/maestro/.mcp.json`): sets `MAESTRO_RUNTIME=codex` and `MAESTRO_EXTENSION_PATH`, then requires `../src/mcp/maestro-server` and calls `.main()` @@ -258,11 +259,23 @@ Uses matchers to filter by tool type. Timeout: 10s (5s for policy-enforcer). Con ### Policy Enforcement -Both runtimes block the same destructive commands (`rm -rf`, `git reset --hard`, `git clean`, heredocs) and require confirmation for redirects (`>`, `>>`, `tee`): +Gemini, Qwen, and Claude block the same destructive commands (`rm -rf`, `git reset --hard`, `git clean`, heredocs) and require confirmation for redirects (`>`, `>>`, `tee`): - **Gemini**: TOML policy rules in `policies/maestro.toml` +- **Qwen**: TOML policy rules in `policies/maestro.toml` - **Claude**: JavaScript policy-enforcer hook triggered on Bash tool use +### Qwen Hooks + +| Event | Script | Purpose | +|-------|--------|---------| +| `SessionStart` | session-start.js | Initialize hook state, prune stale sessions | +| `SubagentStart` | before-agent.js | Detect agent, inject session context | +| `SubagentStop` | after-agent.js | Validate handoff report format | +| `SessionEnd` | session-end.js | Clean up hook state | + +Qwen uses its own hook registration file at `qwen/hooks.json`, while reusing the repo-root hook runner and logic modules. + ### Hook State Ephemeral state stored in `/tmp/maestro-hooks-/`: @@ -287,15 +300,15 @@ Ephemeral state stored in `/tmp/maestro-hooks-/`: ## CI and Testing -For detailed documentation of all six GitHub Actions workflows, the release pipeline chain, and Mermaid flow diagrams, see [docs/cicd.md](cicd.md). +For detailed documentation of all seven GitHub Actions workflows, the release pipeline chain, and Mermaid flow diagrams, see [docs/cicd.md](cicd.md). ### Test Suite -54 test files with 851 tests using Node.js built-in `node:test`: +86 test files using Node.js built-in `node:test`: -- 30 unit tests (`tests/unit/`) -- 13 transform tests (`tests/transforms/`) -- 11 integration tests (`tests/integration/`) +- 53 unit test files (`tests/unit/`) +- 13 transform test files (`tests/transforms/`) +- 20 integration test files (`tests/integration/`) The justfile's `just test` target uses glob expansion (`tests/unit/*.test.js`, `tests/transforms/*.test.js`, `tests/integration/*.test.js`), diff --git a/docs/cicd.md b/docs/cicd.md index d480d69f..8a83362e 100644 --- a/docs/cicd.md +++ b/docs/cicd.md @@ -34,7 +34,7 @@ The six source-of-truth workflows share a common validation core: generate runti ### Purpose -The foundational CI gate. Enforces that all generated runtime adapters (Gemini, Claude Code, Codex) are in sync with canonical source in `src/`, and that the full test suite passes. Runs on every push and pull request targeting `main`. +The foundational CI gate. Enforces that all generated runtime adapters (Gemini CLI, Claude Code, Codex, and Qwen Code) are in sync with canonical source in `src/`, and that the full test suite passes. Runs on every push and pull request targeting `main`. ### Trigger @@ -371,7 +371,7 @@ graph TD | Item | Type | Purpose | |------|------|---------| -| `RELEASE_TOKEN` | Secret | Personal access token with write permissions; used for checkout, branch push, PR creation, and auto-merge. Required because the default `GITHUB_TOKEN` cannot trigger downstream workflows. | +| `RELEASE_TOKEN` | Secret | Personal access token with write permissions; used for checkout, branch push, PR creation, and PR labeling. Required because the default `GITHUB_TOKEN` cannot trigger downstream workflows. | **Permissions**: `contents: write`, `pull-requests: write` diff --git a/docs/flow.md b/docs/flow.md index 85867945..db0d741c 100644 --- a/docs/flow.md +++ b/docs/flow.md @@ -16,9 +16,10 @@ The orchestration workflow is defined by 41 steps (numbered 0 through 40) in `sr ▼ ┌─────────────────────────────────────────────────┐ │ CLASSIFICATION │ -│ Turn 2: Load architecture reference │ +│ Turn 2: Pre-load pre-execution skills │ │ Classify: simple / medium / complex │ -│ Route: simple → Express, else → Design │ +│ Route: simple → Express, else │ +│ finalize session_id + enter gate │ └───────────────────────┬─────────────────────────┘ ▼ ┌─────────────────────────────────────────────────┐ @@ -26,7 +27,7 @@ The orchestration workflow is defined by 41 steps (numbered 0 through 40) in `sr │ Load design-dialogue skill │ │ Structured conversation (depth: quick/std/deep)│ │ Present sections one-at-a-time for approval │ -│ Write design document to state_dir/plans/ │ +│ Exit Plan Mode, then record design approval │ └───────────────────────┬─────────────────────────┘ ▼ ┌─────────────────────────────────────────────────┐ @@ -46,8 +47,10 @@ The orchestration workflow is defined by 41 steps (numbered 0 through 40) in `sr │ For each phase: │ │ → get_agent for methodology │ │ → Delegate with protocols + context chain │ +│ → Resolve Blockers before phase transition │ │ → Parse Task Report + Downstream Context │ │ → transition_phase (HARD-GATE per phase) │ +│ → reconcile empty payloads when required │ └───────────────────────┬─────────────────────────┘ ▼ ┌─────────────────────────────────────────────────┐ @@ -150,9 +153,11 @@ Orchestrator Agent │ ├── ... (task work) ... │ ├── Run validation │ │ + │◄── ## Blockers (if any) ─────────┤ │◄── ## Task Report ───────────────┤ │◄── ## Downstream Context ────────┤ │ │ + ├── Resolve blockers if present │ ├── Parse handoff │ ├── transition_phase() │ └── Feed context to next phase │ @@ -212,11 +217,17 @@ Non-negotiable checkpoints that block progression: | Gate | Location | Condition | |------|----------|-----------| | Tech recommendations | Step 11 | Must recommend vanilla HTML/CSS/JS for static delivery unless framework explicitly required | +| Session ID | Step 9a | One finalized session ID must be reused for design approval, session creation, transitions, reconciliation, and archive | +| Design gate | Steps 9a/14a/21 | Standard workflow cannot create a session until approved design is recorded for the same session ID | | Design sections | Step 12 | Each section presented individually and approved | +| Design approval variant | Step 14a | Use content variant for Gemini; use path variant for Codex/Claude direct writes; never provide both | | validate_plan | Step 16 | Plan must pass validation before user sees it | +| Implementation plan variant | Step 21 | Use content variant for Gemini Plan Mode outputs; use path variant for direct workspace writes; never provide both | | Execution mode | Step 19 | Must present only Parallel and Sequential options | | Agent dispatch | Step 23 | Must dispatch by agent's registered tool directly | +| Blockers | Step 24 | Non-empty `## Blockers` must be answered and re-delegated before `transition_phase` | | transition_phase | Step 25 | Must be called individually for EVERY completed phase | +| Reconciliation | Step 25 | Empty file manifests plus empty downstream context require `scan_phase_changes` → user confirmation → `reconcile_phase` | | Code review | Step 28 | Critical/Major findings block completion | | Express 1-phase | Step 31 | Express sessions must have exactly one phase | | Express questions | Step 32 | Each question must use user prompt tool | diff --git a/docs/maestro-cheatsheet.md b/docs/maestro-cheatsheet.md index 7caba950..bd2f5167 100644 --- a/docs/maestro-cheatsheet.md +++ b/docs/maestro-cheatsheet.md @@ -142,6 +142,7 @@ Common paths: - Command entry point: `/maestro:*` - Same command surface as Gemini CLI +- Uses `qwen/agents/` and `qwen/hooks.json`; commands, policies, MCP, and hook runner are shared from the repository root ## 7. Hook Reference @@ -163,6 +164,13 @@ Common paths: - No runtime hooks +### Qwen Code + +- `SessionStart` +- `SubagentStart` +- `SubagentStop` +- `SessionEnd` + ## 8. Common Notes ### Codex CLI diff --git a/docs/overview.md b/docs/overview.md index e43c77ec..873f2386 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -33,7 +33,7 @@ Simple tasks use an **Express workflow** (1 agent, 1 phase), while medium/comple | Entry-point commands | 9 (+ 3 core) | | Runtime targets | 4 | | Source transforms | 6 | -| Test cases | see `just test` output (70+ files across unit, transforms, integration) | +| Test files | 86 files across unit, transforms, and integration | ## Project Structure @@ -57,7 +57,7 @@ maestro-orchestrate/ │ └── manifest.js # Declarative file mapping rules ├── scripts/ │ └── generate.js # Generator (manifest → output) -├── tests/ # 71 test files, 980 tests (see `just test` output) +├── tests/ # 86 test files across unit, transforms, and integration │ ├── agents/ # [generated] Gemini agent stubs ├── commands/maestro/ # [generated] Gemini TOML commands diff --git a/docs/runtime-codex.md b/docs/runtime-codex.md index ed3ba53d..f20d768b 100644 --- a/docs/runtime-codex.md +++ b/docs/runtime-codex.md @@ -183,15 +183,15 @@ plugins/maestro/ The runtime server is invoked via `npx` rather than a local wrapper file, so the plugin ships no local `mcp/` directory under `plugins/maestro/`. The bin entrypoint lives in the repo root `bin/maestro-mcp-server.js`; `node scripts/generate.js` derives `plugins/maestro/.mcp.json` from `package.json` so the plugin manifest and MCP package spec stay on the same version. -## Differences from Gemini and Claude - -| Aspect | Gemini | Claude | Codex | -|--------|--------|--------|-------| -| Agent names | snake_case | kebab-case | kebab-case | -| Delegation | Direct function call | Agent subagent | spawn_agent | -| Hooks | 4 events, no matchers | SessionStart, SessionEnd, PreToolUse + matchers | None | -| Policies | TOML rules | JS hook enforcer | None | -| Skill surface | N/A (commands) | 19 skills | plugin namespace `$maestro:*` | -| Path style | Variable passthrough | Env var refs | `npx` bin | -| Extra files | TOML policy rules | policy-enforcer | runtime guide | -| Runtime payload | thin entrypoint only | thin entrypoint + detached `src/` payload | npx bin + detached `src/` payload | +## Differences from Other Runtimes + +| Aspect | Gemini | Claude | Qwen | Codex | +|--------|--------|--------|------|-------| +| Agent names | snake_case | kebab-case | snake_case | kebab-case | +| Delegation | Direct function call | Agent subagent | Direct function call | spawn_agent | +| Hooks | 4 events, no matchers | SessionStart, SessionEnd, PreToolUse + matchers | 4 events in `qwen/hooks.json` | None | +| Policies | TOML rules | JS hook enforcer | TOML rules | None | +| Skill surface | N/A (commands) | 19 skills | N/A (Gemini-compatible commands) | plugin namespace `$maestro:*` | +| Path style | Variable passthrough | Env var refs | Variable passthrough | `npx` bin | +| Extra files | TOML policy rules | policy-enforcer | Qwen manifest, context, agents, hooks config | runtime guide | +| Runtime payload | thin entrypoint only | thin entrypoint + detached `src/` payload | shared root entrypoint + `qwen/` stubs | npx bin + detached `src/` payload | diff --git a/docs/runtime-gemini.md b/docs/runtime-gemini.md index 8e93c4b8..38def9bf 100644 --- a/docs/runtime-gemini.md +++ b/docs/runtime-gemini.md @@ -15,11 +15,14 @@ The Gemini CLI extension lives at the repository root. It is the primary runtime "command": "node", "args": ["${extensionPath}/mcp/maestro-server.js"], "cwd": "${extensionPath}", - "env": { "MAESTRO_WORKSPACE_PATH": "${workspacePath}" } + "env": { + "MAESTRO_RUNTIME": "gemini", + "MAESTRO_WORKSPACE_PATH": "${workspacePath}" + } } ``` -The public server at `mcp/maestro-server.js` is a thin adapter. It sets `MAESTRO_RUNTIME=gemini`, requires canonical `src/mcp/maestro-server.js` directly, and runs the Gemini runtime against shared source in `src/`. Gemini declares `primary: filesystem` and `fallback: none`. +The public server at `mcp/maestro-server.js` is a thin adapter. The manifest launches it with `MAESTRO_RUNTIME=gemini`; the adapter also defaults to Gemini if that env var is absent. It requires canonical `src/mcp/maestro-server.js` directly and runs the Gemini runtime against shared source in `src/`. Gemini declares `primary: filesystem` and `fallback: none`. ## Agent Naming diff --git a/docs/runtime-qwen.md b/docs/runtime-qwen.md index 2737a0ca..80ecd5de 100644 --- a/docs/runtime-qwen.md +++ b/docs/runtime-qwen.md @@ -15,11 +15,14 @@ The Qwen Code extension lives in `qwen/` (the output directory declared in `src/ "command": "node", "args": ["${extensionPath}/mcp/maestro-server.js"], "cwd": "${extensionPath}", - "env": { "MAESTRO_WORKSPACE_PATH": "${workspacePath}" } + "env": { + "MAESTRO_RUNTIME": "qwen", + "MAESTRO_WORKSPACE_PATH": "${workspacePath}" + } } ``` -The public server at `mcp/maestro-server.js` is a thin adapter. It sets `MAESTRO_RUNTIME=qwen`, requires canonical `src/mcp/maestro-server.js` directly, and runs the Qwen runtime against shared source in `src/`. Qwen declares `primary: filesystem` and `fallback: none`. +Qwen reuses the repo-root public server at `mcp/maestro-server.js`. The Qwen manifest launches that shared adapter with `MAESTRO_RUNTIME=qwen`; without that env var the adapter defaults to Gemini. The adapter requires canonical `src/mcp/maestro-server.js` directly and runs the Qwen runtime against shared source in `src/`. Qwen declares `primary: filesystem` and `fallback: none`. ## Agent Naming @@ -42,16 +45,16 @@ The Qwen runtime does not emit its own TOML command files. `src/generator/entry- ## Hooks -4 hook events (same lifecycle shape as Gemini): +4 hook events in `qwen/hooks.json`: | Event | Script | Purpose | |-------|--------|---------| | `SessionStart` | `hooks/hook-runner.js qwen session-start` | Initialize hook state, prune stale sessions | -| `BeforeAgent` | `hooks/hook-runner.js qwen before-agent` | Detect agent, inject session context | -| `AfterAgent` | `hooks/hook-runner.js qwen after-agent` | Validate Task Report + Downstream Context | +| `SubagentStart` | `hooks/hook-runner.js qwen before-agent` | Detect agent, inject session context | +| `SubagentStop` | `hooks/hook-runner.js qwen after-agent` | Validate Task Report + Downstream Context | | `SessionEnd` | `hooks/hook-runner.js qwen session-end` | Clean up hook state | -### AfterAgent Validation +### SubagentStop Validation Qwen uses the same post-delegation validation as Gemini: diff --git a/docs/usage.md b/docs/usage.md index cca89396..6dd3a935 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -11,7 +11,7 @@ node scripts/generate.js # Generate runtime adapters using package scripts npm run build -# Run all 980 tests across 71 files +# Run all tests across unit, transform, and integration suites node --test tests/unit/*.test.js tests/transforms/*.test.js tests/integration/*.test.js # Show unified diff of changes @@ -29,13 +29,13 @@ just test-transforms # Run only integration tests just test-integration -# Generate + verify zero drift (CI equivalent) +# Generate + verify zero drift in a clean worktree/CI checkout just check -# Full CI equivalent (check + test) +# Full CI equivalent in a clean worktree/CI checkout (check + check-layers + test) just ci -# Verify lib/ import-boundary rules (enforced by check target) +# Verify lib/ import-boundary rules just check-layers # Delete local branches whose remotes are gone @@ -44,11 +44,12 @@ just cleanup-branches ## Editing Workflow -1. Edit canonical source in `src/`. Maintain root docs (`README.md`, `EXAMPLES.md`, `USAGE.md`, `OVERVIEW.md`, `ARCHITECTURE.md`) directly, and do not edit generated `claude/`, `plugins/maestro/`, or `qwen/` output. +1. Edit canonical source in `src/`. Maintain hand-authored root docs (`README.md`, `EXAMPLES.md`, `USAGE.md`, `OVERVIEW.md`, `ARCHITECTURE.md`, `CONTRIBUTING.md`, `SECURITY.md`) directly. Do not edit generated runtime stubs, command files, hook adapters, detached payloads, or generated skill copies directly. 2. Run `node scripts/generate.js` or `npm run build` to regenerate runtime adapters -3. Run `node --test tests/unit/*.test.js tests/transforms/*.test.js tests/integration/*.test.js` (or `just test`) before committing -4. Commit canonical source, directly owned root docs, and generated adapter output together -5. CI will fail if runtime adapters drift from canonical `src/` +3. Run `node scripts/generate.js --diff` to confirm the generator has no additional pending output +4. Run `node --test tests/unit/*.test.js tests/transforms/*.test.js tests/integration/*.test.js` (or `just test`) before committing +5. Commit canonical source, directly owned root docs, and generated adapter output together +6. CI will fail if runtime adapters drift from canonical `src/`; `just check` and `just ci` are designed for clean worktrees because they end with `git diff --exit-code` ## Configuration @@ -72,6 +73,8 @@ All settings are resolved with precedence: environment variable > workspace `.en |----------|---------|---------| | `MAESTRO_EXTENSION_PATH` | Gemini | Override extension root path | | `MAESTRO_WORKSPACE_PATH` | Gemini | Workspace root (set by Gemini CLI) | +| `MAESTRO_EXTENSION_PATH` | Qwen | Override extension root path | +| `MAESTRO_WORKSPACE_PATH` | Qwen | Workspace root (set by Qwen Code) | | `MAESTRO_WORKSPACE_PATH` | Codex | Optional workspace root override; otherwise Codex uses MCP `roots/list` | | `CLAUDE_PLUGIN_ROOT` | Claude | Plugin root (set by Claude Code) | | `CLAUDE_PROJECT_DIR` | Claude | Project directory (set by Claude Code) | diff --git a/gemini-extension.json b/gemini-extension.json index f1d21065..5655d5da 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,6 +1,6 @@ { "name": "maestro", - "version": "1.6.3", + "version": "1.6.4", "description": "Multi-agent development orchestration platform — 39 specialists, 4-phase orchestration, native parallel subagents, persistent sessions, and standalone review/debug/security/perf/seo/a11y/compliance commands", "contextFileName": "GEMINI.md", "settings": [ @@ -48,6 +48,7 @@ ], "cwd": "${extensionPath}", "env": { + "MAESTRO_RUNTIME": "gemini", "MAESTRO_WORKSPACE_PATH": "${workspacePath}" } } diff --git a/package-lock.json b/package-lock.json index c61365e1..f3be4d73 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@josstei/maestro", - "version": "1.6.3", + "version": "1.6.4", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@josstei/maestro", - "version": "1.6.3", + "version": "1.6.4", "license": "Apache-2.0", "bin": { "maestro-install-codex": "scripts/install-codex-plugin.js", diff --git a/package.json b/package.json index f23c96e3..3ee21dab 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@josstei/maestro", - "version": "1.6.3", + "version": "1.6.4", "description": "Multi-agent development orchestration platform — 39 specialists, 4-phase workflows, 4 runtime targets (Gemini CLI, Claude Code, OpenAI Codex, Qwen Code)", "license": "Apache-2.0", "author": { @@ -30,9 +30,19 @@ }, "c8": { "all": true, - "reporter": ["text", "html", "lcov"], - "include": ["src/**/*.js", "scripts/**/*.js", "bin/**/*.js"], - "exclude": ["**/*.test.js"] + "reporter": [ + "text", + "html", + "lcov" + ], + "include": [ + "src/**/*.js", + "scripts/**/*.js", + "bin/**/*.js" + ], + "exclude": [ + "**/*.test.js" + ] }, "devDependencies": { "c8": "^10.1.3" diff --git a/plugins/maestro/.codex-plugin/plugin.json b/plugins/maestro/.codex-plugin/plugin.json index d9e227e4..3ccfd487 100644 --- a/plugins/maestro/.codex-plugin/plugin.json +++ b/plugins/maestro/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "maestro", - "version": "1.6.3", + "version": "1.6.4", "description": "Generated Codex runtime for Maestro's multi-agent design, planning, execution, and review workflows.", "author": { "name": "josstei", diff --git a/plugins/maestro/.mcp.json b/plugins/maestro/.mcp.json index b4e03ed1..6e34e45f 100644 --- a/plugins/maestro/.mcp.json +++ b/plugins/maestro/.mcp.json @@ -5,7 +5,7 @@ "args": [ "-y", "-p", - "@josstei/maestro@1.6.3", + "@josstei/maestro@1.6.4", "maestro-mcp-server" ], "env": { diff --git a/plugins/maestro/README.md b/plugins/maestro/README.md index 95ce3a2a..675728bb 100644 --- a/plugins/maestro/README.md +++ b/plugins/maestro/README.md @@ -22,7 +22,7 @@ codex plugin marketplace add /absolute/path/to/maestro-orchestrate ## Architecture -Codex shares the same canonical `src/` source tree as the Gemini CLI and Claude Code outputs: +Codex shares the same canonical `src/` source tree as the Gemini CLI, Claude Code, and Qwen Code outputs: - shared methodology, references, templates, hooks, and MCP server logic are authored only in `src/` - this plugin contains public entry skills, manifests, thin adapters, and a generated `./src/` runtime payload derived from canonical `src/` - Codex-specific behavior is isolated to this plugin's runtime guide and public entry skills, exposed under the plugin namespace as `$maestro:` @@ -54,4 +54,4 @@ Codex shares the same canonical `src/` source tree as the Gemini CLI and Claude ## Alignment goal -Codex is treated as a third generated runtime, not a separate implementation. If behavior changes, update shared `src/` first and regenerate. +Codex is treated as one of four generated runtimes, not a separate implementation. If behavior changes, update shared `src/` first and regenerate. diff --git a/plugins/maestro/src/platforms/shared/agent-names.js b/plugins/maestro/src/platforms/shared/agent-names.js index 086551d4..98a80e2e 100644 --- a/plugins/maestro/src/platforms/shared/agent-names.js +++ b/plugins/maestro/src/platforms/shared/agent-names.js @@ -1,10 +1,15 @@ module.exports = { agentNames: [ 'accessibility-specialist', 'analytics-engineer', 'api-designer', 'architect', - 'code-reviewer', 'coder', 'compliance-reviewer', 'content-strategist', - 'copywriter', 'data-engineer', 'debugger', 'design-system-engineer', - 'devops-engineer', 'i18n-specialist', 'performance-engineer', 'product-manager', - 'refactor', 'security-engineer', 'seo-specialist', 'technical-writer', - 'tester', 'ux-designer', + 'cloud-architect', 'cobol-engineer', 'code-reviewer', 'coder', + 'compliance-reviewer', 'content-strategist', 'copywriter', 'data-engineer', + 'database-administrator', 'db2-dba', 'debugger', 'design-system-engineer', + 'devops-engineer', 'hlasm-assembler-specialist', 'i18n-specialist', + 'ibm-i-specialist', 'integration-engineer', 'ml-engineer', 'mlops-engineer', + 'mobile-engineer', 'observability-engineer', 'performance-engineer', + 'platform-engineer', 'product-manager', 'prompt-engineer', 'refactor', + 'release-manager', 'security-engineer', 'seo-specialist', + 'site-reliability-engineer', 'solutions-architect', 'technical-writer', + 'tester', 'ux-designer', 'zos-sysprog', ], }; diff --git a/plugins/maestro/src/skills/shared/delegation/SKILL.md b/plugins/maestro/src/skills/shared/delegation/SKILL.md index 1e19cdb8..88e8f584 100644 --- a/plugins/maestro/src/skills/shared/delegation/SKILL.md +++ b/plugins/maestro/src/skills/shared/delegation/SKILL.md @@ -130,17 +130,26 @@ Explicitly state what the agent must NOT do: | Task Domain | Agent | Key Capability | |-------------|-------|---------------| | System architecture, component design | `architect` | Read-only analysis, architecture patterns | +| Cloud architecture, multi-region topology | `cloud-architect` | Read-only cloud/IaC architecture | +| Enterprise integration architecture | `solutions-architect` | Read-only cross-team architecture | | API contracts, endpoint design | `api-designer` | Read-only, REST/GraphQL expertise | | Feature implementation, coding | `coder` | Full read/write/shell access | | Code quality assessment | `code-reviewer` | Read-only, verified findings | | Database schema, queries, ETL | `data-engineer` | Full read/write/shell access | +| RDBMS tuning, indexes, migration safety | `database-administrator` | Read + shell for database analysis | +| DB2 operations and tuning | `db2-dba` | Read + shell for DB2-specific work | | Bug investigation, root cause | `debugger` | Read + shell for investigation | | CI/CD, infrastructure, deployment | `devops-engineer` | Full read/write/shell access | +| Internal platforms, paved paths | `platform-engineer` | Full platform implementation access | +| B2B APIs, ETL, message brokers | `integration-engineer` | Full integration implementation access | +| SLOs, runbooks, reliability | `site-reliability-engineer` | Read + shell reliability analysis | +| Metrics, logs, traces, dashboards | `observability-engineer` | Full observability implementation access | | Performance analysis, profiling | `performance-engineer` | Read + shell for profiling | | Code restructuring, modernization | `refactor` | Read/write/shell, skill activation | | Security assessment, vulnerability | `security-engineer` | Read + shell for scanning | | Test creation, TDD, coverage | `tester` | Full read/write/shell access | | Documentation, READMEs, guides | `technical-writer` | Read/write, no shell | +| Release notes, changelogs, rollout | `release-manager` | Read/write for release artifacts | | Technical SEO auditing | `seo-specialist` | Read + shell + web search/fetch | | Marketing copy, content writing | `copywriter` | Read/write | | Content planning, strategy | `content-strategist` | Read + web search/fetch | @@ -151,6 +160,14 @@ Explicitly state what the agent must NOT do: | Internationalization | `i18n-specialist` | Full read/write/shell access | | Design tokens, theming | `design-system-engineer` | Full read/write/shell access | | Legal, regulatory compliance | `compliance-reviewer` | Read + web search/fetch | +| Mobile platform work | `mobile-engineer` | Full mobile implementation access | +| Model training and inference integration | `ml-engineer` | Full ML implementation access | +| Model operations and model CI/CD | `mlops-engineer` | Full MLOps implementation access | +| Prompt design, few-shot, RAG tuning | `prompt-engineer` | Read/write prompt and eval design | +| Mainframe COBOL, JCL, CICS/IMS | `cobol-engineer` | Full mainframe implementation access | +| IBM HLASM for z/OS | `hlasm-assembler-specialist` | Full assembly implementation access | +| IBM i RPG/CL, DB2 for i | `ibm-i-specialist` | Full IBM i implementation access | +| z/OS systems programming, JCL, RACF | `zos-sysprog` | Read + shell for z/OS system work | ## Agent Tool Dispatch Contract @@ -269,7 +286,7 @@ Before each agent dispatch, a hook tracks which agent is currently executing: - Preferred signal: the required `Agent: ` header in the delegation prompt - Legacy fallbacks: `MAESTRO_CURRENT_AGENT` from the environment, then regex-based detection of patterns like `delegate to ` or `@` -The detected agent name is persisted to `/tmp/maestro-hooks//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. +The detected agent name is persisted to `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//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. ### Session Context Injection diff --git a/plugins/maestro/src/skills/shared/design-dialogue/SKILL.md b/plugins/maestro/src/skills/shared/design-dialogue/SKILL.md index ebbba70c..60cef0fa 100644 --- a/plugins/maestro/src/skills/shared/design-dialogue/SKILL.md +++ b/plugins/maestro/src/skills/shared/design-dialogue/SKILL.md @@ -257,7 +257,7 @@ Apply depth-gated reasoning enrichment to design section content during the conv The write path depends on whether your runtime provides a Plan Mode surface (check `get_runtime_context`, loaded at session start, step 0): -- **Plan Mode active**: Some runtimes restrict writes to a temporary staging directory during Plan Mode. Write the design document there. After `exit_plan_mode` approval in Phase 2, copy it to the permanent location. +- **Plan Mode active**: Some runtimes restrict writes to a temporary staging directory during Plan Mode. Write the design document there first, then exit Plan Mode and complete the design approval handoff. When the runtime's Plan Mode path is not visible to the MCP server, use the `record_design_approval` content variant so the server materializes the canonical copy under `/plans/`. - **Plan Mode not active or not available**: Write directly to the permanent location. If your runtime does not provide Plan Mode, track design progress using the plan-update mechanism from runtime context and use the user-prompt tool from runtime context for section approvals and final signoff. Permanent location: `/plans/YYYY-MM-DD--design.md` (where `` resolves from `MAESTRO_STATE_DIR`, default `docs/maestro`). diff --git a/plugins/maestro/src/skills/shared/execution/SKILL.md b/plugins/maestro/src/skills/shared/execution/SKILL.md index 1ed110a0..167b4eea 100644 --- a/plugins/maestro/src/skills/shared/execution/SKILL.md +++ b/plugins/maestro/src/skills/shared/execution/SKILL.md @@ -121,7 +121,7 @@ Hooks fire automatically at agent boundaries. The orchestrator does not invoke t The hooks system tracks which agent is currently executing. Before each agent dispatch, a hook resolves the active agent identity from the required `Agent:` header first, then falls back to legacy env/regex detection, and injects compact session context. After completion, a hook validates that the response contains both `Task Report` and `Downstream Context`; it requests one retry on the first malformed response. -The hook state directory under `/tmp/maestro-hooks//` is transient and separate from orchestration state. +The hook state directory under `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//` is transient and separate from orchestration state. ## Sequential Execution Protocol diff --git a/plugins/maestro/src/skills/shared/implementation-planning/SKILL.md b/plugins/maestro/src/skills/shared/implementation-planning/SKILL.md index 8b194191..463ad295 100644 --- a/plugins/maestro/src/skills/shared/implementation-planning/SKILL.md +++ b/plugins/maestro/src/skills/shared/implementation-planning/SKILL.md @@ -77,12 +77,12 @@ Before finalizing agent assignments, verify each phase's agent can deliver its r | Phase Deliverable | Required Tier | Compatible Agents | |-------------------|--------------|-------------------| -| Creates/modifies files | Full Access or Read+Write | coder, data-engineer, devops-engineer, tester, refactor, design-system-engineer, i18n-specialist, analytics-engineer, technical-writer, product-manager, ux-designer, copywriter | -| Runs shell commands | Full Access or Read+Shell | coder, data-engineer, devops-engineer, tester, refactor, design-system-engineer, i18n-specialist, analytics-engineer, debugger, performance-engineer, security-engineer, seo-specialist, accessibility-specialist | +| Creates/modifies files | Full Access or Read+Write | analytics-engineer, cobol-engineer, coder, copywriter, data-engineer, design-system-engineer, devops-engineer, hlasm-assembler-specialist, i18n-specialist, ibm-i-specialist, integration-engineer, ml-engineer, mlops-engineer, mobile-engineer, observability-engineer, platform-engineer, product-manager, prompt-engineer, refactor, release-manager, technical-writer, tester, ux-designer | +| Runs shell commands | Full Access or Read+Shell | accessibility-specialist, analytics-engineer, cobol-engineer, coder, data-engineer, database-administrator, db2-dba, debugger, design-system-engineer, devops-engineer, hlasm-assembler-specialist, i18n-specialist, ibm-i-specialist, integration-engineer, ml-engineer, mlops-engineer, mobile-engineer, observability-engineer, performance-engineer, platform-engineer, refactor, security-engineer, seo-specialist, site-reliability-engineer, tester, zos-sysprog | | Analysis/review only | Any tier | All agents | -Read-Only agents (architect, api-designer, code-reviewer, content-strategist, compliance-reviewer) +Read-Only agents (architect, api-designer, cloud-architect, code-reviewer, compliance-reviewer, content-strategist, solutions-architect) CANNOT be assigned to phases that create or modify files. If a phase requires file creation and domain expertise from a Read-Only agent, split it: the Read-Only agent produces a spec or analysis, then a write-capable agent (typically coder) implements the files based on that output. @@ -180,17 +180,26 @@ If `validate_plan` is available, review its `parallelization_profile` and `redun | Task Domain | Primary Agent | Secondary Agent | Rationale | |-------------|--------------|-----------------|-----------| | System design, architecture | `architect` | - | Read-only analysis, design expertise | +| Cloud architecture, multi-region topology | `cloud-architect` | `devops-engineer` | Architecture first, implementation second | +| Enterprise integration architecture | `solutions-architect` | `integration-engineer` | Cross-team design before implementation | | API contracts, endpoints | `api-designer` | `coder` | Design then implement | | Feature implementation | `coder` | - | Full implementation access | | Code quality review | `code-reviewer` | - | Read-only verification | | Database schema, queries | `data-engineer` | - | Schema + implementation | +| RDBMS tuning, indexes, migration safety | `database-administrator` | `data-engineer` | DBA analysis before schema/code changes | +| DB2 administration | `db2-dba` | `data-engineer` | DB2-specific operations and design | | Bug investigation | `debugger` | - | Read + shell for investigation | | CI/CD, infrastructure | `devops-engineer` | - | Full DevOps access | +| Internal platforms, paved paths | `platform-engineer` | `devops-engineer` | Platform conventions and implementation | +| B2B integrations, ETL, message brokers | `integration-engineer` | - | Full integration implementation | +| SLOs, runbooks, reliability | `site-reliability-engineer` | `observability-engineer` | Reliability assessment plus telemetry implementation | +| Observability, metrics, traces | `observability-engineer` | - | Full telemetry implementation | | Performance analysis | `performance-engineer` | - | Read + shell for profiling | | Code restructuring | `refactor` | - | Write + shell access (for validation) | | Security assessment | `security-engineer` | - | Read + shell for scanning | | Test creation | `tester` | - | Full test implementation | | Documentation | `technical-writer` | - | Write access for docs | +| Release notes, changelogs, rollout | `release-manager` | - | Write access for release artifacts | | Technical SEO audit | `seo-specialist` | - | Read + shell + web search | | Marketing copy, content | `copywriter` | - | Read/write | | Content planning | `content-strategist` | - | Read + web search/fetch | @@ -201,6 +210,14 @@ If `validate_plan` is available, review its `parallelization_profile` and `redun | Internationalization | `i18n-specialist` | `coder` | Implement then localize | | Design tokens, theming | `design-system-engineer` | `coder` | Tokens then consume | | Legal, regulatory | `compliance-reviewer` | - | Read + web search/fetch | +| Mobile platform work | `mobile-engineer` | `tester` | Mobile implementation plus validation | +| Model training, inference integration | `ml-engineer` | `tester` | ML implementation plus evaluation | +| Model registry, drift, model CI/CD | `mlops-engineer` | `devops-engineer` | Model operations and deployment | +| Prompt design, few-shot, RAG tuning | `prompt-engineer` | `coder` | Prompt spec before integration | +| Mainframe COBOL, JCL, CICS/IMS | `cobol-engineer` | `tester` | Mainframe implementation and validation | +| IBM HLASM for z/OS | `hlasm-assembler-specialist` | - | Assembly implementation | +| IBM i RPG/CL, DB2 for i | `ibm-i-specialist` | - | IBM i implementation | +| z/OS systems programming, JCL, RACF | `zos-sysprog` | `security-engineer` | System-level analysis and controls | ### Assignment Rules 1. Match the primary task domain to the agent specialization @@ -216,32 +233,19 @@ Estimate token consumption per phase based on: - Agent's max_turns limit as upper bound - Historical averages: ~500 input tokens per file read, ~200 output tokens per file written -### Cost Estimation +### Resource Estimation -#### Per-Phase Cost Factors -- **Model tier**: Pro agents (~$0.01/1K input, ~$0.04/1K output) vs Flash agents (~$0.001/1K input, ~$0.004/1K output) -- **Input complexity**: Number of files read, average file size, context from previous phases -- **Output complexity**: Lines of code generated, number of files created/modified -- **Retry budget**: Add 50% buffer per phase for potential retries (max 2 retries) +Do not invent provider pricing or model tiers. Agent model selection is runtime-owned through agent frontmatter and runtime configuration. Estimate execution size in stable, codebase-derived terms instead: -#### Estimation Formula -``` -Phase Cost = (input_tokens × input_rate + output_tokens × output_rate) × retry_multiplier -``` - -Where: -- `input_tokens` = files_to_read × 500 + context_tokens -- `output_tokens` = files_to_write × 200 + validation_output -- `retry_multiplier` = 1.5 (accounts for up to 2 retries) +- **Input complexity**: number of files likely to be read, average file size, and prior-phase context +- **Output complexity**: number of files created or modified, validation output volume, and expected handoff detail +- **Retry budget**: note phases likely to need retries because of broad file ownership, external dependencies, or uncertain validation -#### Plan-Level Cost Summary -Include this table in every implementation plan: +Include a lightweight plan-level resource summary when useful: -| Phase | Agent | Model | Est. Input | Est. Output | Est. Cost | -|-------|-------|-------|-----------|------------|----------| -| 1 | [agent] | [model] | [tokens] | [tokens] | [$X.XX] | -| ... | ... | ... | ... | ... | ... | -| **Total** | | | **[sum]** | **[sum]** | **[$X.XX]** | +| Phase | Agent | Est. Files Read | Est. Files Written | Retry Risk | Notes | +|-------|-------|-----------------|--------------------|------------|-------| +| 1 | [agent] | [N] | [N] | LOW/MEDIUM/HIGH | [why] | ## Plan Document Generation @@ -296,7 +300,7 @@ After writing the implementation plan: 1. Confirm the file path to the user 2. Present the dependency graph and execution strategy 3. Highlight parallel execution opportunities -4. Provide token budget estimates +4. Provide resource estimates when useful 5. If your runtime provides Plan Mode, call `exit_plan_mode` with the plan path to present the plan for user approval. If Plan Mode is not available, present the completed plan for user approval using the user-prompt tool from runtime context. 6. Ensure the approved plan is at `/plans/YYYY-MM-DD--impl-plan.md` as the permanent project reference (copy from the staging directory if Plan Mode was used) 7. Ask if the user is ready to proceed to execution (Phase 3) diff --git a/plugins/maestro/src/skills/shared/session-management/SKILL.md b/plugins/maestro/src/skills/shared/session-management/SKILL.md index 595e7720..fc9fcd6e 100644 --- a/plugins/maestro/src/skills/shared/session-management/SKILL.md +++ b/plugins/maestro/src/skills/shared/session-management/SKILL.md @@ -18,12 +18,12 @@ Detection: check whether MCP state tools appear in your available tools. If they ## Hook-Level Session State -Maestro hooks maintain a separate, transient state directory at `/tmp/maestro-hooks//` that is distinct from orchestration state in ``: +Maestro hooks maintain a separate, transient state directory under `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//` that is distinct from orchestration state in ``: | Concern | Orchestration State | Hook State | | --- | --- | --- | -| Location | `/state/` | `/tmp/maestro-hooks//` (Unix) or `/maestro-hooks//` (Windows) | -| Lifecycle | Created in Phase 2, archived in Phase 4 | Directory created by the session-start hook when an active session exists; active-agent file written by the pre-delegation hook and cleared by the post-delegation hook; stale directories pruned by both session-start and pre-delegation hooks | +| Location | `/state/` | `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//` | +| Lifecycle | Created at execution setup, archived in Phase 4 | Directory created by the session-start hook when an active session exists; active-agent file written by the pre-delegation hook and cleared by the post-delegation hook; stale directories pruned by both session-start and pre-delegation hooks | | Contents | Session metadata, phase tracking, token usage, file manifests | Active agent tracking file (`active-agent`) | | Persistence | Survives session restarts (supports `/maestro:resume`) | Ephemeral — lost on session end or system reboot | | Managed by | Orchestrator via session-management skill | The runtime's pre-delegation and post-delegation hooks | @@ -35,7 +35,7 @@ The orchestrator does not read or write hook-level state directly. It interacts ## Session Creation Protocol ### When to Create -For Standard workflow, create a new session when beginning Phase 2 (Team Assembly & Planning) of orchestration, after the design document has been approved. For Express workflow, create a session after the structured brief is approved (see Express Workflow section in the orchestrator template). +For Standard workflow, create a new session at execution setup after the design document and implementation plan are approved and the execution mode gate has resolved. For Express workflow, create a session after the structured brief is approved (see Express Workflow section in the orchestrator template). ### Session ID Format `YYYY-MM-DD-` diff --git a/plugins/maestro/src/version.json b/plugins/maestro/src/version.json index 5fe39fde..db43f847 100644 --- a/plugins/maestro/src/version.json +++ b/plugins/maestro/src/version.json @@ -1,3 +1,3 @@ { - "version": "1.6.3" + "version": "1.6.4" } diff --git a/qwen-extension.json b/qwen-extension.json index 1a5724de..5457a7c3 100644 --- a/qwen-extension.json +++ b/qwen-extension.json @@ -1,6 +1,6 @@ { "name": "maestro", - "version": "1.6.3", + "version": "1.6.4", "description": "Multi-agent development orchestration platform — 39 specialists, 4-phase orchestration, native parallel subagents, persistent sessions, and standalone review/debug/security/perf/seo/a11y/compliance commands", "contextFileName": "QWEN.md", "settings": [ @@ -48,6 +48,7 @@ ], "cwd": "${extensionPath}", "env": { + "MAESTRO_RUNTIME": "qwen", "MAESTRO_WORKSPACE_PATH": "${workspacePath}" } } diff --git a/src/platforms/metadata-shared.js b/src/platforms/metadata-shared.js index 6787af64..62fa8106 100644 --- a/src/platforms/metadata-shared.js +++ b/src/platforms/metadata-shared.js @@ -85,7 +85,9 @@ function buildSettings() { } function buildExtensionMcpServer(runtime) { - const env = {}; + const env = { + MAESTRO_RUNTIME: runtime, + }; if (runtime === 'qwen' || runtime === 'gemini') { env.MAESTRO_WORKSPACE_PATH = '${workspacePath}'; diff --git a/src/platforms/shared/agent-names.js b/src/platforms/shared/agent-names.js index 086551d4..98a80e2e 100644 --- a/src/platforms/shared/agent-names.js +++ b/src/platforms/shared/agent-names.js @@ -1,10 +1,15 @@ module.exports = { agentNames: [ 'accessibility-specialist', 'analytics-engineer', 'api-designer', 'architect', - 'code-reviewer', 'coder', 'compliance-reviewer', 'content-strategist', - 'copywriter', 'data-engineer', 'debugger', 'design-system-engineer', - 'devops-engineer', 'i18n-specialist', 'performance-engineer', 'product-manager', - 'refactor', 'security-engineer', 'seo-specialist', 'technical-writer', - 'tester', 'ux-designer', + 'cloud-architect', 'cobol-engineer', 'code-reviewer', 'coder', + 'compliance-reviewer', 'content-strategist', 'copywriter', 'data-engineer', + 'database-administrator', 'db2-dba', 'debugger', 'design-system-engineer', + 'devops-engineer', 'hlasm-assembler-specialist', 'i18n-specialist', + 'ibm-i-specialist', 'integration-engineer', 'ml-engineer', 'mlops-engineer', + 'mobile-engineer', 'observability-engineer', 'performance-engineer', + 'platform-engineer', 'product-manager', 'prompt-engineer', 'refactor', + 'release-manager', 'security-engineer', 'seo-specialist', + 'site-reliability-engineer', 'solutions-architect', 'technical-writer', + 'tester', 'ux-designer', 'zos-sysprog', ], }; diff --git a/src/skills/shared/delegation/SKILL.md b/src/skills/shared/delegation/SKILL.md index 1e19cdb8..88e8f584 100644 --- a/src/skills/shared/delegation/SKILL.md +++ b/src/skills/shared/delegation/SKILL.md @@ -130,17 +130,26 @@ Explicitly state what the agent must NOT do: | Task Domain | Agent | Key Capability | |-------------|-------|---------------| | System architecture, component design | `architect` | Read-only analysis, architecture patterns | +| Cloud architecture, multi-region topology | `cloud-architect` | Read-only cloud/IaC architecture | +| Enterprise integration architecture | `solutions-architect` | Read-only cross-team architecture | | API contracts, endpoint design | `api-designer` | Read-only, REST/GraphQL expertise | | Feature implementation, coding | `coder` | Full read/write/shell access | | Code quality assessment | `code-reviewer` | Read-only, verified findings | | Database schema, queries, ETL | `data-engineer` | Full read/write/shell access | +| RDBMS tuning, indexes, migration safety | `database-administrator` | Read + shell for database analysis | +| DB2 operations and tuning | `db2-dba` | Read + shell for DB2-specific work | | Bug investigation, root cause | `debugger` | Read + shell for investigation | | CI/CD, infrastructure, deployment | `devops-engineer` | Full read/write/shell access | +| Internal platforms, paved paths | `platform-engineer` | Full platform implementation access | +| B2B APIs, ETL, message brokers | `integration-engineer` | Full integration implementation access | +| SLOs, runbooks, reliability | `site-reliability-engineer` | Read + shell reliability analysis | +| Metrics, logs, traces, dashboards | `observability-engineer` | Full observability implementation access | | Performance analysis, profiling | `performance-engineer` | Read + shell for profiling | | Code restructuring, modernization | `refactor` | Read/write/shell, skill activation | | Security assessment, vulnerability | `security-engineer` | Read + shell for scanning | | Test creation, TDD, coverage | `tester` | Full read/write/shell access | | Documentation, READMEs, guides | `technical-writer` | Read/write, no shell | +| Release notes, changelogs, rollout | `release-manager` | Read/write for release artifacts | | Technical SEO auditing | `seo-specialist` | Read + shell + web search/fetch | | Marketing copy, content writing | `copywriter` | Read/write | | Content planning, strategy | `content-strategist` | Read + web search/fetch | @@ -151,6 +160,14 @@ Explicitly state what the agent must NOT do: | Internationalization | `i18n-specialist` | Full read/write/shell access | | Design tokens, theming | `design-system-engineer` | Full read/write/shell access | | Legal, regulatory compliance | `compliance-reviewer` | Read + web search/fetch | +| Mobile platform work | `mobile-engineer` | Full mobile implementation access | +| Model training and inference integration | `ml-engineer` | Full ML implementation access | +| Model operations and model CI/CD | `mlops-engineer` | Full MLOps implementation access | +| Prompt design, few-shot, RAG tuning | `prompt-engineer` | Read/write prompt and eval design | +| Mainframe COBOL, JCL, CICS/IMS | `cobol-engineer` | Full mainframe implementation access | +| IBM HLASM for z/OS | `hlasm-assembler-specialist` | Full assembly implementation access | +| IBM i RPG/CL, DB2 for i | `ibm-i-specialist` | Full IBM i implementation access | +| z/OS systems programming, JCL, RACF | `zos-sysprog` | Read + shell for z/OS system work | ## Agent Tool Dispatch Contract @@ -269,7 +286,7 @@ Before each agent dispatch, a hook tracks which agent is currently executing: - Preferred signal: the required `Agent: ` header in the delegation prompt - Legacy fallbacks: `MAESTRO_CURRENT_AGENT` from the environment, then regex-based detection of patterns like `delegate to ` or `@` -The detected agent name is persisted to `/tmp/maestro-hooks//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. +The detected agent name is persisted to `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//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. ### Session Context Injection diff --git a/src/skills/shared/design-dialogue/SKILL.md b/src/skills/shared/design-dialogue/SKILL.md index ebbba70c..60cef0fa 100644 --- a/src/skills/shared/design-dialogue/SKILL.md +++ b/src/skills/shared/design-dialogue/SKILL.md @@ -257,7 +257,7 @@ Apply depth-gated reasoning enrichment to design section content during the conv The write path depends on whether your runtime provides a Plan Mode surface (check `get_runtime_context`, loaded at session start, step 0): -- **Plan Mode active**: Some runtimes restrict writes to a temporary staging directory during Plan Mode. Write the design document there. After `exit_plan_mode` approval in Phase 2, copy it to the permanent location. +- **Plan Mode active**: Some runtimes restrict writes to a temporary staging directory during Plan Mode. Write the design document there first, then exit Plan Mode and complete the design approval handoff. When the runtime's Plan Mode path is not visible to the MCP server, use the `record_design_approval` content variant so the server materializes the canonical copy under `/plans/`. - **Plan Mode not active or not available**: Write directly to the permanent location. If your runtime does not provide Plan Mode, track design progress using the plan-update mechanism from runtime context and use the user-prompt tool from runtime context for section approvals and final signoff. Permanent location: `/plans/YYYY-MM-DD--design.md` (where `` resolves from `MAESTRO_STATE_DIR`, default `docs/maestro`). diff --git a/src/skills/shared/execution/SKILL.md b/src/skills/shared/execution/SKILL.md index 1ed110a0..167b4eea 100644 --- a/src/skills/shared/execution/SKILL.md +++ b/src/skills/shared/execution/SKILL.md @@ -121,7 +121,7 @@ Hooks fire automatically at agent boundaries. The orchestrator does not invoke t The hooks system tracks which agent is currently executing. Before each agent dispatch, a hook resolves the active agent identity from the required `Agent:` header first, then falls back to legacy env/regex detection, and injects compact session context. After completion, a hook validates that the response contains both `Task Report` and `Downstream Context`; it requests one retry on the first malformed response. -The hook state directory under `/tmp/maestro-hooks//` is transient and separate from orchestration state. +The hook state directory under `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//` is transient and separate from orchestration state. ## Sequential Execution Protocol diff --git a/src/skills/shared/implementation-planning/SKILL.md b/src/skills/shared/implementation-planning/SKILL.md index 8b194191..463ad295 100644 --- a/src/skills/shared/implementation-planning/SKILL.md +++ b/src/skills/shared/implementation-planning/SKILL.md @@ -77,12 +77,12 @@ Before finalizing agent assignments, verify each phase's agent can deliver its r | Phase Deliverable | Required Tier | Compatible Agents | |-------------------|--------------|-------------------| -| Creates/modifies files | Full Access or Read+Write | coder, data-engineer, devops-engineer, tester, refactor, design-system-engineer, i18n-specialist, analytics-engineer, technical-writer, product-manager, ux-designer, copywriter | -| Runs shell commands | Full Access or Read+Shell | coder, data-engineer, devops-engineer, tester, refactor, design-system-engineer, i18n-specialist, analytics-engineer, debugger, performance-engineer, security-engineer, seo-specialist, accessibility-specialist | +| Creates/modifies files | Full Access or Read+Write | analytics-engineer, cobol-engineer, coder, copywriter, data-engineer, design-system-engineer, devops-engineer, hlasm-assembler-specialist, i18n-specialist, ibm-i-specialist, integration-engineer, ml-engineer, mlops-engineer, mobile-engineer, observability-engineer, platform-engineer, product-manager, prompt-engineer, refactor, release-manager, technical-writer, tester, ux-designer | +| Runs shell commands | Full Access or Read+Shell | accessibility-specialist, analytics-engineer, cobol-engineer, coder, data-engineer, database-administrator, db2-dba, debugger, design-system-engineer, devops-engineer, hlasm-assembler-specialist, i18n-specialist, ibm-i-specialist, integration-engineer, ml-engineer, mlops-engineer, mobile-engineer, observability-engineer, performance-engineer, platform-engineer, refactor, security-engineer, seo-specialist, site-reliability-engineer, tester, zos-sysprog | | Analysis/review only | Any tier | All agents | -Read-Only agents (architect, api-designer, code-reviewer, content-strategist, compliance-reviewer) +Read-Only agents (architect, api-designer, cloud-architect, code-reviewer, compliance-reviewer, content-strategist, solutions-architect) CANNOT be assigned to phases that create or modify files. If a phase requires file creation and domain expertise from a Read-Only agent, split it: the Read-Only agent produces a spec or analysis, then a write-capable agent (typically coder) implements the files based on that output. @@ -180,17 +180,26 @@ If `validate_plan` is available, review its `parallelization_profile` and `redun | Task Domain | Primary Agent | Secondary Agent | Rationale | |-------------|--------------|-----------------|-----------| | System design, architecture | `architect` | - | Read-only analysis, design expertise | +| Cloud architecture, multi-region topology | `cloud-architect` | `devops-engineer` | Architecture first, implementation second | +| Enterprise integration architecture | `solutions-architect` | `integration-engineer` | Cross-team design before implementation | | API contracts, endpoints | `api-designer` | `coder` | Design then implement | | Feature implementation | `coder` | - | Full implementation access | | Code quality review | `code-reviewer` | - | Read-only verification | | Database schema, queries | `data-engineer` | - | Schema + implementation | +| RDBMS tuning, indexes, migration safety | `database-administrator` | `data-engineer` | DBA analysis before schema/code changes | +| DB2 administration | `db2-dba` | `data-engineer` | DB2-specific operations and design | | Bug investigation | `debugger` | - | Read + shell for investigation | | CI/CD, infrastructure | `devops-engineer` | - | Full DevOps access | +| Internal platforms, paved paths | `platform-engineer` | `devops-engineer` | Platform conventions and implementation | +| B2B integrations, ETL, message brokers | `integration-engineer` | - | Full integration implementation | +| SLOs, runbooks, reliability | `site-reliability-engineer` | `observability-engineer` | Reliability assessment plus telemetry implementation | +| Observability, metrics, traces | `observability-engineer` | - | Full telemetry implementation | | Performance analysis | `performance-engineer` | - | Read + shell for profiling | | Code restructuring | `refactor` | - | Write + shell access (for validation) | | Security assessment | `security-engineer` | - | Read + shell for scanning | | Test creation | `tester` | - | Full test implementation | | Documentation | `technical-writer` | - | Write access for docs | +| Release notes, changelogs, rollout | `release-manager` | - | Write access for release artifacts | | Technical SEO audit | `seo-specialist` | - | Read + shell + web search | | Marketing copy, content | `copywriter` | - | Read/write | | Content planning | `content-strategist` | - | Read + web search/fetch | @@ -201,6 +210,14 @@ If `validate_plan` is available, review its `parallelization_profile` and `redun | Internationalization | `i18n-specialist` | `coder` | Implement then localize | | Design tokens, theming | `design-system-engineer` | `coder` | Tokens then consume | | Legal, regulatory | `compliance-reviewer` | - | Read + web search/fetch | +| Mobile platform work | `mobile-engineer` | `tester` | Mobile implementation plus validation | +| Model training, inference integration | `ml-engineer` | `tester` | ML implementation plus evaluation | +| Model registry, drift, model CI/CD | `mlops-engineer` | `devops-engineer` | Model operations and deployment | +| Prompt design, few-shot, RAG tuning | `prompt-engineer` | `coder` | Prompt spec before integration | +| Mainframe COBOL, JCL, CICS/IMS | `cobol-engineer` | `tester` | Mainframe implementation and validation | +| IBM HLASM for z/OS | `hlasm-assembler-specialist` | - | Assembly implementation | +| IBM i RPG/CL, DB2 for i | `ibm-i-specialist` | - | IBM i implementation | +| z/OS systems programming, JCL, RACF | `zos-sysprog` | `security-engineer` | System-level analysis and controls | ### Assignment Rules 1. Match the primary task domain to the agent specialization @@ -216,32 +233,19 @@ Estimate token consumption per phase based on: - Agent's max_turns limit as upper bound - Historical averages: ~500 input tokens per file read, ~200 output tokens per file written -### Cost Estimation +### Resource Estimation -#### Per-Phase Cost Factors -- **Model tier**: Pro agents (~$0.01/1K input, ~$0.04/1K output) vs Flash agents (~$0.001/1K input, ~$0.004/1K output) -- **Input complexity**: Number of files read, average file size, context from previous phases -- **Output complexity**: Lines of code generated, number of files created/modified -- **Retry budget**: Add 50% buffer per phase for potential retries (max 2 retries) +Do not invent provider pricing or model tiers. Agent model selection is runtime-owned through agent frontmatter and runtime configuration. Estimate execution size in stable, codebase-derived terms instead: -#### Estimation Formula -``` -Phase Cost = (input_tokens × input_rate + output_tokens × output_rate) × retry_multiplier -``` - -Where: -- `input_tokens` = files_to_read × 500 + context_tokens -- `output_tokens` = files_to_write × 200 + validation_output -- `retry_multiplier` = 1.5 (accounts for up to 2 retries) +- **Input complexity**: number of files likely to be read, average file size, and prior-phase context +- **Output complexity**: number of files created or modified, validation output volume, and expected handoff detail +- **Retry budget**: note phases likely to need retries because of broad file ownership, external dependencies, or uncertain validation -#### Plan-Level Cost Summary -Include this table in every implementation plan: +Include a lightweight plan-level resource summary when useful: -| Phase | Agent | Model | Est. Input | Est. Output | Est. Cost | -|-------|-------|-------|-----------|------------|----------| -| 1 | [agent] | [model] | [tokens] | [tokens] | [$X.XX] | -| ... | ... | ... | ... | ... | ... | -| **Total** | | | **[sum]** | **[sum]** | **[$X.XX]** | +| Phase | Agent | Est. Files Read | Est. Files Written | Retry Risk | Notes | +|-------|-------|-----------------|--------------------|------------|-------| +| 1 | [agent] | [N] | [N] | LOW/MEDIUM/HIGH | [why] | ## Plan Document Generation @@ -296,7 +300,7 @@ After writing the implementation plan: 1. Confirm the file path to the user 2. Present the dependency graph and execution strategy 3. Highlight parallel execution opportunities -4. Provide token budget estimates +4. Provide resource estimates when useful 5. If your runtime provides Plan Mode, call `exit_plan_mode` with the plan path to present the plan for user approval. If Plan Mode is not available, present the completed plan for user approval using the user-prompt tool from runtime context. 6. Ensure the approved plan is at `/plans/YYYY-MM-DD--impl-plan.md` as the permanent project reference (copy from the staging directory if Plan Mode was used) 7. Ask if the user is ready to proceed to execution (Phase 3) diff --git a/src/skills/shared/session-management/SKILL.md b/src/skills/shared/session-management/SKILL.md index 595e7720..fc9fcd6e 100644 --- a/src/skills/shared/session-management/SKILL.md +++ b/src/skills/shared/session-management/SKILL.md @@ -18,12 +18,12 @@ Detection: check whether MCP state tools appear in your available tools. If they ## Hook-Level Session State -Maestro hooks maintain a separate, transient state directory at `/tmp/maestro-hooks//` that is distinct from orchestration state in ``: +Maestro hooks maintain a separate, transient state directory under `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//` that is distinct from orchestration state in ``: | Concern | Orchestration State | Hook State | | --- | --- | --- | -| Location | `/state/` | `/tmp/maestro-hooks//` (Unix) or `/maestro-hooks//` (Windows) | -| Lifecycle | Created in Phase 2, archived in Phase 4 | Directory created by the session-start hook when an active session exists; active-agent file written by the pre-delegation hook and cleared by the post-delegation hook; stale directories pruned by both session-start and pre-delegation hooks | +| Location | `/state/` | `${MAESTRO_HOOKS_DIR:-/maestro-hooks-}//` | +| Lifecycle | Created at execution setup, archived in Phase 4 | Directory created by the session-start hook when an active session exists; active-agent file written by the pre-delegation hook and cleared by the post-delegation hook; stale directories pruned by both session-start and pre-delegation hooks | | Contents | Session metadata, phase tracking, token usage, file manifests | Active agent tracking file (`active-agent`) | | Persistence | Survives session restarts (supports `/maestro:resume`) | Ephemeral — lost on session end or system reboot | | Managed by | Orchestrator via session-management skill | The runtime's pre-delegation and post-delegation hooks | @@ -35,7 +35,7 @@ The orchestrator does not read or write hook-level state directly. It interacts ## Session Creation Protocol ### When to Create -For Standard workflow, create a new session when beginning Phase 2 (Team Assembly & Planning) of orchestration, after the design document has been approved. For Express workflow, create a session after the structured brief is approved (see Express Workflow section in the orchestrator template). +For Standard workflow, create a new session at execution setup after the design document and implementation plan are approved and the execution mode gate has resolved. For Express workflow, create a session after the structured brief is approved (see Express Workflow section in the orchestrator template). ### Session ID Format `YYYY-MM-DD-` diff --git a/tests/unit/doc-drift-guard.test.js b/tests/unit/doc-drift-guard.test.js index 8d05aa34..68de0cd5 100644 --- a/tests/unit/doc-drift-guard.test.js +++ b/tests/unit/doc-drift-guard.test.js @@ -7,6 +7,10 @@ const REPO = path.resolve(__dirname, '../..'); const read = (p) => fs.readFileSync(path.join(REPO, p), 'utf8'); const listDir = (d) => fs.readdirSync(path.join(REPO, d)); const countMd = (d) => listDir(d).filter((f) => f.endsWith('.md')).length; +const canonicalAgents = () => listDir('src/agents') + .filter((f) => f.endsWith('.md')) + .map((f) => f.replace(/\.md$/, '')); +const toSnake = (name) => name.replace(/-/g, '_'); test('doc-drift: agent-count claim phrase present in user-facing surfaces', () => { const canonicalCount = countMd('src/agents'); @@ -36,6 +40,34 @@ test('doc-drift: no stale inject-frontmatter transform in docs', () => { assert.ok(!body.includes('inject-frontmatter'), 'docs/architecture.md still references removed inject-frontmatter transform'); }); +test('doc-drift: root pointer docs include Qwen runtime docs', () => { + for (const surface of ['OVERVIEW.md', 'USAGE.md', 'ARCHITECTURE.md']) { + const body = read(surface); + assert.ok(body.includes('docs/runtime-qwen.md'), `${surface}: missing Qwen runtime documentation link`); + } +}); + +test('doc-drift: GitHub templates include Qwen runtime impact choices', () => { + const surfaces = [ + '.github/ISSUE_TEMPLATE/bug_report.md', + '.github/ISSUE_TEMPLATE/feature_request.md', + '.github/PULL_REQUEST_TEMPLATE.md', + ]; + for (const surface of surfaces) { + const body = read(surface); + assert.ok(body.includes('Qwen Code'), `${surface}: missing Qwen Code runtime option`); + } +}); + +test('doc-drift: Gemini and Qwen context rosters list every src agent', () => { + for (const surface of ['GEMINI.md', 'QWEN.md']) { + const body = read(surface); + for (const agent of canonicalAgents()) { + assert.ok(body.includes(`| \`${toSnake(agent)}\` |`), `${surface}: Agent Roster missing ${toSnake(agent)}`); + } + } +}); + test('doc-drift: no references to deleted plugins/maestro/mcp/ directory', () => { const surfaces = ['docs/architecture.md', 'docs/runtime-codex.md', 'docs/overview.md']; for (const surface of surfaces) { @@ -294,3 +326,13 @@ test('doc-drift: docs/runtime-qwen.md tool mapping has correct Qwen overrides', assert.ok(pattern.test(body), `docs/runtime-qwen.md: mapping row missing: ${canonical} → ${qwen}`); } }); + +test('doc-drift: Qwen docs use Qwen hook event names', () => { + for (const surface of ['docs/runtime-qwen.md', 'docs/maestro-cheatsheet.md', 'QWEN.md']) { + const body = read(surface); + assert.ok(body.includes('SubagentStart'), `${surface}: missing SubagentStart`); + assert.ok(body.includes('SubagentStop'), `${surface}: missing SubagentStop`); + assert.ok(!body.includes('| `BeforeAgent` | `hooks/hook-runner.js qwen'), `${surface}: still documents Qwen BeforeAgent`); + assert.ok(!body.includes('| `AfterAgent` | `hooks/hook-runner.js qwen'), `${surface}: still documents Qwen AfterAgent`); + } +}); diff --git a/tests/unit/platform-metadata.test.js b/tests/unit/platform-metadata.test.js index 89b17c10..8169323c 100644 --- a/tests/unit/platform-metadata.test.js +++ b/tests/unit/platform-metadata.test.js @@ -48,6 +48,14 @@ describe('platform metadata generation', () => { assert.deepEqual([...outputs.keys()].sort(), expectedPaths); assert.equal(outputs.get('gemini-extension.json').version, PACKAGE_FIXTURE.version); assert.equal(outputs.get('qwen-extension.json').version, PACKAGE_FIXTURE.version); + assert.equal( + outputs.get('gemini-extension.json').mcpServers.maestro.env.MAESTRO_RUNTIME, + 'gemini' + ); + assert.equal( + outputs.get('qwen-extension.json').mcpServers.maestro.env.MAESTRO_RUNTIME, + 'qwen' + ); assert.equal(outputs.get('claude/.claude-plugin/plugin.json').version, PACKAGE_FIXTURE.version); assert.equal(outputs.get('plugins/maestro/.codex-plugin/plugin.json').version, PACKAGE_FIXTURE.version); assert.equal(