@josstei/maestro 1.6.4-rc.1

package/plugins/maestro/src/skills/shared/validation/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: validation
+description: Cross-cutting validation methodology for verifying phase outputs and project integrity
+---
+
+# Validation Skill
+
+Activate this skill when validating phase outputs during orchestration execution or when running standalone validation checks. This skill provides the pipeline, heuristics, and interpretation rules for verifying that changes meet quality standards.
+
+## Validation Pipeline
+
+Execute validation steps in this order. Stop on the first blocking failure unless the user explicitly requests continuing.
+
+### Step 1: Build / Compile
+Verify the project compiles without errors.
+
+| Project Type | Command |
+|-------------|---------|
+| Node.js (TypeScript) | `npx tsc --noEmit` |
+| Node.js (JavaScript) | N/A (skip) |
+| Rust | `cargo build` |
+| Go | `go build ./...` |
+| Python | `python -m py_compile [files]` |
+| Java (Maven) | `mvn compile` |
+| Java (Gradle) | `./gradlew compileJava` |
+
+### Step 2: Lint / Format
+Verify code meets style and quality standards.
+
+| Project Type | Command |
+|-------------|---------|
+| Node.js | `npx eslint . && npx prettier --check .` |
+| Rust | `cargo clippy && cargo fmt --check` |
+| Go | `go vet ./... && gofmt -l .` |
+| Python | `ruff check . && ruff format --check .` |
+| Java | `mvn checkstyle:check` or `./gradlew checkstyleMain` |
+
+### Step 3: Unit Tests
+Run unit tests to verify behavior preservation.
+
+| Project Type | Command |
+|-------------|---------|
+| Node.js (Jest) | `npx jest` |
+| Node.js (Vitest) | `npx vitest run` |
+| Rust | `cargo test` |
+| Go | `go test ./...` |
+| Python (pytest) | `python -m pytest tests/` |
+| Java (Maven) | `mvn test` |
+| Java (Gradle) | `./gradlew test` |
+
+### Step 4: Integration Tests
+Run integration tests if available and applicable.
+
+Detect integration test presence by looking for:
+- `tests/integration/`, `test/integration/`, or `**/integration_test*` directories/files
+- Test files with `integration` in the name
+- Test scripts in package.json (e.g., `test:integration`)
+
+### Step 5: Manual Verification
+For changes that cannot be automatically validated, present a checklist to the user.
+
+## Project Type Detection
+
+Detect the project type by checking for the presence of these files in the project root:
+
+| Indicator File | Project Type |
+|---------------|-------------|
+| `package.json` | Node.js (check for `typescript` dep for TS) |
+| `Cargo.toml` | Rust |
+| `go.mod` | Go |
+| `pyproject.toml` or `setup.py` | Python |
+| `pom.xml` | Java (Maven) |
+| `build.gradle` or `build.gradle.kts` | Java (Gradle) |
+| `Gemfile` | Ruby |
+| `*.csproj` or `*.sln` | .NET |
+
+When multiple indicators are present, validate each project type independently.
+
+## Validation Result Interpretation
+
+### Pass
+All executed validation steps completed with exit code 0. No errors or warnings that indicate broken functionality.
+
+### Fail (Blocking)
+Any of the following constitute a blocking failure:
+- Build/compile errors
+- Lint errors (not warnings, unless the project treats warnings as errors)
+- Test failures
+- Type errors
+
+### Warn (Non-Blocking)
+The following are recorded but do not block progression:
+- Lint warnings (when not configured as errors)
+- Deprecation notices
+- Coverage decreases (unless coverage threshold is configured)
+- Format-only issues (can be auto-fixed)
+
+## Validation Modes
+
+The validation strictness is controlled by `MAESTRO_VALIDATION_STRICTNESS` (default: `normal`).
+
+| Mode | Behavior |
+|------|----------|
+| `strict` | Warnings are treated as blocking failures. All lint warnings, deprecation notices, and coverage decreases block phase progression. |
+| `normal` | Only errors block. Warnings are recorded but do not prevent phase completion. This is the default behavior described in the Pass/Fail/Warn sections above. |
+| `lenient` | Nothing blocks automatically. All failures and warnings are recorded in session state and reported to the user, but phase progression continues. The user reviews the accumulated report at completion. |
+
+### Strictness Application
+
+When evaluating each validation step:
+1. Run the validation command and capture the exit code and output
+2. Classify the result as Pass, Fail (Blocking), or Warn (Non-Blocking) using the standard criteria above
+3. Apply the strictness mode:
+   - `strict`: Fail (Blocking) AND Warn (Non-Blocking) both stop progression
+   - `normal`: Only Fail (Blocking) stops progression
+   - `lenient`: Record everything, stop nothing — append all results to session state and continue
+4. If strictness causes a result to be downgraded from blocking to non-blocking, note this in the validation output: "Warning recorded but not blocking (lenient mode)"
+
+## Post-Phase Validation
+
+### When to Validate
+Run validation after:
+- Every phase that creates or modifies source code
+- Every parallel batch completion (validate the combined result)
+- Before marking any phase as `completed`
+
+### When to Skip Validation
+Skip validation when:
+- The phase only modified documentation files
+- The phase only produced read-only analysis (`architect`, `code-reviewer` reports)
+- The user explicitly requests skipping validation
+
+Record `skipped` with rationale in the phase validation result.
+
+## Manual Verification Checklist
+
+For changes that cannot be automatically validated, present this checklist template:
+
+```
+### Manual Verification Required
+
+The following changes require manual verification:
+
+- [ ] [Description of what to verify]
+- [ ] [Visual/UI changes look correct]
+- [ ] [Integration with external service works]
+- [ ] [Environment-specific behavior confirmed]
+
+Please confirm these items are verified before I mark this phase as complete.
+```
+
+Use manual verification for:
+- UI/visual changes
+- External service integrations
+- Environment-specific configurations
+- Performance improvements (require load testing)
+- Security remediations (require penetration testing)
+
+## Incremental Validation Mode
+
+When full pipeline validation is unnecessary, use targeted validation based on the type of changes in the completed phase:
+
+### Validation Scope by Change Type
+- **Phase created new files only** (no existing files modified): Run lint + type check on the new files only. This provides fast feedback without running the full test suite against unchanged code.
+- **Phase modified existing files**: Run the full test suite. Existing tests serve as behavior-preservation checks — any failure indicates a potential regression.
+- **Phase touched configuration files** (build config, CI config, environment config, dependency manifests): Run the full pipeline (build + lint + type check + all tests). Configuration changes can have cascading effects across the entire project.
+- **Phase only produced documentation or analysis**: Skip validation (record as `skipped` with rationale).
+
+### Scope Detection
+Determine the change type automatically from the completing agent's Task Report:
+1. Parse Files Created and Files Modified lists
+2. Classify each file: source code, test code, configuration, documentation
+3. Apply the most comprehensive validation scope that matches any changed file type (e.g., if one config file and three source files changed, run the full pipeline because config was touched)
+
+## Validation Failure Diagnosis
+
+When validation fails, provide a structured diagnosis to help the orchestrator decide next steps.
+
+### Diagnosis Protocol
+1. **Categorize the failure**: type error, lint error, test failure, build error, runtime error
+2. **Identify involved files**: Which files from the current phase appear in the error output?
+3. **Determine causality**: Is the failure caused by the current phase's changes, or is it a pre-existing issue?
+   - Check: Does the failure reference files modified in this phase?
+   - Check: Run validation against a clean snapshot while always restoring local state:
+     - `git stash push --include-untracked -m "maestro-causality-check"`
+     - `[validation command]` (capture exit code as `validation_exit`)
+     - `git stash pop` (run regardless of `validation_exit`)
+   - If `validation_exit` is non-zero in the clean snapshot, classify the failure as pre-existing.
+   - If `git stash pop` fails, mark the diagnosis as inconclusive until restoration conflicts are resolved.
+4. **Classify resolution path**:
+   - **Fixable by same agent**: The error is in files the agent owns, the fix is straightforward (missing import, type mismatch, lint violation). Re-delegate to the same agent with the error context.
+   - **Requires different agent**: The error is caused by an interface mismatch between phases. Identify which phase introduced the incompatibility.
+   - **Requires human input**: The error reveals an ambiguity in the design or plan that cannot be resolved without user guidance. Escalate with full context.
+
+### Diagnosis Output Format
+```
+### Validation Diagnosis
+- **Failure Type**: [type error | lint error | test failure | build error]
+- **Failing Files**: [list of files from current phase involved in the failure]
+- **Root Cause**: [brief description of why validation failed]
+- **Pre-existing**: [yes | no — was this failure present before this phase's changes?]
+- **Resolution Path**: [re-delegate to same agent | escalate to user | requires cross-phase fix]
+- **Recommended Action**: [specific next step with context to include in re-delegation or escalation]
+```

package/plugins/maestro/src/state/session-state.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWriteSync } = require('../lib/io');
+
+const DEFAULT_STATE_DIR = 'docs/maestro';
+
+function validateRelativePath(filePath) {
+  if (path.isAbsolute(filePath)) {
+    throw new Error('Path must be relative');
+  }
+  const segments = filePath.split(/[/\\]/);
+  if (segments.includes('..')) {
+    throw new Error('Path traversal not allowed');
+  }
+}
+
+function validateContainment(absolutePath, rootDir) {
+  let resolved = path.resolve(absolutePath);
+  let resolvedRoot = path.resolve(rootDir);
+  try { resolved = fs.realpathSync(resolved); } catch {}
+  try { resolvedRoot = fs.realpathSync(resolvedRoot); } catch {}
+  const rootPrefix = resolvedRoot + path.sep;
+  if (!resolved.startsWith(rootPrefix) && resolved !== resolvedRoot) {
+    throw new Error('state_dir must be within the project root');
+  }
+  return resolved;
+}
+
+function resolveStateDirPath(cwd, stateDirOverride) {
+  const stateDir = stateDirOverride || process.env.MAESTRO_STATE_DIR || DEFAULT_STATE_DIR;
+  const base = cwd || process.cwd();
+
+  if (path.isAbsolute(stateDir)) {
+    return validateContainment(stateDir, base);
+  }
+
+  validateRelativePath(stateDir);
+  return path.join(base, stateDir);
+}
+
+function resolveActiveSessionPath(cwd) {
+  return path.join(resolveStateDirPath(cwd), 'state', 'active-session.md');
+}
+
+function hasActiveSession(cwd) {
+  try {
+    const sessionPath = resolveActiveSessionPath(cwd);
+    return fs.existsSync(sessionPath);
+  } catch {
+    return false;
+  }
+}
+
+function readState(relativePath, basePath) {
+  validateRelativePath(relativePath);
+  const fullPath = path.join(basePath, relativePath);
+  return fs.readFileSync(fullPath, 'utf8');
+}
+
+function writeState(relativePath, content, basePath) {
+  validateRelativePath(relativePath);
+  const fullPath = path.join(basePath, relativePath);
+  atomicWriteSync(fullPath, content);
+}
+
+function ensureWorkspace(stateDir, basePath) {
+  const fullBase = path.isAbsolute(stateDir)
+    ? validateContainment(stateDir, basePath)
+    : (() => {
+        validateRelativePath(stateDir);
+        return path.join(basePath, stateDir);
+      })();
+  fs.mkdirSync(fullBase, { recursive: true, mode: 0o700 });
+  const stats = fs.lstatSync(fullBase);
+  if (stats.isSymbolicLink()) {
+    throw new Error('STATE_DIR must not be a symlink');
+  }
+  const dirs = [
+    path.join(fullBase, 'state'),
+    path.join(fullBase, 'state', 'archive'),
+    path.join(fullBase, 'plans'),
+    path.join(fullBase, 'plans', 'archive'),
+  ];
+  for (const dir of dirs) {
+    try {
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    } catch {
+      throw new Error('Failed to create workspace directory');
+    }
+    try {
+      fs.accessSync(dir, fs.constants.W_OK);
+    } catch {
+      throw new Error('Workspace directory not writable');
+    }
+  }
+  const stateGitignore = path.join(fullBase, 'state', '.gitignore');
+  try {
+    fs.writeFileSync(stateGitignore, 'active-session.md\narchive/\n', { mode: 0o600, flag: 'wx' });
+  } catch {}
+}
+
+module.exports = {
+  DEFAULT_STATE_DIR,
+  validateContainment,
+  resolveStateDirPath,
+  resolveActiveSessionPath,
+  hasActiveSession,
+  readState,
+  writeState,
+  ensureWorkspace,
+};

package/plugins/maestro/src/templates/design-document.md

@@ -0,0 +1,95 @@
+---
+title: "<topic>"
+created: "<ISO 8601 timestamp>"
+status: "draft"
+authors: ["TechLead", "User"]
+type: "design"
+design_depth: "standard" # one of: quick, standard, deep
+task_complexity: "medium" # one of: simple, medium, complex
+---
+
+# <Topic> Design Document
+
+## Problem Statement
+
+[Clear description of the problem being solved, including context and motivation]
+
+## Requirements
+
+### Functional Requirements
+
+1. **REQ-1**: [Requirement with measurable acceptance criteria]
+
+### Non-Functional Requirements
+
+1. **REQ-N**: [Performance, security, scalability, reliability requirements]
+
+### Constraints
+
+- [Technical, organizational, or business constraints]
+
+## Approach
+
+### Selected Approach
+
+**[Approach Name]**
+
+[Description of the selected approach and why it was chosen]
+
+### Alternatives Considered
+
+#### [Alternative 1 Name]
+
+- **Description**: [Brief overview]
+- **Pros**: [Key advantages]
+- **Cons**: [Key disadvantages]
+- **Rejected Because**: [Specific reason this was not selected]
+
+### Decision Matrix
+
+*(Standard and Deep modes only — omit in Quick mode)*
+
+| Criterion | Weight | [Approach A] | [Approach B] |
+|-----------|--------|--------------|--------------|
+| [Criterion from requirements] | [%] | [1-5]: [justification] | [1-5]: [justification] |
+| **Weighted Total** | | [score] | [score] |
+
+## Architecture
+
+<!-- Standard+Deep: Include rationale annotations on key decisions.
+     Format: [decision] — *[rationale referencing constraints or user-stated preferences]*
+     Deep only: Include per-decision alternatives considered.
+     Format: [decision] *(considered: [alt A] — rejected because [reason]; [alt B] — rejected because [reason])*
+     Deep only: Tag decisions with Traces To: REQ-N -->
+
+### Component Diagram
+
+```
+[ASCII or text-based component diagram showing key components and their relationships]
+```
+
+### Data Flow
+
+[Description of how data flows through the system, including inputs, transformations, and outputs]
+
+### Key Interfaces
+
+```
+[Interface definitions with type signatures for the primary contracts between components]
+```
+
+## Agent Team
+
+| Phase | Agent(s) | Parallel | Deliverables |
+|-------|----------|----------|--------------|
+| 1     | [agent]  | No       | [deliverable] |
+
+## Risk Assessment
+
+| Risk | Severity | Likelihood | Mitigation |
+|------|----------|------------|------------|
+| [risk] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | [mitigation strategy] |
+
+## Success Criteria
+
+1. [Measurable criterion that indicates successful completion]

package/plugins/maestro/src/templates/implementation-plan.md

@@ -0,0 +1,86 @@
+---
+title: "<topic> Implementation Plan"
+design_ref: "<path to design document>"
+created: "<ISO 8601 timestamp>"
+status: "draft"
+total_phases: <integer>
+estimated_files: <integer>
+task_complexity: "medium" # one of: simple, medium, complex
+---
+
+# <Topic> Implementation Plan
+
+## Plan Overview
+
+- **Total phases**: [N]
+- **Agents involved**: [list of agent names]
+- **Estimated effort**: [summary of scope and complexity]
+
+## Dependency Graph
+
+```
+[ASCII diagram showing phase dependencies and parallel opportunities]
+```
+
+## Execution Strategy
+
+| Stage | Phases | Execution | Agent Count | Notes |
+|-------|--------|-----------|-------------|-------|
+| 1     | Phase 1 | Sequential | 1 | Foundation |
+
+## Phase 1: <Phase Name>
+
+### Objective
+[Clear, measurable statement of what this phase delivers]
+
+### Agent: <agent-name>
+### Parallel: <Yes/No>
+
+### Files to Create
+
+- `path/to/file` — [Purpose, key interfaces/classes to define]
+
+### Files to Modify
+
+- `path/to/existing/file` — [What changes and why]
+
+### Implementation Details
+
+[Interface definitions, base class contracts, dependency injection patterns, error handling strategy]
+
+### Validation
+
+- [Commands to run and expected outcomes]
+
+### Dependencies
+
+- Blocked by: [Phase IDs or "None"]
+- Blocks: [Phase IDs or "None"]
+
+---
+
+## File Inventory
+
+| # | File | Phase | Purpose |
+|---|------|-------|---------|
+| 1 | `path/to/file` | 1 | [Purpose] |
+
+## Risk Classification
+
+| Phase | Risk | Rationale |
+|-------|------|-----------|
+| 1     | LOW/MEDIUM/HIGH | [Why this risk level — complexity, number of dependents, reversibility] |
+
+## Execution Profile
+
+```
+Execution Profile:
+- Total phases: [N]
+- Parallelizable phases: [M] (in [B] batches)
+- Sequential-only phases: [S]
+- Estimated parallel wall time: [time estimate based on batch execution]
+- Estimated sequential wall time: [time estimate based on serial execution]
+
+Note: Native subagents currently run without user approval gates.
+All tool calls are auto-approved without user confirmation.
+```

package/plugins/maestro/src/templates/session-state.md

@@ -0,0 +1,68 @@
+---
+session_id: "<YYYY-MM-DD-topic-slug>"
+task: "<user's original task description>"
+created: "<ISO 8601 timestamp>"
+updated: "<ISO 8601 timestamp>"
+status: "in_progress"
+workflow_mode: "standard"
+design_document: "<state_dir>/plans/<YYYY-MM-DD-topic-slug>-design.md"
+implementation_plan: "<state_dir>/plans/<YYYY-MM-DD-topic-slug>-impl-plan.md"
+current_phase: 1
+total_phases: <integer>
+execution_mode: null
+execution_backend: null
+current_batch: null
+task_complexity: null
+
+token_usage:
+  total_input: 0
+  total_output: 0
+  total_cached: 0
+  by_agent: {}
+
+phases:
+  - id: 1
+    name: "<phase name>"
+    status: "pending"
+    agents: []
+    parallel: false
+    started: null
+    completed: null
+    blocked_by: []
+    files_created: []
+    files_modified: []
+    files_deleted: []
+    downstream_context:
+      key_interfaces_introduced: []
+      patterns_established: []
+      integration_points: []
+      assumptions: []
+      warnings: []
+    errors: []
+    retry_count: 0
+---
+
+# <Topic> Orchestration Log
+
+## Phase 1: <Phase Name>
+
+### Status
+Pending
+
+### Agent Output
+[Agent output will be recorded here as execution proceeds]
+
+### Files Changed
+- Created: [none yet]
+- Modified: [none yet]
+- Deleted: [none yet]
+
+### Downstream Context
+- Key Interfaces Introduced: [none yet]
+- Patterns Established: [none yet]
+- Integration Points: [none yet]
+- Assumptions: [none yet]
+- Warnings: [none yet]
+
+### Validation Result
+[Pending]

package/plugins/maestro/src/version.json

@@ -0,0 +1,3 @@
+{
+  "version": "1.6.4-rc.1"
+}

package/policies/maestro.toml

@@ -0,0 +1,44 @@
+# Maestro extension policy pack.
+#
+# These rules add low-friction guardrails for autonomous and interactive runs:
+# - deny obviously destructive shell commands
+# - ask before shell-based file writing patterns
+#
+# The extension tier may only contribute deny / ask_user decisions.
+
+[[rule]]
+toolName = "run_shell_command"
+commandRegex = ".*\\btee\\b.*"
+decision = "ask_user"
+priority = 850
+
+[[rule]]
+toolName = "run_shell_command"
+commandRegex = ".*(?:\\s>>?\\s|\\s>>?$|^>>?\\s|\\d>>?\\s).*$"
+decision = "ask_user"
+priority = 850
+
+[[rule]]
+toolName = "run_shell_command"
+commandPrefix = [
+  "rm -rf",
+  "rm -fr",
+  "sudo rm -rf",
+  "sudo rm -fr",
+  "git reset --hard",
+  "git checkout --",
+  "git clean -fd",
+  "git clean -df",
+  "git clean -xfd",
+  "git clean -xdf"
+]
+decision = "deny"
+priority = 950
+deny_message = "Maestro blocks destructive shell commands. Use safer targeted tools or handle the cleanup manually."
+
+[[rule]]
+toolName = "run_shell_command"
+commandRegex = ".*(?:<<).*$"
+decision = "deny"
+priority = 950
+deny_message = "Heredoc corrupts structured content (YAML, Markdown, JSON) — use write_file instead"

package/qwen/agents/accessibility_specialist.md

@@ -0,0 +1,18 @@
+---
+name: accessibility_specialist
+kind: local
+description: "Accessibility specialist for WCAG compliance auditing, ARIA implementation review, keyboard navigation testing, and inclusive design assessment. Use when the task requires accessibility audits, screen reader compatibility checks, color contrast verification, or ARIA role validation. For example: auditing a web app for WCAG 2.1 AA compliance, reviewing keyboard navigation in modal dialogs, or validating ARIA usage in custom components."
+max_turns: 20
+tools:
+  - read_file
+  - list_directory
+  - glob
+  - grep_search
+  - run_shell_command
+  - web_search
+  - todo_write
+  - read_many_files
+  - ask_user_question
+---
+
+Agent methodology loaded via MCP tool `get_agent`. Call `get_agent(agents: ["accessibility-specialist"])` to read the full methodology at delegation time.

package/qwen/agents/analytics_engineer.md

@@ -0,0 +1,20 @@
+---
+name: analytics_engineer
+kind: local
+description: "Analytics engineering specialist for event tracking implementation, analytics schemas, conversion funnels, A/B test design, and measurement planning. Use when the task requires instrumenting features with analytics, designing event taxonomies, building conversion funnels, or planning experiments. For example: adding event tracking to a checkout flow, designing an A/B test for a pricing page, or defining KPI dashboards."
+max_turns: 25
+tools:
+  - read_file
+  - list_directory
+  - glob
+  - grep_search
+  - write_file
+  - edit
+  - run_shell_command
+  - web_search
+  - todo_write
+  - read_many_files
+  - ask_user_question
+---
+
+Agent methodology loaded via MCP tool `get_agent`. Call `get_agent(agents: ["analytics-engineer"])` to read the full methodology at delegation time.

package/qwen/agents/api_designer.md

@@ -0,0 +1,17 @@
+---
+name: api_designer
+kind: local
+description: "API design specialist for endpoint design, request/response contracts, and API versioning strategies. Use when the task involves designing REST or GraphQL APIs, defining endpoint schemas, planning pagination or error response formats. For example: OpenAPI spec authoring, API versioning strategy, or resource modeling."
+max_turns: 15
+tools:
+  - read_file
+  - list_directory
+  - glob
+  - grep_search
+  - read_many_files
+  - ask_user_question
+  - web_search
+  - web_fetch
+---
+
+Agent methodology loaded via MCP tool `get_agent`. Call `get_agent(agents: ["api-designer"])` to read the full methodology at delegation time.

package/qwen/agents/architect.md

@@ -0,0 +1,17 @@
+---
+name: architect
+kind: local
+description: "System design specialist for architecture decisions, technology selection, and high-level component design. Use when the task requires evaluating architectural trade-offs, designing system components, selecting technology stacks, or planning service boundaries. For example: microservice decomposition, database schema design, or API contract planning."
+max_turns: 15
+tools:
+  - read_file
+  - list_directory
+  - glob
+  - grep_search
+  - web_search
+  - read_many_files
+  - ask_user_question
+  - web_fetch
+---
+
+Agent methodology loaded via MCP tool `get_agent`. Call `get_agent(agents: ["architect"])` to read the full methodology at delegation time.