@josstei/maestro 1.6.4-nightly.20260430

package/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/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/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/src/transforms/agent-stub.js

@@ -0,0 +1,29 @@
+const { extractValue, splitAtBoundary } = require('../lib/frontmatter');
+const { toKebabCase } = require('../lib/naming');
+
+function canonicalAgentName(name, runtime) {
+  if (!name) return name;
+  if (runtime.agentNaming === 'snake_case') {
+    return toKebabCase(name);
+  }
+  return name;
+}
+
+function replaceBodyWithStub(content, stubBody) {
+  const { raw } = splitAtBoundary(content);
+  if (raw) {
+    return '---\n' + raw + '\n---\n\n' + stubBody;
+  }
+  return stubBody;
+}
+
+function agentStub(content, runtime) {
+  const name = canonicalAgentName(extractValue(content, 'name') || '', runtime);
+  const stubBody =
+    `Agent methodology loaded via MCP tool \`get_agent\`. ` +
+    `Call \`get_agent(agents: ["${name}"])\` to read the full methodology at delegation time.\n`;
+
+  return replaceBodyWithStub(content, stubBody);
+}
+
+module.exports = agentStub;

package/src/transforms/extract-examples.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * Transform: extract-examples
+ *
+ * For Claude runtime, extracts <example>...</example> blocks from the body
+ * and stores them in the shared pipeline state. Other runtimes pass through
+ * unchanged.
+ *
+ * @param {string} content  - Full agent file (pass-through)
+ * @param {object} runtime  - Runtime config
+ * @param {object} options  - Pipeline options with shared state
+ * @returns {string} Content passed through unchanged
+ */
+function extractExamplesTransform(content, runtime, options) {
+  if (runtime.name !== 'claude') return content;
+
+  const { examples, remaining } = extractExamples(options.state.body);
+  options.state.body = remaining;
+  options.state.examples = examples;
+  return content;
+}
+
+/**
+ * Extract <example>...</example> blocks from body text.
+ * @param {string} body - Body text to extract examples from
+ * @returns {{ examples: string[], remaining: string }}
+ */
+function extractExamples(body) {
+  const examples = [];
+  const lines = body.split('\n');
+  const remainingLines = [];
+  let inExample = false;
+  let currentExample = [];
+
+  for (const line of lines) {
+    if (line.trim() === '<example>') {
+      inExample = true;
+      currentExample = ['<example>'];
+    } else if (line.trim() === '</example>') {
+      inExample = false;
+      currentExample.push('</example>');
+      examples.push(currentExample.join('\n'));
+      currentExample = [];
+    } else if (inExample) {
+      currentExample.push(line);
+    } else {
+      remainingLines.push(line);
+    }
+  }
+
+  if (inExample) {
+    throw new Error('Unclosed <example> tag in agent body');
+  }
+
+  let remaining = remainingLines.join('\n');
+  remaining = remaining.replace(/\n{3,}/g, '\n\n');
+  remaining = remaining.replace(/^\n{2,}/, '\n');
+
+  return { examples, remaining };
+}
+
+module.exports = extractExamplesTransform;

package/src/transforms/index.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const path = require('node:path');
+const { discover } = require('../lib/discovery');
+
+const TRANSFORMS_DIR = path.resolve(__dirname);
+
+const entries = discover({
+  dir: TRANSFORMS_DIR,
+  pattern: '*.js',
+  identity: (filepath) => path.basename(filepath, '.js'),
+  validate: (entry) => entry.id !== 'index',
+});
+
+const transforms = Object.create(null);
+for (const entry of entries) {
+  transforms[entry.id] = require(path.join(TRANSFORMS_DIR, `${entry.id}.js`));
+}
+
+/**
+ * Resolve a transform name to its function.
+ * Supports parameterized transforms like 'strip-feature:flagName'.
+ * @param {string} name
+ * @returns {{ fn: Function, param: string|null }}
+ */
+function resolve(name) {
+  const [baseName, param] = name.split(':');
+  const fn = transforms[baseName];
+  if (!fn) {
+    throw new Error(`Unknown transform: "${baseName}"`);
+  }
+  return { fn, param: param || null };
+}
+
+module.exports = { resolve, transforms };

package/src/transforms/parse-frontmatter.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const { parse } = require('../lib/frontmatter');
+
+/**
+ * Transform: parse-frontmatter
+ *
+ * Parses YAML frontmatter from agent content and stores the parsed
+ * frontmatter object and body string into the shared pipeline state.
+ *
+ * @param {string} content  - Full agent file with --- delimited frontmatter
+ * @param {object} _runtime - Runtime config (unused)
+ * @param {object} options  - Pipeline options with shared state
+ * @returns {string} Content passed through unchanged
+ */
+function parseFrontmatterTransform(content, _runtime, options) {
+  const { frontmatter, body } = parse(content);
+  options.state.frontmatter = frontmatter;
+  options.state.body = body;
+  return content;
+}
+
+module.exports = parseFrontmatterTransform;

package/src/transforms/rebuild-frontmatter.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const { toSnakeCase } = require('../lib/naming');
+const { escapeYaml } = require('../lib/frontmatter');
+const { emitBlockList } = require('../lib/yaml-emit');
+
+/**
+ * Per-field emitters. Each returns the YAML line(s) to append, or an
+ * empty array to skip the field entirely.
+ *
+ * Context shape:
+ *   - `name`         - canonical agent name (snake_case or kebab-case)
+ *   - `frontmatter`  - parsed input frontmatter
+ *   - `description`  - final description (may have examples appended for claude)
+ *   - `tools`        - flattened tool list (after per-runtime mapping)
+ *   - `runtime`      - full runtime config
+ *   - `fm`           - runtime.agentFrontmatter config (shape hints)
+ */
+const FIELDS = {
+  name: (ctx) =>
+    ctx.name != null && ctx.name !== '' ? [`name: ${ctx.name}`] : [],
+
+  kind: (ctx) => (ctx.fm.kind ? [`kind: ${ctx.fm.kind}`] : []),
+
+  description: (ctx) => {
+    if (ctx.runtime.name === 'claude' && ctx.description.includes('\n')) {
+      return [
+        'description: |',
+        ...ctx.description.split('\n').map((line) => `  ${line}`),
+      ];
+    }
+    return [`description: "${escapeYaml(ctx.frontmatter.description || '')}"`];
+  },
+
+  model: (ctx) => (ctx.fm.model ? [`model: ${ctx.fm.model}`] : []),
+
+  color: (ctx) =>
+    ctx.frontmatter.color ? [`color: ${ctx.frontmatter.color}`] : [],
+
+  tools: (ctx) => emitBlockList('tools', ctx.tools),
+
+  temperature: (ctx) =>
+    ctx.fm.hasTemperature && ctx.frontmatter.temperature != null
+      ? [`temperature: ${ctx.frontmatter.temperature}`]
+      : [],
+
+  turns: (ctx) =>
+    ctx.fm.turnsField && ctx.frontmatter.max_turns != null
+      ? [`${ctx.fm.turnsField}: ${ctx.frontmatter.max_turns}`]
+      : [],
+
+  timeout: (ctx) =>
+    ctx.fm.hasTimeout && ctx.frontmatter.timeout_mins != null
+      ? [`timeout_mins: ${ctx.frontmatter.timeout_mins}`]
+      : [],
+};
+
+const DEFAULT_FIELD_ORDER = [
+  'name',
+  'kind',
+  'description',
+  'model',
+  'turns',
+  'tools',
+];
+
+const RUNTIME_FIELD_ORDER = {
+  claude: ['name', 'kind', 'description', 'model', 'color', 'turns', 'tools'],
+  gemini: [
+    'name',
+    'kind',
+    'description',
+    'model',
+    'tools',
+    'temperature',
+    'turns',
+    'timeout',
+  ],
+};
+
+function resolveTools(frontmatter, runtime) {
+  const overrideKey = `tools.${runtime.name}`;
+  if (frontmatter[overrideKey]) {
+    return frontmatter[overrideKey];
+  }
+
+  return (frontmatter.tools || [])
+    .map((tool) => {
+      const mapped = runtime.tools && runtime.tools[tool];
+      if (Array.isArray(mapped)) return mapped;
+      return mapped || tool;
+    })
+    .flat();
+}
+
+function buildDescription(baseDescription, examples, runtime) {
+  if (runtime.name === 'claude' && examples.length > 0) {
+    return baseDescription + '\n\n' + examples.join('\n');
+  }
+  return baseDescription;
+}
+
+/**
+ * Transform: rebuild-frontmatter
+ *
+ * Reads parsed frontmatter, body, and optional examples from the shared
+ * pipeline state and produces the final output content with runtime-specific
+ * frontmatter formatting.
+ *
+ * @param {string} _content - Original content (unused; state drives output)
+ * @param {object} runtime  - Runtime config (name, agentNaming, agentFrontmatter, tools)
+ * @param {object} options  - Pipeline options with shared state
+ * @returns {string} Final content with rebuilt frontmatter
+ */
+function rebuildFrontmatterTransform(_content, runtime, options) {
+  const frontmatter = options.state.frontmatter || {};
+  const body = options.state.body != null ? options.state.body : '';
+  const examples = options.state.examples || [];
+  const fm = runtime.agentFrontmatter || {};
+
+  const name =
+    runtime.agentNaming === 'snake_case'
+      ? toSnakeCase(frontmatter.name)
+      : frontmatter.name;
+
+  const ctx = {
+    name,
+    frontmatter,
+    description: buildDescription(frontmatter.description || '', examples, runtime),
+    tools: resolveTools(frontmatter, runtime),
+    runtime,
+    fm,
+  };
+
+  const fieldOrder = RUNTIME_FIELD_ORDER[runtime.name] || DEFAULT_FIELD_ORDER;
+  const lines = ['---'];
+  for (const fieldName of fieldOrder) {
+    const emit = FIELDS[fieldName];
+    if (!emit) continue;
+    lines.push(...emit(ctx));
+  }
+  lines.push('---');
+
+  return lines.join('\n') + '\n' + body;
+}
+
+module.exports = rebuildFrontmatterTransform;

package/src/transforms/skill-discovery-stub.js

@@ -0,0 +1,27 @@
+const { parse } = require('../lib/frontmatter');
+
+function skillDiscoveryStub(content, runtime) {
+  const { frontmatter } = parse(content);
+  const name = frontmatter.name;
+  const description = frontmatter.description;
+  const lines = ['---'];
+
+  if (name) {
+    lines.push(`name: ${name}`);
+  }
+  if (description) {
+    lines.push(`description: ${description}`);
+  }
+  if (runtime.name === 'claude') {
+    lines.push('user-invocable: false');
+  }
+
+  lines.push('---');
+  lines.push('');
+  lines.push(`Methodology loaded via MCP. Call \`get_skill_content(resources: ["${name}"])\`.`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+module.exports = skillDiscoveryStub;

package/src/transforms/skill-metadata.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const { splitAtBoundary } = require('../lib/frontmatter');
+
+function skillMetadata(content, runtime) {
+  if (runtime.name !== 'claude') return content;
+
+  const { raw, body } = splitAtBoundary(content);
+  if (!raw) return content;
+
+  return '---\n' + raw + '\nuser-invocable: false\n---' + (body ? '\n' + body : '');
+}
+
+module.exports = skillMetadata;