maestro-flow 0.3.11 → 0.3.13

package/workflows/retrospective.md

@@ -9,7 +9,7 @@ This is a **post-execution analysis** workflow. It reads only — until the rout
 ## Prerequisites
 
 - `.workflow/` initialized (`.workflow/state.json` exists)
-- At least one phase directory under `.workflow/phases/{NN}-{slug}/`
+- At least one completed phase (via artifact registry in state.json)
 - Target phase has been executed (has `.task/` and `.summaries/`)
 - `maestro delegate` available (used for the four lens analyses via Agent calls)
 
@@ -61,18 +61,26 @@ This is a **post-execution analysis** workflow. It reads only — until the rout
 
 ```
 candidates = []
-FOR each .workflow/phases/{NN}-{slug}/index.json:
-  Read index.json
-  IF index.json.status == "completed":
-    has_retro = file exists at "{phase_dir}/retrospective.json"
+
+Read .workflow/state.json → state
+artifacts = state.artifacts ?? []
+
+// Resolve completed phases from artifact registry
+phaseNums = [...new Set(artifacts.map(a => a.phase).filter(Boolean))]
+FOR each phaseNum in phaseNums:
+  execArt = artifacts.find(a => a.type === 'execute' && a.phase === phaseNum && a.status === 'completed')
+  IF execArt:
+    artifact_dir = ".workflow/" + execArt.path
+    has_retro = file exists at "{artifact_dir}/retrospective.json"
     candidates.push({
-      number: NN,
-      slug: slug,
-      title: index.json.title or slug,
-      completed_at: index.json.completed_at,
+      number: phaseNum,
+      slug: execArt.slug ?? "phase-" + phaseNum,
+      title: execArt.title ?? execArt.slug ?? "Phase " + phaseNum,
+      completed_at: execArt.completed_at,
       has_retro: has_retro,
-      gaps: index.json.verification?.gaps?.length or 0,
-      review_verdict: index.json.review?.verdict or "—"
+      phase_dir: artifact_dir,
+      gaps: 0,
+      review_verdict: "—"
     })
 ```
 
@@ -103,34 +111,43 @@ FOR each .workflow/phases/{NN}-{slug}/index.json:
 
 If overwriting existing retrospective.json:
 ```
-mkdir -p "{phase_dir}/.history"
+mkdir -p "{candidate.phase_dir}/.history"   // phase_dir is artifact_dir from registry
 TIMESTAMP = format(now(), "YYYY-MM-DDTHH-mm-ss")
-mv "{phase_dir}/retrospective.json" "{phase_dir}/.history/retrospective-{TIMESTAMP}.json"
-mv "{phase_dir}/retrospective.md"   "{phase_dir}/.history/retrospective-{TIMESTAMP}.md"
+mv "{candidate.phase_dir}/retrospective.json" "{candidate.phase_dir}/.history/retrospective-{TIMESTAMP}.json"
+mv "{candidate.phase_dir}/retrospective.md"   "{candidate.phase_dir}/.history/retrospective-{TIMESTAMP}.md"
 ```
 
 ---
 
 ## Stage 3: load_artifacts (per phase)
 
-For each selected phase, build the in-memory artifacts bundle:
+For each selected phase (using `candidate.phase_dir` resolved in Stage 2), build the in-memory artifacts bundle:
 
 ```
+phase_dir = candidate.phase_dir  // already resolved from artifact registry (e.g. .workflow/scratch/plan-auth-2026-04-20)
+
 artifacts = {
   phase_num: NN,
   phase_slug: slug,
-  phase_dir: ".workflow/phases/{NN}-{slug}",
-  index: read JSON,
+  artifact_dir: artifact_dir,
+  index: read "{artifact_dir}/index.json" or null,
   state: read .workflow/state.json,
-  plan: read "{phase_dir}/plan.json" or null,
-  verification: read "{phase_dir}/verification.json" or null,
-  review: read "{phase_dir}/review.json" or null,
-  uat: read "{phase_dir}/uat.md" or null,
-  task_summaries: read all "{phase_dir}/.summaries/TASK-*-summary.md",
-  task_jsons: read all "{phase_dir}/.task/TASK-*.json",
+  plan: read "{artifact_dir}/plan.json" or null,
+  verification: read "{artifact_dir}/verification.json" or null,
+  review: read "{artifact_dir}/review.json" or null,
+  uat: read "{artifact_dir}/uat.md" or null,
+  task_summaries: read all "{artifact_dir}/.summaries/TASK-*-summary.md",
+  task_jsons: read all "{artifact_dir}/.task/TASK-*.json",
   phase_issues: filter ".workflow/issues/issues.jsonl" + ".workflow/issues/issue-history.jsonl"
                 where issue.phase_ref == phase_slug or issue.phase_ref == NN,
-  prior_retro: (if --compare M) read .workflow/phases/{MM}-*/retrospective.json
+  prior_retro: null
+}
+
+// Resolve --compare target
+IF --compare M:
+  compareArt = state.artifacts.find(a => a.type === 'execute' && a.phase === M)
+  IF compareArt:
+    artifacts.prior_retro = read ".workflow/" + compareArt.path + "/retrospective.json"
 }
 ```
 
@@ -206,12 +223,12 @@ the project's spec / note / issue stores.
 - Completed at: {index.completed_at}
 
 ## Artifacts (read these from disk)
-- Plan:           {phase_dir}/plan.json
-- Verification:   {phase_dir}/verification.json
-- Review:         {phase_dir}/review.json
-- UAT notes:      {phase_dir}/uat.md
-- Task summaries: {phase_dir}/.summaries/
-- Task JSONs:     {phase_dir}/.task/
+- Plan:           {artifact_dir}/plan.json
+- Verification:   {artifact_dir}/verification.json
+- Review:         {artifact_dir}/review.json
+- UAT notes:      {artifact_dir}/uat.md
+- Task summaries: {artifact_dir}/.summaries/
+- Task JSONs:     {artifact_dir}/.task/
 - Phase issues:   .workflow/issues/issues.jsonl (filter phase_ref == "{phase_slug}")
 - Project state:  .workflow/state.json (decisions, deferred)
 
@@ -248,7 +265,7 @@ Return ONLY a single JSON object, no prose, matching this schema:
       "title": "Short imperative title",
       "summary": "1–3 sentences a future planner can act on",
       "confidence": "high|medium|low",
-      "evidence_refs": ["{phase_dir}/verification.json#gaps[2]", "..."],
+      "evidence_refs": ["{artifact_dir}/verification.json#gaps[2]", "..."],
       "routed_to": "spec|note|issue|none",
       "tags": ["..."]
     }
@@ -422,10 +439,10 @@ retrospective = {
 | {INS-id} | note | ... |
 ```
 
-Write both files:
+Write both files (phase_dir already resolved in Stage 2):
 ```
-Write "{phase_dir}/retrospective.json"
-Write "{phase_dir}/retrospective.md"
+Write "{artifact_dir}/retrospective.json"
+Write "{artifact_dir}/retrospective.md"
 ```
 
 ---
@@ -454,46 +471,31 @@ Accept all? [Y/n/i for individual]
 
 #### Target: spec
 
-Write a stub spec file directly. Do NOT invoke `spec-generate` (heavyweight 7-phase pipeline).
+Route spec-routed insights as `<spec-entry>` entries into the appropriate category file. Map insight type to category:
+- `pattern` / `convention` → `coding`
+- `adr-candidate` / architecture → `arch`
+- quality-related → `quality`
 
 ```
-mkdir -p ".workflow/specs"
-slug = slugify(insight.title)
-spec_file = ".workflow/specs/SPEC-retro-{phase_num}-{INS_id}-{slug}.md"
-
-Write spec_file:
----
-status: draft
-type: pattern | convention | adr-candidate
-source: retrospective
-source_phase: {NN}
-source_insight: {INS_id}
-created_at: {now ISO}
-tags: {insight.tags}
-confidence: {insight.confidence}
----
-
-# {insight.title}
+category = map_insight_to_category(insight.type)
+target_file = category_to_file(category)  # e.g., coding → coding-conventions.md
 
-## Context
+keywords = extract_keywords(insight.title + insight.summary)  # 3-5 domain-specific terms
 
-Extracted from phase {NN} ({phase_slug}) retrospective by the {lens} lens.
-This stub captures a reusable {category} surfaced during execution; expand it
-into a full spec via `/maestro-spec-generate` if it warrants project-wide adoption.
+Append to .workflow/specs/{target_file}:
+  <spec-entry category="{category}" keywords="{keywords}" date="{YYYY-MM-DD}" source="retrospective">
 
-## Pattern / Convention
+  ### {insight.title}
 
-{insight.summary}
+  {insight.summary}
 
-## Evidence
-
-{FOR ref in evidence_refs:} - `{ref}`{END FOR}
+  **Evidence:** {FOR ref in evidence_refs:} `{ref}` {END FOR}
+  **Phase:** {NN} ({phase_slug}) | **Lens:** {lens} | **Insight:** {INS_id} | **Confidence:** {insight.confidence}
 
-## Open Questions
+  </spec-entry>
+```
 
-- Is this pattern already documented elsewhere?
-- Should existing code be migrated to this pattern, or is it forward-only?
-- What is the failure mode if this pattern is violated?
+If the target file does not exist, create it with category frontmatter first (same as `spec-add` on-demand creation).
 
 ## Routing trail
 
@@ -502,7 +504,7 @@ into a full spec via `/maestro-spec-generate` if it warrants project-wide adopti
 - Insight: {INS_id}
 - Confidence: {confidence}
 
-insight.routed_id = "SPEC-retro-{phase_num}-{INS_id}-{slug}.md"
+insight.routed_id = "{category_file}#INS-{INS_id}"  # e.g., coding-conventions.md#INS-a1b2c3d4
 ```
 
 #### Target: note
@@ -522,7 +524,7 @@ Capture the returned TIP-{id} from the skill output.
 insight.routed_id = "TIP-{captured_id}"
 ```
 
-If the skill call cannot be intercepted to capture the ID, fall back to writing the tip file directly using the schema in `workflows/memory.md` Part B Step 3 (Tip mode), and update `memory-index.json` per Step 4.
+If the skill call cannot be intercepted to capture the ID, fall back to writing the tip file directly using the schema in `workflows/memory.md` Part B Step 3 (Tip mode), and update `wiki-index.json` per Step 4.
 
 #### Target: issue
 
@@ -667,19 +669,24 @@ Write .workflow/learning/learning-index.json
 
 ### Backward-compat append to specs/learnings.md
 
-Append learnings to `.workflow/specs/learnings.md` (shared with milestone-complete's learning extraction). Append a one-line summary per insight:
+Append learnings to `.workflow/specs/learnings.md` (shared with milestone-complete's learning extraction) using `<spec-entry>` closed-tag format:
 
 ```
 IF .workflow/specs/learnings.md exists:
   FOR each insight:
-    Append under "## Entries":
-      ### [{YYYY-MM-DD HH:mm}] {category}: {title}
+    keywords = extract_keywords(insight.title + insight.summary)  # 3-5 domain-specific terms
+    Append:
+      <spec-entry category="learning" keywords="{keywords}" date="{YYYY-MM-DD}" source="retrospective">
+
+      ### {title}
 
       {summary}
-      Phase: {NN} | Source: retrospective | Insight: {INS_id} | Lens: {lens}
+      Phase: {NN} | Lens: {lens} | Insight: {INS_id}
+
+      </spec-entry>
 ```
 
-If the file does not exist, create it with a `## Entries` header.
+If the file does not exist, create it with category frontmatter and a `## Entries` header.
 
 ---
 
@@ -694,14 +701,14 @@ Lenses run:      {lenses joined by ", "}
 Insights:        {count}
 
 Routing summary:
-  Specs drafted:   {N}  → .workflow/specs/SPEC-retro-*
+  Spec entries:    {N}  → .workflow/specs/{category-file}.md
   Notes saved:     {N}  → .workflow/memory/TIP-*
   Issues opened:   {N}  → .workflow/issues/issues.jsonl
   Lessons logged:  {N}  → .workflow/learning/lessons.jsonl
 
 Files:
-  {phase_dir}/retrospective.md
-  {phase_dir}/retrospective.json
+  {artifact_dir}/retrospective.md
+  {artifact_dir}/retrospective.json
 
 Next steps (suggested):
   Skill({ skill: "manage-status" })                                    — Review project state
@@ -770,12 +777,12 @@ Total issues:        {sum}
       "summary": "Refresh-on-use prevents replay attacks. Implemented in src/auth/refresh.ts; should become a project-wide convention.",
       "confidence": "high",
       "evidence_refs": [
-        ".workflow/phases/01-auth/verification.json#gaps[2]",
-        ".workflow/phases/01-auth/.summaries/TASK-005-summary.md:42"
+        ".workflow/scratch/plan-auth-2026-04-15/verification.json#gaps[2]",
+        ".workflow/scratch/plan-auth-2026-04-15/.summaries/TASK-005-summary.md:42"
       ],
       "tags": ["auth", "jwt", "security"],
       "routed_to": "spec",
-      "routed_id": "SPEC-retro-1-INS-a1b2c3d4-jwt-refresh-rotation.md"
+      "routed_id": "coding-conventions.md#INS-a1b2c3d4"
     }
   ],
   "routing_recommendations": [
@@ -790,7 +797,7 @@ Total issues:        {sum}
 One JSON object per line:
 
 ```json
-{"id":"INS-a1b2c3d4","phase":1,"phase_slug":"01-auth","lens":"technical","category":"pattern","title":"JWT refresh tokens must rotate on every use","summary":"...","confidence":"high","tags":["auth","jwt","security"],"evidence_refs":["..."],"routed_to":"spec","routed_id":"SPEC-retro-1-INS-a1b2c3d4-jwt-refresh-rotation.md","source":"retrospective","captured_at":"2026-04-11T10:00:00Z"}
+{"id":"INS-a1b2c3d4","phase":1,"phase_slug":"01-auth","lens":"technical","category":"pattern","title":"JWT refresh tokens must rotate on every use","summary":"...","confidence":"high","tags":["auth","jwt","security"],"evidence_refs":["..."],"routed_to":"spec","routed_id":"coding-conventions.md#INS-a1b2c3d4","source":"retrospective","captured_at":"2026-04-11T10:00:00Z"}
 ```
 
 ### learning-index.json
@@ -811,7 +818,7 @@ One JSON object per line:
       "phase_slug": "01-auth",
       "confidence": "high",
       "routed_to": "spec",
-      "routed_id": "SPEC-retro-1-INS-a1b2c3d4-jwt-refresh-rotation.md"
+      "routed_id": "coding-conventions.md#INS-a1b2c3d4"
     }
   ],
   "_metadata": {

package/workflows/review.md

@@ -15,10 +15,16 @@ Tiered multi-dimensional code review with parallel agents, severity classificati
 
 ```
 Input: <phase> argument (number or slug)
-  1. If number: find .workflow/phases/{NN}-*/index.json
-  2. If slug: find .workflow/phases/*-{slug}/index.json
-  3. Validate execution has occurred (index.json.execution.tasks_completed > 0)
-  4. Set PHASE_DIR = resolved path
+
+Read .workflow/state.json → state
+artifacts = state.artifacts ?? []
+
+IF number: art = artifacts.find(a => a.type === 'execute' && a.phase === number)
+IF slug:   art = artifacts.find(a => a.type === 'execute' && a.slug?.includes(slug))
+IF art:    PHASE_DIR = ".workflow/" + art.path
+ELSE:      ERROR "Phase not found in artifact registry"
+
+Validate execution has occurred (tasks_completed > 0 or .task/ exists)
 ```
 
 ---
@@ -574,7 +580,7 @@ Verdict: {PASS | WARN | BLOCK}
 Issues Created: {count}
 
 Files:
-  {phase_dir}/review.json
+  {artifact_dir}/review.json
 
 Next steps:
   {suggested_next_command}

package/workflows/specs-remove.md

@@ -0,0 +1,115 @@
+# Spec Remove Workflow
+
+Remove a `<spec-entry>` block from a specs container file. Symmetric with `specs-add.md`.
+
+Uses `maestro wiki remove-entry` for atomic removal — the entry is deleted from the markdown file and the unified wiki index is auto-updated by WikiIndexer.
+
+---
+
+## Prerequisites
+
+- `.workflow/specs/` initialized (at least one specs file exists)
+- `maestro wiki` CLI available
+- Entry ID known (use `maestro wiki list --type spec` to discover)
+
+---
+
+## Argument Shape
+
+```
+/spec-remove spec-learnings-003                → remove entry 003 from learnings.md
+/spec-remove spec-coding-conventions-001       → remove entry 001 from coding-conventions.md
+/spec-remove spec-quality-rules-005 -y         → remove without confirmation
+```
+
+| Flag | Effect |
+|------|--------|
+| `<entry-id>` | Required. The spec sub-node ID to remove |
+| `-y` / `--yes` | Skip confirmation prompt |
+
+---
+
+## Stage 1: Parse Input
+
+1. Extract entry ID from arguments
+2. Validate non-empty (E001 if missing)
+3. Check `.workflow/specs/` exists (E002 if not)
+
+---
+
+## Stage 2: Lookup Entry
+
+1. Run `maestro wiki get <entry-id> --json` to fetch entry metadata
+2. Validate entry exists (E003 if not found)
+3. Validate entry is a spec sub-node — must have:
+   - `type` = "spec"
+   - `parent` field set (sub-nodes have parent pointing to container)
+   - If not a sub-node, error E004
+4. Extract: title, category, keywords, container file path, body preview
+
+---
+
+## Stage 3: Confirm Removal
+
+Display entry details for user confirmation:
+
+```
+== Spec Entry to Remove ==
+ID:        {entry-id}
+Title:     {title}
+Category:  {category}
+Keywords:  {keywords}
+Container: .workflow/specs/{filename}
+Preview:   {first 80 chars of body}
+
+Remove this entry? [y/N]
+```
+
+If `-y` flag: skip confirmation.
+If user declines: abort with "Cancelled."
+
+---
+
+## Stage 4: Remove Entry
+
+Execute removal via wiki CLI:
+
+```bash
+maestro wiki remove-entry <entry-id>
+```
+
+This command:
+1. Reads the container file
+2. Locates the `<spec-entry>` block by index position
+3. Removes the block (including opening tag, body, closing tag)
+4. Writes the updated file
+5. WikiIndexer auto-updates `.workflow/wiki-index.json`
+
+---
+
+## Stage 5: Verify & Report
+
+1. Verify entry no longer appears: `maestro wiki get <entry-id>` should return not-found
+2. Display confirmation:
+
+```
+== Entry Removed ==
+ID:        {entry-id}
+From:      .workflow/specs/{filename}
+Remaining: {remaining entry count} entries in {filename}
+
+To verify:  maestro wiki list --type spec --category {category}
+To re-add:  /spec-add {category} {content}
+```
+
+---
+
+## Error Codes
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | fatal | Entry ID required | Usage: `/spec-remove <entry-id>` |
+| E002 | fatal | `.workflow/specs/` not initialized | Run `/spec-setup` first |
+| E003 | fatal | Entry ID not found in wiki index | Check ID with `maestro wiki list --type spec` |
+| E004 | fatal | Entry is not a spec sub-node | Only `<spec-entry>` sub-nodes can be removed this way |
+| W001 | warning | Container file empty after removal | File kept but has no entries |

package/workflows/specs-setup.md

@@ -52,28 +52,7 @@ Framework detection (from dependency files):
   spring              --> Java Spring
 ```
 
-### Step 3: Write project-tech.json
-
-Output: `.workflow/project-tech.json`
-
-```json
-{
-  "detected_at": "{ISO timestamp}",
-  "languages": ["TypeScript", "..."],
-  "frameworks": ["Next.js", "..."],
-  "package_manager": "npm | yarn | pnpm | ...",
-  "build_system": "tsc | webpack | vite | ...",
-  "test_framework": "jest | vitest | pytest | ...",
-  "linter": "eslint | prettier | ...",
-  "architecture": {
-    "type": "monorepo | single-package | ...",
-    "entry_points": ["src/index.ts", "..."],
-    "key_directories": ["src/", "lib/", "..."]
-  }
-}
-```
-
-### Step 4: Detect Code Patterns
+### Step 3: Detect Code Patterns
 
 Scan source files for coding conventions:
 
@@ -85,9 +64,9 @@ Formatting:   Check for .prettierrc, .editorconfig, eslint config
 File naming:  kebab-case vs camelCase vs PascalCase for source files
 ```
 
-### Step 5: Generate Core Files (always created)
+### Step 4: Generate Core Files (always created)
 
-#### 5a: coding-conventions.md
+#### 4a: coding-conventions.md
 
 Output: `.workflow/specs/coding-conventions.md`
 
@@ -124,7 +103,7 @@ Auto-generated from project analysis. Update manually as patterns evolve.
 {empty section for spec-add entries}
 ```
 
-#### 5b: architecture-constraints.md
+#### 4b: architecture-constraints.md
 
 Output: `.workflow/specs/architecture-constraints.md`
 
@@ -156,7 +135,7 @@ Auto-generated from project structure. Update manually as architecture evolves.
 {empty section for spec-add entries}
 ```
 
-#### 5c: learnings.md
+#### 4c: learnings.md
 
 Output: `.workflow/specs/learnings.md`
 
@@ -175,9 +154,9 @@ Add entries with: `/spec-add learning <description>`
 {empty -- entries added via spec-add}
 ```
 
-### Step 6: Generate Optional Files (when signals detected)
+### Step 5: Generate Optional Files (when signals detected)
 
-#### 6a: quality-rules.md (when linter config or CI detected)
+#### 5a: quality-rules.md (when linter config or CI detected)
 
 Output: `.workflow/specs/quality-rules.md`
 
@@ -193,7 +172,7 @@ category: quality
 {empty -- entries added via spec-add}
 ```
 
-#### 6b: test-conventions.md (when test framework or test files detected)
+#### 5b: test-conventions.md (when test framework or test files detected)
 
 Scan existing test files for conventions (framework, naming, directory structure, patterns).
 
@@ -225,16 +204,15 @@ Auto-generated from project analysis. Update manually as patterns evolve.
 {empty section for spec-add entries}
 ```
 
-#### 6c: debug-notes.md and review-standards.md
+#### 5c: debug-notes.md and review-standards.md
 
 These are NOT created during setup. They are created on demand when `spec-add debug` or `spec-add review` is first used.
 
-### Step 7: Summary
+### Step 6: Summary
 
 Display what was created:
 ```
 Specs initialized:
-  .workflow/project-tech.json                    -- Tech stack analysis
   .workflow/specs/coding-conventions.md          (category: coding)
   .workflow/specs/architecture-constraints.md    (category: arch)
   .workflow/specs/learnings.md                   (category: learning)