maestro-flow 0.4.12 → 0.4.14

package/workflows/issue-analyze.md

@@ -3,109 +3,23 @@
 > **DEPRECATED**: Superseded by `issue-gaps-analyze.md` which adds batch support and context.md output.
 > Use `maestro-analyze --gaps [ISS-ID]` instead.
 
-Root cause analysis for a specific issue using CLI exploration and codebase context gathering.
+This workflow's executable steps have been removed to prevent divergent implementations.
 
-## Input
+## Migration
 
-- `$ARGUMENTS`: `<ISS-ID> [--tool gemini|qwen] [--depth standard|deep]`
-- Operates on `.workflow/issues/`
+| Old usage | New usage |
+|-----------|-----------|
+| `manage-issue-analyze ISS-ID` | `/maestro-analyze --gaps ISS-ID` |
+| `manage-issue-analyze` (batch) | `/maestro-analyze --gaps` |
+| `manage-issue-plan ISS-ID` (follow-up) | `/maestro-plan --gaps ISS-ID` |
 
----
+## See Also
 
-### Step 1: Parse Arguments
+- `issue-gaps-analyze.md` — current implementation (single + batch, classification, parallel exploration, context.md)
+- `issue-gaps-analyze.codex.md` — codex variant using `spawn_agents_on_csv` waves
+- `issue-execute.md` — downstream execution after planning
 
-```
-Extract ISS-ID (required, pattern ISS-\d{8}-\d{3}).
-Flags: --tool gemini|qwen (default: gemini), --depth standard|deep (default: standard)
-```
+## Notes
 
----
-
-### Step 2: Load Issue and Validate
-
-```
-Load ISS-ID from .workflow/issues/issues.jsonl → fatal if file missing or ID not found.
-Status check: open/registered → proceed; other → warn but continue (non-destructive).
-```
-
----
-
-### Step 3: Gather Codebase Context
-
-```
-Extract keywords from issue title, description, location, affected_components.
-
-Standard depth: grep keywords in source files → top 20 paths, read 10 lines around
-  top 5 matches.
-Deep depth: standard grep + semantic Agent search (error handling, data flow, deps),
-  merge results.
-
-Build CODEBASE_CONTEXT: related files, key snippets (max 50 lines), dependency chain.
-```
-
----
-
-### Step 4: Run CLI Analysis
-
-```
-Delegate root cause analysis with issue details + CODEBASE_CONTEXT:
-
-  maestro delegate "Root cause analysis for {ISS-ID}: {ISSUE.title}
-  ISSUE: title, description, severity, location, fix_direction
-  CODEBASE CONTEXT: {CODEBASE_CONTEXT}
-  TASK: Identify root cause (file:line) → assess impact → list related files → rate confidence → suggest fix
-  EXPECTED: JSON { root_cause, impact, related_files[], confidence, suggested_approach }
-  CONSTRAINTS: Evidence-only, no speculation
-  " --to {TOOL} --mode analysis
-
-Validate response: all required fields present.
-Parse failure → save raw output to issue feedback for review.
-```
-
----
-
-### Step 5: Build Analysis Record
-
-```
-Construct IssueAnalysis:
-  { root_cause, impact, related_files, confidence, suggested_approach, analyzed_at: NOW_ISO, analyzed_by: TOOL }
-```
-
----
-
-### Step 6: Update Issue in JSONL
-
-```
-Read-modify-write issues.jsonl:
-  Set issue.analysis = ANALYSIS, updated_at = NOW_ISO
-  Append issue_history: actor "analysis-agent", note "confidence: {confidence}"
-  Status unchanged (analysis is metadata enrichment).
-Verify: re-read file, confirm analysis field present.
-```
-
----
-
-### Step 7: Display Summary and Next Steps
-
-```
-Display: root cause, impact, confidence, related files, suggested approach.
-
-Next steps:
-  - manage-issue-plan {ISS-ID} (generate solution | --tool {TOOL})
-  - manage-issue status {ISS-ID}
-```
-
----
-
-## Output
-
-- **Updated**: `.workflow/issues/issues.jsonl` -- issue record enriched with `analysis` field
-- **Analysis fields**: root_cause, impact, related_files, confidence, suggested_approach, analyzed_at, analyzed_by
-
-## Quality Criteria
-
-- Analysis grounded in actual codebase evidence (file:line references)
-- JSON result validated before writing to JSONL
-- Issue status unchanged (analysis is non-destructive enrichment)
-- Read-modify-write pattern preserves other issues in JSONL
-- Next-step routing guides user to solution planning
+- Issue records analyzed by the new pipeline still write to `.workflow/issues/issues.jsonl` with `analysis` field (root_cause, impact, related_files, confidence, suggested_approach, analyzed_at, analyzed_by).
+- Status is unchanged by analysis (non-destructive enrichment).

package/workflows/issue-discover.md

@@ -148,7 +148,7 @@ Display summary: session ID, mode, raw/unique counts, per-perspective breakdown,
 Next steps:
   - manage-issue list --severity critical
   - manage-issue list
-  - manage-issue-discover by-prompt "..."
+  - see also: /manage-issue-discover usage docs (by-prompt mode for focused scans)
 ```
 
 ---
@@ -211,8 +211,7 @@ Display summary: session, prompt, rounds, raw/unique counts, per-dimension + sev
 
 Next steps:
   - manage-issue list --source discovery
-  - manage-issue-discover (full 8-perspective scan)
-  - manage-issue-discover by-prompt "..." (explore another area)
+  - see also: /manage-issue-discover usage docs (full 8-perspective scan and by-prompt mode)
 ```
 
 ---

package/workflows/issue-execute.md

@@ -25,7 +25,7 @@ Flags: --executor claude-code|codex|gemini (default: claude-code), --dry-run (de
 
 ```
 Load ISS-ID from .workflow/issues/issues.jsonl → fatal if file missing or ID not found.
-Require issue.solution with non-empty steps[] → error if missing (run manage-issue-plan first).
+Require issue.solution with non-empty steps[] → error if missing (run `maestro-plan --gaps {ISS-ID}` first).
 Resolve EXECUTOR → CLI tool (claude-code→claude, codex→codex, gemini→gemini), all with --mode write.
 ```
 

package/workflows/issue-gaps-analyze.md

@@ -1,5 +1,7 @@
 # Workflow: Issue Gaps Analysis
 
+> **CLI variants**: see `issue-gaps-analyze.codex.md` for codex-specific notes (CSV-wave variant using `spawn_agents_on_csv`).
+
 Root cause analysis for issues using CLI exploration and codebase context gathering.
 Supports single issue (ISS-ID) or batch (all open/registered) with classification and parallel analysis.
 Produces analysis records in issues.jsonl and context.md for downstream `plan --gaps`.

package/workflows/learn.md

@@ -8,7 +8,7 @@ Storage:
 
 **Shared store rationale:** Manual captures (`source: "manual"`), tips (`source: "tip"`), retrospective-distilled insights (`source: "retrospective"`, `lens: <name>` from `quality-retrospective`), and learn-retro insights (`source: "retro-git"` or `source: "retro-decision"` from `learn-retro`) all live in the same store so search and list see the entire knowledge corpus. The `source` field disambiguates origin.
 
-This workflow does NOT spawn agents or call CLI tools. It is a thin file operation: parse → infer → append → confirm.
+This workflow does NOT spawn sub-agents; it may invoke maestro CLI utilities (e.g. `maestro wiki search`, `maestro wiki list`) for list/search subcommands. The core capture flow is a thin file operation: parse → infer → append → confirm.
 
 ---
 

package/workflows/maestro-chain-execute.md

@@ -4,235 +4,17 @@
 > Both maestro and ralph sessions now use `maestro-ralph-execute` for step execution.
 > This file is kept for reference only and will be removed in a future version.
 
-Original description: Upgraded version of maestro's original direct execution strategy.
-Reads session status.json, loops through steps with per-step engine selection,
-context propagation, post-step Gemini analysis, and error handling.
-Dual-track progress: status.json (persistence + resume) and TodoWrite (UI visibility).
+## Migration
 
-**Prerequisites:**
-- Session directory with valid status.json (status: "running", pending steps)
-- TodoWrite initialized by selection workflow (Step 3h) with `MAESTRO:{chain_name}:` prefix
-- $SESSION_PATH passed from maestro.md dispatch
+- Caller dispatching from `maestro.md` → use `Skill({ skill: "maestro-ralph-execute" })`
+- Resume from session → `Skill({ skill: "maestro-ralph-execute" })` (auto-discovers latest running session via `.workflow/.maestro/*/status.json`)
 
-## Step 1: Load Session
+## References
 
-Read status.json from `$SESSION_PATH`.
+- `~/.maestro/workflows/maestro.md` — coordinator that creates sessions and dispatches to the unified executor
+- `~/.maestro/workflows/maestro-ralph-execute.md` — current canonical executor (handles both maestro static chains and ralph adaptive chains)
 
-Extract: `session_id`, `chain_name`, `steps[]`, `context`, `auto_mode`, `exec_mode`, `cli_tool`, `gemini_session_id`.
-
-Set `$STEP_INDEX` = `current_step` (first pending step).
-
-Validate: `status == "running"` and at least one pending step exists.
-
-**TodoWrite sync (resume mode):** If TodoWrite has no `MAESTRO:{chain_name}:` entries (e.g., fresh context after `/maestro -c`), rebuild from status.json:
-
-```javascript
-const todos = steps.map((step, i) => ({
-  content: `MAESTRO:${chain_name}: [${i + 1}/${steps.length}] ${step.skill}`,
-  status: step.status === 'completed' ? 'completed'
-        : i === $STEP_INDEX ? 'in_progress'
-        : 'pending'
-}));
-TodoWrite({ todos });
-```
-
-Display banner:
-
-```
-============================================================
-  CHAIN EXECUTOR
-============================================================
-  Session: {session_id}
-  Chain:   {chain_name}
-  Steps:   {completed}/{total} done, starting from step {$STEP_INDEX}
-  Auto:    {auto_mode}
-  Exec:    {exec_mode}
-```
-
-## Step 2: Context & Argument Assembly
-
-Initialize context object from `status.json.context`:
-
-```
-context = {
-  current_phase,    // from status.json.context or top-level phase
-  user_intent,      // from status.json.context or top-level intent
-  issue_id,
-  milestone_num,
-  spec_session_id,
-  scratch_dir
-}
-```
-
-### assembleArgs(step)
-
-```
-1. Substitute placeholders in step.args:
-   {phase} → context.current_phase
-   {description} → context.user_intent (chainMap uses {description} as alias for user intent)
-   {issue_id} → context.issue_id
-   {spec_session_id} → context.spec_session_id
-   {scratch_dir} → context.scratch_dir
-   {milestone_num} → context.milestone_num
-
-2. In auto_mode, append per-command flag if not already present:
-   maestro-analyze / maestro-brainstorm / maestro-roadmap / maestro-impeccable → -y
-   maestro-plan → --auto
-   quality-test → --auto-fix
-   quality-retrospective → --auto-yes
-
-3. Shell-escape strings with single quotes for CLI delegate calls.
-```
-
-## Step 3: Step Loop
-
-For each step starting at `$STEP_INDEX`:
-
-### 3a. Select engine & display banner
-
-Read `step.engine` from status.json (pre-computed by selection workflow Step 3e).
-
-If `step.engine` is missing or null, fallback to auto selection:
-```
-  CLI: maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm,
-       maestro-roadmap, maestro-impeccable, quality-refactor
-  Internal: everything else (current-session Skill() call)
-```
-
-Display: `[Step {N}/{total}] /{step.skill} [{engine}] — {args}`
-
-Update status.json: step `status = "running"`, `engine`, `started_at`.
-
-Context window hint:
-- Step >= 4 and not autoYes: hint user about `/maestro -c` for fresh context resume.
-- autoYes and step >= 5: log warning to status.json.
-
-### 3b. Execute (engine-dependent)
-
-**Internal engine** — current-session Skill() call (synchronous, visible):
-
-```
-Skill({ skill: step.skill, args: assembledArgs })
-```
-
-**CLI engine** — template-driven, async, context-isolated:
-
-```
-1. Load template ~/.maestro/templates/cli/prompts/coordinate-step.txt
-2. Build analysisHints from previous step's next_step_hints
-   (prompt_additions, cautions, context_to_carry)
-3. Substitute template placeholders:
-   {{COMMAND}}, {{ARGS}}, {{STEP_N}}, {{AUTO_DIRECTIVE}},
-   {{CHAIN_NAME}}, {{ANALYSIS_HINTS}}
-4. Run:
-   Bash(maestro delegate "<prompt>" --to {cli_tool} --mode write,
-        run_in_background: true, timeout: 600000)
-5. **STOP** — wait for background callback
-```
-
-### 3c. Parse output & update context
-
-Scan step output for context propagation:
-
-```
-PHASE: N         → context.current_phase
-SPEC-xxx         → context.spec_session_id
-scratch_dir: path → context.scratch_dir
-```
-
-CLI: capture `exec_id` from stderr `[MAESTRO_EXEC_ID=<id>]`.
-
-**Persist context back to status.json** after each step — write updated `context` field and `current_step`. This enables resume via `/maestro -c`.
-
-### 3d. Handle result & sync dual tracking
-
-**Success:**
-1. status.json: mark step `status = "completed"`, set `completed_at`
-2. TodoWrite: mark current step `completed`, next step `in_progress`
-3. CLI: save output to `step-{N}-output.txt` in session directory
-
-```javascript
-// Dual-track update after each step
-function updateDualTracking(stepIndex, total, chain_name, result) {
-  // 1. status.json — already updated in 3c
-  // 2. TodoWrite — sync UI
-  const todos = getAllTodos().map(todo => {
-    if (!todo.content.startsWith(`MAESTRO:${chain_name}:`)) return todo;
-    const num = extractStepNum(todo.content);
-    if (num === stepIndex + 1) return { ...todo, status: result };
-    if (num === stepIndex + 2 && result === 'completed') return { ...todo, status: 'in_progress' };
-    return todo;
-  });
-  TodoWrite({ todos });
-}
-```
-
-**Failure:**
-1. status.json: mark step `"failed"` or `"skipped"`
-2. TodoWrite: mark step `completed` (skipped) or keep `in_progress` (retry)
-3. `auto_mode` → retry once, then skip
-4. Interactive → offer: Retry (max 2) / Skip / Abort
-5. Abort → status.json `status = "aborted"`, TodoWrite mark remaining `pending`, display resume hint: `/maestro -c`
-
-### 3e. Post-step analysis (CLI steps only)
-
-Skip if: step failed/skipped, or `engine == 'internal'`.
-
-Delegate to gemini (analysis mode, `--resume` if `gemini_session_id` exists) with prompt containing:
-- Step command, args, chain name, intent
-- Last 200 lines of step output
-- Next step info (command, args) if any
-
-Expected JSON response:
-
-```json
-{
-  "quality_score": "<0-100>",
-  "execution_assessment": {
-    "success": "<bool>",
-    "completeness": "<full|partial|minimal>",
-    "key_outputs": [],
-    "missing_outputs": []
-  },
-  "issues": [
-    { "severity": "critical|high|medium|low", "description": "" }
-  ],
-  "next_step_hints": {
-    "prompt_additions": "<extra context for next step>",
-    "cautions": ["<things to watch out for>"],
-    "context_to_carry": "<key facts from this step>"
-  },
-  "step_summary": ""
-}
-```
-
-On callback:
-1. Capture gemini `exec_id` → store as `gemini_session_id` in status.json for session continuity.
-2. Store analysis in `step_analyses[]` and `step-{N}-analysis.json` in session directory.
-3. Advance to next step (**3a**).
-
-## Step 4: Completion Report
-
-Finalize dual tracking:
-1. status.json: `status = "completed"`
-2. TodoWrite: all steps marked `completed` (or `completed` for skipped)
-
-```
-============================================================
-  MAESTRO SESSION COMPLETE
-============================================================
-  Session:  {session_id}
-  Chain:    {chain_name}
-  Steps:    {completed}/{total} completed
-  Phase:    {context.current_phase}
-
-  Results:
-    [✓] 1. maestro-plan — completed [cli] (quality: 85/100)
-    [✓] 2. maestro-verify — completed [internal]
-    [—] 3. quality-review — skipped [internal]
-
-  CLI Avg Quality: {avgScore}/100 (based on {cliStepCount} cli steps)
-
-  Next: /maestro continue | /manage-status
-============================================================
-```
+The unified executor preserves all behaviour previously documented here:
+status.json persistence, TodoWrite dual-tracking, per-step engine selection (`Skill` vs `CLI`),
+context propagation across steps, post-step Gemini analysis for CLI steps,
+and retry/skip/abort on failure.

package/workflows/maestro.md

@@ -357,6 +357,7 @@ const chainMap = {
   'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '--mode full "{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'roadmap-driven':       [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'brainstorm-driven':    [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
+  'brainstorm_visualize': [{ cmd: 'brainstorm-visualize', args: '"{description}"' }],
   'impeccable-build':       [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'impeccable-driven':      [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'analyze-plan-execute': [{ cmd: 'maestro-analyze', args: '"{description}" -q' }, { cmd: 'maestro-plan', args: '--dir {scratch_dir}' }, { cmd: 'maestro-execute', args: '--dir {scratch_dir}' }],

package/workflows/milestone-complete.md

@@ -15,9 +15,9 @@ Archive completed milestone, move artifacts to history, and prepare for next.
 2. Check milestone audit status:
    - Read `.workflow/milestones/{milestone}/audit-report.md` if exists
    - If no audit report:
-     - WARN: "No audit report found. Run `/maestro-milestone-audit` first."
-     - Ask user: "Complete without audit?"
-     - If NO → exit
+     - ERROR E004: "No audit report found. Audit is a required hard contract — cannot complete without it."
+     - Guidance: "Run `/maestro-milestone-audit` first, then re-run this command."
+     - Exit (skipping audit is not permitted)
    - If verdict is FAIL: ERROR E002
 
 3. Verify all milestone artifacts have status "completed" → ERROR E003 if any incomplete (list ids and statuses)

package/workflows/milestone-release.md

@@ -0,0 +1,82 @@
+# Workflow: milestone-release
+
+Bump version, generate changelog, and tag the current milestone for release.
+
+> **STATUS: PLACEHOLDER** — minimal skeleton referenced by `maestro-milestone-release.md`.
+> Full release pipeline is TODO. Do not invoke until contents below are fleshed out.
+
+---
+
+## Arguments
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `<milestone>` | Milestone id from `.workflow/state.json` `milestones[]` | current_milestone |
+| `--bump <level>` | Semver bump: `major` \| `minor` \| `patch` | `minor` |
+| `--dry-run` | Preview changes without writing | `false` |
+
+---
+
+## Step 1: Validation
+
+1. Read `.workflow/state.json`:
+   - Determine target milestone (from `$ARGUMENTS` or `current_milestone`).
+   - If no milestone: ERROR E001.
+2. Verify milestone is **completed**:
+   - Read `.workflow/milestones/{milestone}/audit-report.md` — verdict must be `PASS`.
+   - If missing or non-PASS: ERROR E002 with guidance to run `/maestro-milestone-complete` first.
+3. Read package manifest (`package.json` / `pyproject.toml` / etc.) — locate current version. TODO: multi-manifest detection.
+
+---
+
+## Step 2: Version Bump
+
+1. Compute next version from `--bump` level (semver). TODO: prerelease/build metadata handling.
+2. Update manifest file in place. If `--dry-run`: print diff and exit.
+
+---
+
+## Step 3: Changelog Generation
+
+1. Read milestone audit report + retrospective insights (`.workflow/milestones/{milestone}/`).
+2. Render `CHANGELOG.md` entry — header `## [vX.Y.Z] - YYYY-MM-DD`, body grouped by `Added / Changed / Fixed / Removed`.
+3. TODO: integrate with `quality-retrospective` output for richer narrative.
+
+---
+
+## Step 4: Tag and Commit
+
+1. Stage updated manifest + `CHANGELOG.md`.
+2. Commit: `chore(release): vX.Y.Z — {milestone}`.
+3. Create annotated git tag `vX.Y.Z`.
+4. TODO: optionally push tag (`--push` flag).
+
+---
+
+## Outputs
+
+| Artifact | Status |
+|----------|--------|
+| Updated manifest version | written |
+| `CHANGELOG.md` entry | appended |
+| Git tag `vX.Y.Z` | created locally (not pushed) |
+
+---
+
+## Error Codes
+
+| Code | Meaning |
+|------|---------|
+| E001 | No milestone resolvable |
+| E002 | Milestone not completed / audit not PASS |
+| E003 | Manifest file not found |
+| E004 | Git working tree dirty (uncommitted changes block tagging) |
+
+---
+
+## TODO (placeholder gaps)
+
+- Multi-package monorepo support.
+- Push tag + GitHub release integration.
+- Roll-back path on failed tag.
+- Wire to `manage-knowhow-capture` for release-note capture.

package/workflows/plan.md

@@ -4,7 +4,7 @@
 
 Produces two-layer plan output: `plan.json` (overview with task_ids[] and waves[]) + `.task/TASK-{NNN}.json` (individual task definitions).
 
-All output goes to `.workflow/scratch/plan-{slug}-{date}/`.
+All output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`. Date-first ordering enables chronological sorting; scope prefix (`P{N}` for phase, `M{N}` for milestone, omit for standalone/adhoc) enables fallback identification.
 
 ---
 
@@ -166,12 +166,12 @@ When `--tdd` is active:
    - Map `insights[].summary` to implementation guidance for relevant tasks
    - These replace the need for a separate analyze step when brainstorm already provided sufficient role analysis
 
-5. **Parallel exploration** (skip if `--gaps` or upstream analysis loaded)
+6. **Parallel exploration** (skip if `--gaps` or upstream analysis loaded)
    - Exploration angles (1-4 based on complexity): architecture, implementation, integration, risk
    - Spawn 1-4 `cli-explore-agent` in parallel, each with phase goal + success_criteria + one angle
    - Output: `.process/exploration-{angle}.json`, `.process/explorations-manifest.json`, `.process/context-package.json`
 
-5b. **CLI supplementary context** (runs in parallel with step 5, skip if `--gaps` or no CLI tools enabled)
+6b. **CLI supplementary context** (runs in parallel with step 6, skip if `--gaps` or no CLI tools enabled)
    ```
    IF no CLI tools enabled: skip
 
@@ -188,7 +188,7 @@ When `--tdd` is active:
    ```
    **On callback:** Parse result, merge into explorationContext as `cli_context` field. Planner uses patterns for task `read_first[]`, dependencies for wave ordering, conflict_risks for collision detection.
 
-6. **Gap-mode context** (if `--gaps`)
+7. **Gap-mode context** (if `--gaps`)
 
    Gap sources (in priority order, first non-empty wins, then additionals merged):
    - **Primary**: `.workflow/issues/issues.jsonl` — filter by phase_ref + status in ["registered","diagnosed"], mark as "planning"
@@ -298,7 +298,7 @@ Every TASK-*.json MUST include these fields — they are NOT optional:
 
 ### Gap Mode (`--gaps`)
 
-Spawn `workflow-planner` agent with: explorationContext (gap list from P1 Step 6), spec-ref, doc-index.json, phase goal + success_criteria, templates, mode = `gap-fix`.
+Spawn `workflow-planner` agent with: explorationContext (gap list from P1 Step 7), spec-ref, doc-index.json, phase goal + success_criteria, templates, mode = `gap-fix`.
 
 Planner: for each gap emit one task — `type: "fix"`, `description`, `action` (concrete fix_direction), `read_first` (affected files), `convergence.criteria` (grep-verifiable), `issue_id` (if source == "issue"); assign IDs and waves; build plan.json.
 

package/workflows/quick.md

@@ -69,10 +69,10 @@ Quick tasks can run mid-phase -- validation only checks project exists, not phas
 **Create scratch directory:**
 
 Generate slug from $DESCRIPTION (lowercase, hyphens, max 40 chars).
-Set date to current date (YYYY-MM-DD).
+Set date to current date (YYYYMMDD).
 
 ```bash
-QUICK_DIR=".workflow/scratch/quick-${slug}-${date}"
+QUICK_DIR=".workflow/scratch/${date}-quick-${slug}"
 mkdir -p "$QUICK_DIR/.task"
 mkdir -p "$QUICK_DIR/.summaries"
 ```
@@ -80,7 +80,7 @@ mkdir -p "$QUICK_DIR/.summaries"
 Write index.json:
 ```json
 {
-  "id": "quick-{slug}-{date}",
+  "id": "{YYYYMMDD}-quick-{slug}",
   "type": "quick",
   "title": "{$DESCRIPTION}",
   "status": "active",
@@ -315,7 +315,7 @@ Read state.json. Add quick task to accumulated_context or quick_tasks array.
 Record:
 ```json
 {
-  "id": "quick-{slug}-{date}",
+  "id": "{YYYYMMDD}-quick-{slug}",
   "description": "{$DESCRIPTION}",
   "completed_at": "{ISO timestamp}",
   "directory": "{$QUICK_DIR}",

package/workflows/refactor.md

@@ -2,7 +2,7 @@
 
 Systematically reduce tech debt through scope analysis, task planning, and reflection-driven execution. Each refactoring round records strategy, outcome, and adjustments. Existing tests must pass after every change.
 
-Output: scratch/refactor-{slug}-{date}/ with index.json + reflection-log.md + .task/ + .summaries/
+Output: scratch/{YYYYMMDD}-refactor-{slug}/ with index.json + reflection-log.md + .task/ + .summaries/
 
 ---
 
@@ -24,13 +24,13 @@ Output: scratch/refactor-{slug}-{date}/ with index.json + reflection-log.md + .t
 
 Prompt user for scope type: module path, feature area, or full codebase.
 
-Generate slug from scope (lowercase, hyphens, max 40 chars). Set date = YYYY-MM-DD.
+Generate slug from scope (lowercase, hyphens, max 40 chars). Set date = YYYYMMDD.
 
 ---
 
 ### Step 2: Create Scratch Directory
 
-Create `REFACTOR_DIR=".workflow/scratch/refactor-${slug}-${date}"` with `.task/` and `.summaries/` subdirs.
+Create `REFACTOR_DIR=".workflow/scratch/${date}-refactor-${slug}"` with `.task/` and `.summaries/` subdirs.
 
 Write index.json: id, type="refactor", title, status="active", scope, plan (empty task_ids), execution (method=agent, counts=0), reflection (rounds=0).
 

package/workflows/retrospective.md

@@ -2,7 +2,7 @@
 
 Multi-lens 复盘 of completed phase artifacts. Consumes existing execution outputs (verification.json, review.json, issues.jsonl, .summaries/, state.json, uat.md, plan.json) and routes distilled insights into the spec / note / issue / knowhow stores.
 
-This is a **post-execution analysis** workflow. It reads only — until the routing stage, where it writes new spec stubs, issue rows, memory entries, and knowhow entries. It never modifies existing phase artifacts.
+This is a **post-execution analysis** workflow. It reads only — until the routing stage, where it writes new spec stubs, issue rows, memory entries, and knowhow entries. It **does not modify existing phase artifacts**; it writes to the spec / issue / knowhow stores as configured outputs (new entries appended; pre-existing phase outputs such as verification.json, review.json, uat.md, .summaries/ are never altered).
 
 ---
 
@@ -481,8 +481,8 @@ If `mode == "range"` or `--all`, loop Stages 3-8 per phase, then print aggregate
       "summary": "Refresh-on-use prevents replay attacks. Implemented in src/auth/refresh.ts; should become a project-wide convention.",
       "confidence": "high",
       "evidence_refs": [
-        ".workflow/scratch/plan-auth-2026-04-15/verification.json#gaps[2]",
-        ".workflow/scratch/plan-auth-2026-04-15/.summaries/TASK-005-summary.md:42"
+        ".workflow/scratch/20260415-plan-P1-auth/verification.json#gaps[2]",
+        ".workflow/scratch/20260415-plan-P1-auth/.summaries/TASK-005-summary.md:42"
       ],
       "tags": ["auth", "jwt", "security"],
       "routed_to": "spec",
@@ -508,7 +508,7 @@ Refresh-on-use prevents replay attacks. Implemented in src/auth/refresh.ts; shou
 - **Phase**: 1 (01-auth)
 - **Lens**: technical
 - **Confidence**: high
-- **Evidence**: .workflow/scratch/plan-auth-2026-04-15/verification.json#gaps[2]
+- **Evidence**: .workflow/scratch/20260415-plan-P1-auth/verification.json#gaps[2]
 - **Routed to**: spec (coding-conventions.md#INS-a1b2c3d4)
 
 </spec-entry>

package/workflows/roadmap.md

@@ -102,7 +102,7 @@ Follow roadmap-common.md **Roadmap Write Logic** (overwrite vs edit rules, state
 ## Step 6: Handoff
 
 Display summary (strategy, phase count, milestones, roadmap path) and offer next steps:
-- `maestro-init` — set up project (if not yet initialized)
+- `maestro-blueprint` — generate formal spec package for the roadmap (if heavier spec is needed)
 - `maestro-plan 1` — plan first phase
 - `maestro-brainstorm 1` — explore first phase ideas
 - `manage-status` — view project dashboard