maestro-flow 0.3.43 → 0.3.44

package/workflows/harvest.md

@@ -67,7 +67,7 @@ Scan `.workflow/` for harvestable artifacts. Each source type has a known struct
 | `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` | directory name |
 | `scratchpad` | `.workflow/.scratchpad/` | `*.md`, `*.json` | filename |
 | `session` | `.workflow/active/WFS-*/` | `workflow-session.json` | `WFS-*` |
-| `learning` | `.workflow/learning/` | `lessons.jsonl`, `digest-*.md`, `*.md` | filename |
+| `knowhow` | `.workflow/knowhow/` | `*.md`, `digest-*.md` | filename |
 
 Scan each source type (filtered by `--source`). For each matching directory/file within `--recent` window, extract: `source_type`, `id`, `path`, `title` (from JSON or H1), `updated_at`, `summary`, `file_count`.
 
@@ -143,8 +143,8 @@ Parse content to identify discrete knowledge items. Each source type has specifi
 
 **Debug (`debug-log.md`, `hypothesis-*.md`):**
 - Final diagnosis → bug fragment
-- Verified hypothesis → pattern/lesson fragment
-- Rejected hypotheses with reasoning → lesson fragment
+- Verified hypothesis → pattern/knowhow fragment
+- Rejected hypotheses with reasoning → knowhow fragment
 
 **Scratchpad (*.md):**
 - Markdown sections → generic fragments
@@ -155,8 +155,8 @@ Parse content to identify discrete knowledge items. Each source type has specifi
 - `key_decisions[]` → decision fragments
 - `deferred_items[]` → issue fragments
 
-**Learning (`lessons.jsonl`):**
-- Each lesson line → lesson fragment (check if already routed to wiki/spec/issue)
+**Learning Insights (`specs/learnings.md`):**
+- Each `<spec-entry>` → learning fragment (check if already routed to wiki/spec/issue)
 
 Each fragment gets:
 ```
@@ -167,7 +167,7 @@ fragment = {
   title: extracted or inferred,
   content: raw text,
   tags: extracted from context,
-  category: "finding" | "decision" | "pattern" | "bug" | "risk" | "task" | "lesson" | "recommendation",
+  category: "finding" | "decision" | "pattern" | "bug" | "risk" | "task" | "knowhow" | "recommendation",
   confidence: 0.0-1.0 (based on specificity and actionability)
 }
 ```
@@ -190,7 +190,7 @@ For each fragment, determine the best routing target (unless `--to` forces a spe
 | `bug` | issue or spec (bug) | Active bugs → issue; fixed bugs → spec learnings |
 | `risk` | issue | Unmitigated risks → trackable issues |
 | `task` | issue | Unfinished work → trackable issues |
-| `lesson` | wiki (lesson) | Generalizable insights → wiki knowledge |
+| `knowhow` | wiki (knowhow) | Generalizable insights → wiki knowledge |
 | `recommendation` | wiki (note) or issue | Actionable recommendations → issue; informational → wiki |
 
 ### Override with `--to`
@@ -214,7 +214,7 @@ Fragments extracted: 8 (filtered from 12 by confidence ≥ 0.5)
 
   → Wiki (3 entries):
     [note]   "SQL injection vector in user input"     tags: security, sql
-    [lesson] "Parameterized queries prevent injection" tags: security, pattern
+    [knowhow] "Parameterized queries prevent injection" tags: security, pattern
     [spec]   "Auth token rotation policy"              tags: auth, security
 
   → Spec (2 entries):
@@ -239,11 +239,11 @@ Execute the routing plan. Each target uses existing infrastructure:
 
 ### 6a. Wiki routing
 
-Create via `maestro wiki create --type <wiki_type> --slug harvest-<source_type>-<short_id> --title --tags --body`. Types: note/lesson/spec. Fallback on failure: write `.workflow/harvest/wiki-pending-{id}.md` with frontmatter.
+Create via `maestro wiki create --type <wiki_type> --slug harvest-<source_type>-<short_id> --title --tags --body`. Types: note/knowhow/spec. Fallback on failure: write `.workflow/harvest/wiki-pending-{id}.md` with frontmatter.
 
 ### 6b. Spec routing
 
-Route via `Skill({ skill: "spec-add", args: "<spec_type> <content>" })`. Category mapping: pattern→pattern, decision→decision, bug→bug, lesson→rule.
+Route via `Skill({ skill: "spec-add", args: "<spec_type> <content>" })`. Category mapping: pattern→pattern, decision→decision, bug→bug, knowhow→rule.
 
 ### 6c. Issue routing
 
@@ -287,7 +287,7 @@ This log prevents duplicate harvesting in future runs.
 
 ## Stage 7: dedup_check
 
-Before writing any item in Stage 6, check for duplicates across `harvest-log.jsonl` (by fragment_id), wiki (by title search), `issues.jsonl` (by title/description), and `learnings.md` (by content). Duplicates are skipped with `[SKIP-DUP]` marker and logged to harvest report.
+Before writing any item in Stage 6, check for duplicates across `harvest-log.jsonl` (by fragment_id), wiki (by title search), `issues.jsonl` (by title/description), and `specs/learnings.md` (by content). Duplicates are skipped with `[SKIP-DUP]` marker and logged to harvest report.
 
 ---
 
@@ -314,7 +314,7 @@ Write `.workflow/harvest/harvest-report-{date}.md`:
 | # | Type | Slug | Title | Status |
 |---|------|------|-------|--------|
 | 1 | note | harvest-analysis-abc | SQL injection vector | CREATED |
-| 2 | lesson | harvest-analysis-def | Parameterized queries | CREATED |
+| 2 | knowhow | harvest-analysis-def | Parameterized queries | CREATED |
 
 ### Spec ({N} entries)
 | # | Type | Content (truncated) | Status |
@@ -349,5 +349,5 @@ Next:
   → Review wiki entries: maestro wiki list --type note
   → Triage issues: Skill({ skill: "manage-issue", args: "list --source harvest" })
   → Connect wiki graph: Skill({ skill: "wiki-connect", args: "--fix" })
-  → View specs: Skill({ skill: "spec-load", args: "--category learning" })
+  → View specs: Skill({ skill: "spec-load", args: "--role implement" })
 ```

package/workflows/integration-test.md

@@ -30,8 +30,8 @@ If existing session at `${PHASE_DIR}/.tests/integration/state.json`: offer resum
 ### Step 1.3: Load Project Specs
 
 ```
-specs_content = maestro spec load --category test
-arch_content = maestro spec load --category arch
+specs_content = maestro spec load --role test
+arch_content = maestro spec load --role plan
 ```
 
 `specs_content` for test conventions; `arch_content` for module boundaries in Step 2-3.

package/workflows/issue-discover.md

@@ -86,7 +86,7 @@ Initialize discovery-state.json:
 ### Step 3.5: Load Project Specs
 
 ```
-specs_content = maestro spec load --category coding
+specs_content = maestro spec load --role implement
 ```
 
 Pass to each analysis agent so severity assessments align with project quality standards.

package/workflows/knowhow.md

@@ -30,7 +30,7 @@ Six types of knowhow, each with dedicated structure:
 | `decision` | DCS- | Architecture Decision Record | Making non-trivial design choices |
 | `tip` | TIP- | Quick note, snippet, reminder | Fleeting insight, debugging trick |
 
-All types share `WikiNodeType = 'knowhow'`. The `category` field distinguishes subtypes in wiki queries.
+All types share `WikiNodeType = 'knowhow'`. The `type` field distinguishes subtypes in wiki queries.
 
 ---
 
@@ -60,7 +60,7 @@ Verify stores exist. Neither → E001.
 
 ### Step 3: List
 
-Workflow: `maestro wiki list --type knowhow --json`, filter by `--tag`, `--type`, `--category`.
+Workflow: `maestro wiki list --type knowhow --json`, filter by `--keywords`, `--type`, `--role`.
 System: Glob `*.md` files, extract titles.
 
 Display: ID/File, Type, Category, Date, Tags, Summary with navigation hints.
@@ -123,7 +123,6 @@ Reusable code or configuration pattern. Sections:
 ---
 title: {descriptive name}
 type: template
-category: template
 lang: {typescript|python|bash|yaml|...}
 tags: [{comma-separated}]
 created: {ISO timestamp}
@@ -166,7 +165,6 @@ Step-by-step operational guide. Sections:
 ---
 title: {goal summary}
 type: recipe
-category: recipe
 tags: [{comma-separated}]
 created: {ISO timestamp}
 ---
@@ -211,7 +209,6 @@ External documentation digest. Sections:
 ---
 title: {reference title}
 type: reference
-category: reference
 source: {original URL}
 tags: [{comma-separated}]
 created: {ISO timestamp}
@@ -254,7 +251,6 @@ Architecture Decision Record. Sections:
 ---
 title: {decision summary}
 type: decision
-category: decision
 status: {proposed|accepted|superseded}
 tags: [{comma-separated}]
 created: {ISO timestamp}
@@ -304,7 +300,6 @@ Quick note. Minimal structure:
 ---
 title: {tip summary}
 type: tip
-category: tip
 tags: [{comma-separated}]
 created: {ISO timestamp}
 ---
@@ -327,7 +322,6 @@ Frontmatter keys by type:
 |-------|:-------:|:--------:|:------:|:---------:|:--------:|:---:|
 | title | Y | Y | Y | Y | Y | Y |
 | type | Y | Y | Y | Y | Y | Y |
-| category | Y | Y | Y | Y | Y | Y |
 | tags | Y | Y | Y | Y | Y | Y |
 | created | Y | Y | Y | Y | Y | Y |
 | lang | | Y | | | | |
@@ -352,7 +346,7 @@ maestro knowhow search "deploy auth"    # full-text
 maestro knowhow get knowhow-{slug}      # view one
 
 maestro wiki list --type knowhow --json # programmatic
-maestro wiki list --type knowhow --category decision  # decisions only
+maestro wiki list --type knowhow --role plan  # decisions only
 ```
 
 ### MCP
@@ -364,11 +358,78 @@ store_knowhow { operation: "add", type: "template", title: "...", body: "..." }
 
 ### Type Label Reference
 
-| Wiki type | Category | Prefix | Label |
-|-----------|----------|--------|-------|
+| Wiki type | Type | Prefix | Label |
+|-----------|------|--------|-------|
 | knowhow | session | KNW- | Session |
 | knowhow | tip | TIP- | Tip |
 | knowhow | template | TPL- | Template |
 | knowhow | recipe | RCP- | Recipe |
 | knowhow | reference | REF- | Reference |
 | knowhow | decision | DCS- | Decision |
+| spec | learning | — | Learning Insight (in `specs/learnings.md`) |
+
+---
+
+## Part D: Learning Insights Container (specs/learnings.md)
+
+A special container file at `.workflow/specs/learnings.md` holds multiple `<spec-entry>` sub-entries for atomic learning insights. This replaces the former `lessons.jsonl` approach.
+
+### Container Format
+
+```markdown
+---
+title: "Learning Insights"
+type: spec
+roles: [implement]
+tags: [insights, learning]
+created: {ISO timestamp}
+---
+# Learning Insights
+
+Atomic insights captured during active work.
+
+## Entries
+
+<spec-entry roles="implement" keywords="pattern,auth,jwt" date="2026-05-10" id="INS-abc123" source="manual">
+
+### JWT refresh tokens must rotate on every use
+
+Refresh-on-use prevents replay attacks.
+
+- **Phase**: 1 (01-auth)
+- **Confidence**: high
+- **Tags**: auth, jwt, security
+
+</spec-entry>
+
+<spec-entry roles="analyze" keywords="gotcha,redis,cache" date="2026-05-11" id="INS-def456" source="retrospective">
+
+### Redis MULTI is not truly transactional
+
+MULTI/EXEC guarantees atomicity but not isolation...
+
+- **Phase**: 2 (02-cache)
+- **Lens**: technical
+- **Confidence**: medium
+
+</spec-entry>
+```
+
+### Producers
+
+Multiple workflows append `<spec-entry>` blocks to this container:
+
+| Workflow | Source value | When |
+|----------|-------------|------|
+| `manage-learn` | `manual` or `tip` | Manual capture during active work |
+| `quality-retrospective` | `retrospective` | Phase retrospective insight distillation |
+| `learn-retro` | `retro-git` or `retro-decision` | Retrospective from git activity or decisions |
+| `wiki-connect` | `wiki-connect` | Graph connectivity insights |
+| `wiki-digest` | `wiki-digest` | Knowledge synthesis meta-insights |
+
+### Retrieval
+
+```bash
+maestro wiki list --type knowhow --role implement    # list all insights
+maestro wiki search "<query>"                           # full-text search
+```

package/workflows/learn.md

@@ -3,8 +3,8 @@
 Atomic insight capture, search, and retrieval. Lightweight gstack-style "eureka moment" log that complements the retrospective workflow: where retrospective extracts insights from completed phases in bulk, `manage-learn` captures one insight at a time during active work.
 
 Storage:
-- `.workflow/learning/lessons.jsonl` — append-only JSONL row per insight (shared with retrospective output)
-- `.workflow/learning/learning-index.json` — searchable index
+- `.workflow/specs/learnings.md` — append-only container of `<spec-entry>` sub-entries (shared with retrospective output)
+- Auto-indexed by WikiIndexer (no manual index required)
 
 **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.
 
@@ -15,7 +15,7 @@ This workflow does NOT spawn agents or call CLI tools. It is a thin file operati
 ## Prerequisites
 
 - `.workflow/` initialized (`.workflow/state.json` exists). If missing, error E001.
-- The `learning/` directory and its files are created on first use; do not require them to exist upfront.
+- The `specs/` directory and `learnings.md` are created on first use; do not require them to exist upfront.
 
 ---
 
@@ -23,17 +23,17 @@ This workflow does NOT spawn agents or call CLI tools. It is a thin file operati
 
 ```
 /manage-learn "<insight text>"                                  → capture, infer category, auto-link phase
-/manage-learn "<insight>" --category pattern --tag auth,jwt    → capture with explicit category and tags
+/manage-learn "<insight>" --category pattern --keywords auth,jwt → capture with explicit category and keywords
 /manage-learn list                                              → show recent 20 insights
-/manage-learn list --tag auth                                   → filtered list
-/manage-learn search <query>                                    → text search across lessons.jsonl
+/manage-learn list --keywords auth                              → filtered list
+/manage-learn search <query>                                    → search via maestro wiki search
 /manage-learn show <INS-id>                                     → full insight + linked phase context
 ```
 
 | Flag | Effect |
 |------|--------|
 | `--category <name>` | One of: pattern, antipattern, decision, tool, gotcha, technique, tip. Default: inferred (tip mode defaults to `tip`). |
-| `--tag t1,t2` | Comma-separated tags. Insight mode implicitly adds `manual`, tip mode implicitly adds `tip`. |
+| `--keywords t1,t2` | Comma-separated keywords. Insight mode implicitly adds `manual`, tip mode implicitly adds `tip`. |
 | `--phase <N>` | Override auto-detected phase link. Use `--phase 0` to force "no phase". |
 | `--confidence <level>` | high / medium / low. Default: medium (insight), low (tip). |
 | `--lens <name>` | Filter by retrospective lens: technical, process, quality, decision, git (list/search only). |
@@ -46,7 +46,7 @@ This workflow does NOT spawn agents or call CLI tools. It is a thin file operati
 ```
 Verify .workflow/ exists (else E001). Route by first token:
   "list" → list | "search" → search (next token = query) | "show" → show (next token = INS-id)
-  "tip"  → tip capture (source="tip", category="tip", confidence="low", implicit tag "tip")
+  "tip"  → tip capture (source="tip", category="tip", confidence="low", implicit keyword "tip")
   else   → capture mode (full quoted text = insight body)
 Empty args → AskUserQuestion. Invalid --category → E002.
 ```
@@ -58,15 +58,27 @@ Empty args → AskUserQuestion. Invalid --category → E002.
 ### Step 2.1: Bootstrap storage
 
 ```bash
-LEARN_DIR=".workflow/learning"
-LESSONS_FILE="$LEARN_DIR/lessons.jsonl"
-INDEX_FILE="$LEARN_DIR/learning-index.json"
+SPECS_DIR=".workflow/specs"
+INSIGHTS_FILE="$SPECS_DIR/learnings.md"
 
-mkdir -p "$LEARN_DIR"
-touch "$LESSONS_FILE"
+mkdir -p "$SPECS_DIR"
 
-if [ ! -f "$INDEX_FILE" ]; then
-  echo '{"entries":[],"_metadata":{"created":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","version":"1.0"}}' > "$INDEX_FILE"
+if [ ! -f "$INSIGHTS_FILE" ]; then
+  cat > "$INSIGHTS_FILE" << 'EOF'
+---
+title: "Learning Insights"
+type: spec
+roles: [implement]
+tags: [insights, learning]
+created: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+---
+# Learning Insights
+
+Atomic insights captured during active work.
+
+## Entries
+
+EOF
 fi
 ```
 
@@ -102,32 +114,33 @@ Simple keyword heuristics — no LLM call. Match the insight text (lowercased) a
 
 First match wins. If nothing matches, category = `technique`.
 
-### Step 2.5: Build row
+### Step 2.5: Build spec-entry
 
 ```
-row = {
-  id: "INS-{hex}",
-  phase: phase,
-  phase_slug: phase_slug,
-  lens: null,                  // null for manual capture (only retrospective sets this)
-  category: category,
-  title: first 80 chars of insight text (truncated on word boundary),
-  summary: full insight text,
-  confidence: --confidence value or "medium",
-  tags: parsed --tag values + ["manual"],
-  evidence_refs: [],           // empty for manual capture
-  routed_to: "none",
-  routed_id: null,
-  source: "manual",
-  captured_at: now ISO 8601 UTC
-}
+entry = <spec-entry
+  roles="{role}"
+  keywords="{category},{parsed --keywords values joined by comma}"
+  date="{YYYY-MM-DD}"
+  id="INS-{hex}"
+  source="manual"
+>
+
+### {title: first 80 chars of insight text, truncated on word boundary}
+
+{full insight text}
+
+- **Phase**: {phase or "none"} ({phase_slug or "—"})
+- **Confidence**: {--confidence value or "medium"}
+- **Tags**: {parsed --keywords values + ["manual"]}
+
+</spec-entry>
 ```
 
 ### Step 2.6: Persist
 
-Append row as single JSON line to `.workflow/learning/lessons.jsonl`.
+Append the `<spec-entry>` block to `.workflow/specs/learnings.md`.
 
-Update `.workflow/learning/learning-index.json` — append an index entry mirroring key row fields: `id`, `type:"insight"`, `timestamp`, `file:"lessons.jsonl"`, `summary` (=title), `tags`, `lens`, `category`, `phase`, `phase_slug`, `confidence`, `routed_to:"none"`, `routed_id:null`.
+WikiIndexer auto-indexes the entry — no manual index update required.
 
 ### Step 2.7: Confirmation banner
 
@@ -139,12 +152,12 @@ Display: ID, category, confidence, tags, phase (+slug if present), title, file p
 
 ### Step 3.1: Read entries
 
-Read `.workflow/learning/learning-index.json`. Filter by `--tag`, `--category`, `--phase`, `--lens` flags. Sort by timestamp descending. Limit to 20 (or `--limit N`).
+Query via `maestro wiki list --type knowhow --role implement --json`. Filter by `--keywords`, `--category`, `--phase`, `--lens` flags. Sort by timestamp descending. Limit to 20 (or `--limit N`).
 
 ### Step 3.2: Display table
 
 ```
-=== LEARNING INSIGHTS ({shown}/{total}) ===
+=== KNOWHOW INSIGHTS ({shown}/{total}) ===
 
   ID              Category    Phase   Conf   Tags                 Title
   ──────────────  ──────────  ──────  ─────  ───────────────────  ────────────────────────────
@@ -174,9 +187,9 @@ Capture your first: Skill({ skill: "manage-learn", args: "\"...\"" })
 
 Next token after "search". Empty → AskUserQuestion.
 
-### Step 4.2: Scan lessons.jsonl
+### Step 4.2: Search via wiki
 
-Case-insensitive search across each row's `title`, `summary`, `tags`, `category`, `lens`. Rank matches: title match +3, tags +2, summary +1. Sort by rank desc, then captured_at desc.
+Execute `maestro wiki search "<query>" --type knowhow --json`. Results are ranked by BM25 relevance. Sort by rank desc, then date desc.
 
 ### Step 4.3: Display results
 
@@ -204,45 +217,44 @@ List all: Skill({ skill: "manage-learn", args: "list" })
 
 ## Stage 5: show mode
 
-### Step 5.1: Locate row
+### Step 5.1: Locate entry
 
-Find row matching target INS-id in `lessons.jsonl`. Missing arg → E003. Not found → E004.
+Find `<spec-entry>` matching target INS-id in `learnings.md`. Missing arg → E003. Not found → E004.
 
 ### Step 5.2: Resolve linked phase context (if any)
 
-If `row.phase_slug` set: look up phase directory from `state.json` artifacts, read its `index.json` for title/status, check for `retrospective.md`.
+If `entry.phase_slug` set (parsed from entry content): look up phase directory from `state.json` artifacts, read its `index.json` for title/status, check for `retrospective.md`.
 
 ### Step 5.3: Resolve routed artifact (if any)
 
-Map `routed_to` → path: `spec` → `.workflow/specs/{id}`, `issue` → `.workflow/issues/issues.jsonl#{id}`, `note` → `.workflow/knowhow/{id}.md`.
+Map `routed_to` → path: `spec` → `.workflow/specs/{id}`, `issue` → `.workflow/issues/issues.jsonl#{id}`, `knowhow` → `.workflow/knowhow/{id}.md`.
 
 ### Step 5.4: Display
 
 ```
 =========================================
-  INSIGHT: {row.id}
-  CATEGORY: {row.category}
-  CONFIDENCE: {row.confidence}
-  SOURCE: {row.source}{IF row.lens: " (" + row.lens + " lens)"}
+  INSIGHT: {entry.id}
+  CATEGORY: {entry.category}
+  CONFIDENCE: {entry.confidence}
+  SOURCE: {entry.source}{IF entry.lens: " (" + entry.lens + " lens)"}
 =========================================
 
-CAPTURED:    {row.captured_at}
-PHASE:       {row.phase or "none"}{IF phase_slug: " (" + phase_slug + ")"}
-TAGS:        {row.tags joined by ", "}
+CAPTURED:    {entry.date}
+PHASE:       {entry.phase or "none"}{IF phase_slug: " (" + phase_slug + ")"}
+TAGS:        {entry.keywords}
 
 TITLE:
-  {row.title}
+  {entry.title}
 
 SUMMARY:
-  {row.summary}
+  {entry.content}
 
 EVIDENCE:
-  {FOR ref in row.evidence_refs:} - {ref}{END FOR}
-  {OR "(none — manual capture)"}
+  {parsed from entry content, or "(none — manual capture)"}
 
 ROUTED:
-  Target: {row.routed_to}
-  ID:     {row.routed_id or "—"}
+  Target: {entry.routed_to or "none"}
+  ID:     {entry.routed_id or "—"}
   Path:   {routed_path or "—"}
 
 {IF phase_context:}
@@ -259,7 +271,7 @@ PHASE CONTEXT:
 
 | Workflow | Relationship |
 |----------|--------------|
-| `quality-retrospective` | Producer. Writes insights into the same `lessons.jsonl` with `source: "retrospective"` and a populated `lens` field. |
-| `manage-knowhow-capture` | Sibling. Captures session state for recovery; `learn` captures timeless insights. They share the JSONL+index pattern but live in different directories so retrieval semantics stay clean. |
+| `quality-retrospective` | Producer. Appends `<spec-entry>` to the same `specs/learnings.md` with `source: "retrospective"` and a populated `lens` field. |
+| `manage-knowhow-capture` | Sibling. Captures session state for recovery; `learn` captures timeless insights. Both write to `.workflow/knowhow/` with different prefixes. |
 | `phase-transition` | Reader (informally). Phase-transition's free-form `.workflow/specs/learnings.md` is a distinct file with a different audience; do not merge them. |
-| `maestro-plan` | Future consumer. Should query `lessons.jsonl` filtered by tag/lens/category to inform planning decisions. (Out of scope for this command.) |
+| `maestro-plan` | Future consumer. Should query via `maestro wiki search` or `maestro wiki list --type knowhow --role implement` to inform planning decisions. (Out of scope for this command.) |

package/workflows/map.md

@@ -30,7 +30,7 @@ Spawn 4 parallel `workflow-codebase-mapper` agents, each writing to `.workflow/r
 
 If `$ARGUMENTS` provided, pass as focus filter to each agent.
 
-Load project specs: `maestro spec load --category arch`
+Load project specs: `maestro spec load --role plan`
 
 Each agent spawned in parallel as `workflow-codebase-mapper` subagent with specs context.
 

package/workflows/milestone-complete.md

@@ -41,7 +41,7 @@ Archive completed milestone, move artifacts to history, and prepare for next.
 ## Step 2.5: Load Existing Learnings
 
 ```
-existing_learnings = maestro spec load --category learning
+existing_learnings = maestro spec load --role implement
 ```
 
 Check existing entries to avoid duplicates when appending in Step 3.
@@ -57,7 +57,7 @@ Check existing entries to avoid duplicates when appending in Step 3.
 
 2. Aggregate learnings and append to `.workflow/specs/learnings.md` using `<spec-entry>` closed-tag format. Each entry (strategy adjustment, pattern, or pitfall) follows this template:
    ```
-   <spec-entry category="learning" keywords="{auto-extracted}" date="{YYYY-MM-DD}" source="milestone-complete">
+   <spec-entry roles="implement" keywords="{auto-extracted}" date="{YYYY-MM-DD}" source="milestone-complete">
 
    ### {summary}
 

package/workflows/plan.md

@@ -74,7 +74,7 @@ default             → Create Mode: P1 → P2 → P3 → P4 → P4.5 → P5
 
 3. **Load project specs**
    ```
-   specs_content = maestro spec load --category arch
+   specs_content = maestro spec load --role plan
    ```
    Pass to planner agent as project constraints context.
 

package/workflows/quick.md

@@ -204,7 +204,7 @@ Report: "Context captured: ${QUICK_DIR}/context.md"
 ### Step 4.5: Load Project Specs
 
 ```
-specs_content = maestro spec load --category coding
+specs_content = maestro spec load --role implement
 ```
 
 Passed inline to planner agent in Step 5.

package/workflows/refactor.md

@@ -39,7 +39,7 @@ Write index.json: id, type="refactor", title, status="active", scope, plan (empt
 ### Step 2.5: Load Project Specs
 
 ```
-specs_content = maestro spec load --category coding
+specs_content = maestro spec load --role implement
 ```
 
 Used in Step 3 to detect pattern violations against project conventions.