maestro-flow 0.4.12 → 0.4.14

package/workflows/spec-generate.md

@@ -11,6 +11,8 @@ brainstorm (optional) → init (REQUIRED) → spec-generate → plan → execute
 Alternative light path: init → roadmap (light mode) → plan (skip spec-generate)
 ```
 
+> **Relation to blueprint**: `spec-generate` is the full-pipeline superset of `blueprint` (adds P7 roadmap stage on top of P0–P6 spec chain). Use `blueprint` when only specs are needed; use `spec-generate` when downstream `roadmap → plan` execution is intended.
+
 ## Architecture
 
 ```

package/workflows/specs-add.md

@@ -1,4 +1,9 @@
-# Workflow: specs-add
+---
+name: spec-add
+alias: spec-add
+---
+
+# Workflow: spec-add
 
 Add a `<spec-entry>` closed-tag entry to a single target spec file by category.
 

package/workflows/specs-load.md

@@ -1,4 +1,9 @@
-# Workflow: specs-load
+---
+name: spec-load
+alias: spec-load
+---
+
+# Workflow: spec-load
 
 Load spec files filtered by category. Supports project, global, team, and personal scopes.
 

package/workflows/specs-setup.md

@@ -1,4 +1,9 @@
-# Workflow: specs-setup
+---
+name: spec-setup
+alias: spec-setup
+---
+
+# Workflow: spec-setup
 
 System specs initialization -- scan project structure, detect tech stack, generate convention files.
 

package/workflows/sync.md

@@ -47,6 +47,19 @@ Read .workflow/codebase/doc-index.json
 Extract: components[], features[], requirements[], architecture_decisions[]
 ```
 
+**Degradation path — doc-index.json missing:**
+
+```
+If .workflow/codebase/doc-index.json does NOT exist:
+  1. Emit WARNING: "doc-index.json missing — sync cannot perform impact analysis."
+  2. Prompt user with two choices:
+     (a) Run `/manage-codebase-rebuild` to build doc-index, then re-run sync (recommended)
+     (b) Fall back to git-diff-only mode: skip Steps 3-5, emit raw changed-file
+         list from Step 2 as the sync output (no component/feature mapping)
+  3. If user picks (b): set DEGRADED_MODE = true and continue with git diff only.
+  4. If user picks (a) or no answer: exit with code E002.
+```
+
 ### Step 4: Impact Chain Traversal
 
 For each `changed_file` in `changed_files[]`:

package/workflows/tools-spec.md

@@ -1,5 +1,9 @@
 # Tool Spec Reference
 
+<reference>
+Tool specs are a **subtype of knowhow** (`tool: true` frontmatter on knowhow documents). For the full knowhow data model, lifecycle, and management commands, see `knowhow.md`. This file documents only the tool-specific subset.
+</reference>
+
 Shared reference for tool spec registration and execution commands.
 
 ## Storage

package/workflows/ui-design.md

@@ -6,9 +6,9 @@ User reviews via compare.html, selects winner(s), design solidified as code refe
 
 Pipeline position: analyze -> **ui-design** -> plan -> execute -> verify
 
-> **Note:** This is the full self-contained pipeline. When ui-ux-pro-max skill is available,
-> the command routes to `ui-style.md` instead (lightweight delegation).
-> This workflow runs when the skill is absent or `--full` is explicitly requested.
+> **Note:** This is the primary implementation. When the `ui-ux-pro-max` skill is available,
+> the command may delegate to `ui-style.md` for a lightweight path. This workflow is the
+> fallback when the skill is unavailable, and is also used when `--full` is explicitly requested.
 
 ---
 
@@ -24,7 +24,7 @@ Pipeline position: analyze -> **ui-design** -> plan -> execute -> verify
 
 ```
 Input: <phase> (number) OR topic text
-Output: .workflow/scratch/ui-design-{slug}-{date}/
+Output: .workflow/scratch/{YYYYMMDD}-ui-design-{slug}/
 
 Resolve scope:
   number → phase slug from roadmap.md, scope="phase", register with phase

package/workflows/ui-style.md

@@ -23,7 +23,7 @@ If argument is phase number/slug:
   SCRATCH_MODE = false
 
 If argument is topic text (scratch mode):
-  PHASE_DIR = .workflow/scratch/ui-design-{slug}-{YYYYMMDD}
+  PHASE_DIR = .workflow/scratch/{YYYYMMDD}-ui-design-{slug}
   Create directory + minimal index.json (type="ui-design", goal=topic).
   SCRATCH_MODE = true
 ```

package/workflows/verify.md

@@ -82,7 +82,7 @@ Resolve PLAN_DIRS and VERIFY_MODE by input type:
   numeric arg     → phase mode, collect completed execute artifacts for that phase from state.json
 
 If no matching artifacts found: ERROR E001.
-Milestone mode creates output dir: .workflow/scratch/verify-{milestone_slug}-{date}/
+Milestone mode creates output dir: .workflow/scratch/{YYYYMMDD}-verify-{milestone_slug}/
 ```
 
 ---

package/workflows/wiki-manage.md

@@ -44,6 +44,8 @@ Run in parallel: `maestro wiki health`, `list --json`, `orphans`, `hubs --top 5`
 
 Display: health score, entry counts by type, broken links, orphan count, top hubs. Include health status message and quick-action commands (`/wiki-connect --fix`, `/wiki-digest`, `/manage-wiki cleanup --fix`, `maestro wiki graph`).
 
+> **Scope split (complementary, not conflicting):** `/wiki-connect --fix` repairs/augments `related` links between existing entries (no deletion). `/manage-wiki cleanup --fix` deletes/flags orphans and removes broken-link entries from frontmatter. Run `wiki-connect` first to maximize link recovery, then `cleanup` to handle the true residual orphans.
+
 ---
 
 ## Subcommand: search <query>