maestro-flow 0.3.6 → 0.3.8

package/.claude/commands/maestro-learn.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-learn
-description: Learning coordinator - analyze intent → route to optimal learn command chain → execute via Skill()
+description: Learning coordinator — route intent to learn commands, execute single or multi-step chains
 argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
 allowed-tools:
   - Read
@@ -12,23 +12,18 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Orchestrate all learn-* commands based on user intent. Routes natural language learning requests to the optimal learn command or multi-step chain.
+Route learning requests to the optimal learn command or multi-step chain. Supports direct chain selection via `--chain` or intent-based routing via keyword matching.
 
-Two routing modes:
-1. **Intent-based**: User describes a learning goal → classify → select command/chain → confirm → execute
-2. **Direct**: User specifies a known chain name via `--chain`
-
-Produces session directory at `.workflow/learning/.maestro-learn/{session_id}/` with status.json tracking chain progress.
-Executes commands sequentially via Skill() with artifact propagation between steps.
+Executes commands sequentially via Skill() with session tracking.
 </purpose>
 
 <context>
 $ARGUMENTS — user learning intent text, or flags.
 
 **Flags:**
-- `-y` / `--yes` — Auto mode: skip clarification, skip confirmation
+- `-y` / `--yes` — Auto mode: skip confirmation
 - `--dry-run` — Show planned chain without executing
-- `--chain <name>` — Force a specific chain (bypass intent detection). Valid: `follow`, `investigate`, `decompose`, `second-opinion`, `retro-git`, `retro-decision`, `deep-understand`, `pattern-catalog`, `full-retro`
+- `--chain <name>` — Force a specific chain (bypass intent detection)
 
 **Available learn commands:**
 | Command | Purpose |
@@ -37,8 +32,18 @@ $ARGUMENTS — user learning intent text, or flags.
 | `learn-investigate` | Hypothesis-driven question investigation |
 | `learn-decompose` | 4-dimension parallel pattern extraction |
 | `learn-second-opinion` | Multi-perspective review/challenge/consult |
-| `learn-retro-git` | Git activity retrospective with metrics |
-| `learn-retro-decision` | Decision trace and lifecycle evaluation |
+| `learn-retro` | Unified retrospective (git metrics + decision evaluation) |
+
+**Available chains:**
+| Chain | Steps | Use when |
+|-------|-------|----------|
+| `follow` | learn-follow | Read/understand code or docs |
+| `investigate` | learn-investigate | Answer a "how/why" question |
+| `decompose` | learn-decompose | Catalog patterns in a module |
+| `second-opinion` | learn-second-opinion | Get review/challenge on code |
+| `retro` | learn-retro --lens all | Full retrospective (git + decisions) |
+| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
+| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
 
 **Storage:**
 - `.workflow/learning/.maestro-learn/{session_id}/status.json` — Session tracking
@@ -47,318 +52,89 @@ $ARGUMENTS — user learning intent text, or flags.
 
 <execution>
 
-### Step 1: Parse Arguments & Detect Mode
-
-```javascript
-const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)
-const dryRun = /\b--dry-run\b/.test($ARGUMENTS)
-const forcedChain = $ARGUMENTS.match(/--chain\s+(\S+)/)?.[1] || null
-const intent = $ARGUMENTS
-  .replace(/\b(-y|--yes|--dry-run)\b/g, '')
-  .replace(/--chain\s+\S+/g, '')
-  .trim()
-```
-
-**Display banner:**
-```
-============================================================
-  MAESTRO LEARN COORDINATOR
-============================================================
-  Mode:  {intent-based | forced-chain}
-  Auto:  {yes | no}
-  Input: {intent}
-```
-
----
-
-### Step 2: Analyze Intent
-
-**If `$FORCED_CHAIN` is set:**
-- Validate against known chains: `follow`, `investigate`, `decompose`, `second-opinion`, `retro-git`, `retro-decision`, `deep-understand`, `pattern-catalog`, `full-retro`
-- If valid: skip intent analysis, jump to **Step 4**
-- If invalid: **Error E005** — display valid chains
-
-**Extract structured intent:**
-
-```json
-{
-  "action":  "<from enum>",
-  "target":  "<file path | module | topic | wiki-id | null>",
-  "mode":    "<review | challenge | consult | null>",
-  "scope":   "<path filter | null>",
-  "flags":   "<--depth, --days, --save-wiki, etc.>"
-}
-```
-
-**Action enum:**
-
-| action | Triggered by (semantic) |
-|--------|------------------------|
-| `read` | Read code, follow along, walk through, understand file, 阅读, 跟读 |
-| `question` | Why does X, how does Y work, what happens if, investigate, 为什么, 怎么 |
-| `patterns` | Find patterns, decompose, catalog, extract conventions, 分解, 模式 |
-| `opinion` | Second opinion, review, challenge, critique, consult, 评审, 挑战 |
-| `retro-git` | Git activity, commit history, retro, work sessions, 提交回顾 |
-| `retro-decision` | Decision review, architecture decisions, decision quality, 决策回顾 |
-| `learn` | Generic learn, capture insight, remember — route to best fit |
-
-**Target resolution:**
-- Contains `/` or `\` or file extension → file path
-- Matches `<type>-<slug>` → wiki ID
-- Matches `--days`, `--author` → retro-git flags
-- Matches `--phase`, `--tag`, `--id` → retro-decision flags
-- Otherwise → topic string (passed as quoted argument)
-
----
-
-### Step 3: Route via action → command
-
-```javascript
-const routeMap = {
-  'read':           'follow',
-  'question':       'investigate',
-  'patterns':       'decompose',
-  'opinion':        'second-opinion',
-  'retro-git':      'retro-git',
-  'retro-decision': 'retro-decision',
-  'learn':          null,  // needs disambiguation
-};
-
-function routeLearnIntent(action, target, intent) {
-  // Direct mapping
-  if (routeMap[action]) return routeMap[action];
-
-  // Disambiguate generic 'learn' based on target and context
-  if (target && isFilePath(target))  return 'follow';
-  if (target && isWikiId(target))    return 'follow';
-  if (/retro|commit|git|session/i.test(intent))  return 'retro-git';
-  if (/decision|architect/i.test(intent))         return 'retro-decision';
-  if (/pattern|decompose|catalog/i.test(intent))  return 'decompose';
-  if (/opinion|review|challenge/i.test(intent))   return 'second-opinion';
-  if (/why|how|what if/i.test(intent))            return 'investigate';
-
-  // Fallback: ask user
-  return null;
-}
-```
-
-**Compute clarity score:**
-- 3: `action` recognized + `target` present + specific flags
-- 2: `action` recognized + `target` present
-- 1: `action` recognized but no `target`
-- 0: Cannot determine action
-
-**If clarity < 2 and not autoYes:**
-
-```
-AskUserQuestion:
-  header: "What would you like to learn?"
-  question: |
-    I need a bit more detail. What are you trying to do?
-  options:
-    - "Read through code/docs" → follow
-    - "Investigate a question" → investigate
-    - "Find patterns in code" → decompose
-    - "Get a second opinion" → second-opinion
-    - "Review git activity" → retro-git
-    - "Evaluate decisions" → retro-decision
-    - "Let me rephrase" → re-parse
-```
-
-Max 2 clarification rounds. If still unclear: **Error E002**.
+### Step 1: Parse & Route
 
----
+Parse flags (`-y`, `--dry-run`, `--chain`). Extract intent text.
 
-### Step 4: Select Chain & Confirm
+**If `--chain` specified:** validate against known chains, jump to Step 2.
 
-#### 4a: Map resolved command → chain
+**Intent routing table** (match first token or keywords):
 
-```javascript
-const chainMap = {
-  // Single-step chains
-  'follow':          [{ cmd: 'learn-follow', args: '{target} {flags}' }],
-  'investigate':     [{ cmd: 'learn-investigate', args: '"{target}" {flags}' }],
-  'decompose':       [{ cmd: 'learn-decompose', args: '{target} {flags}' }],
-  'second-opinion':  [{ cmd: 'learn-second-opinion', args: '{target} {flags}' }],
-  'retro-git':       [{ cmd: 'learn-retro-git', args: '{flags}' }],
-  'retro-decision':  [{ cmd: 'learn-retro-decision', args: '{flags}' }],
+| Keywords | Route |
+|----------|-------|
+| File path (contains `/` or `\`) | `follow` |
+| Wiki ID (`type-slug` pattern) | `follow` |
+| read, follow, walk through, understand, 阅读, 跟读 | `follow` |
+| why, how, what if, investigate, 为什么, 怎么 | `investigate` |
+| pattern, decompose, catalog, 分解, 模式 | `decompose` |
+| opinion, review, challenge, consult, 评审, 挑战 | `second-opinion` |
+| retro, git, commit, decision, 回顾 | `retro` |
+| thorough, deep, 全面, 深入 | `deep-understand` |
 
-  // Multi-step chains
-  'deep-understand': [
-    { cmd: 'learn-follow', args: '{target} --depth deep' },
-    { cmd: 'learn-decompose', args: '{target} --save-spec' },
-    { cmd: 'learn-second-opinion', args: '{target} --mode challenge' }
-  ],
-  'pattern-catalog': [
-    { cmd: 'learn-decompose', args: '{target} --save-spec --save-wiki' },
-    { cmd: 'learn-second-opinion', args: '{target} --mode review' }
-  ],
-  'full-retro': [
-    { cmd: 'learn-retro-git', args: '{flags}' },
-    { cmd: 'learn-retro-decision', args: '{flags}' }
-  ]
-};
+**If no match:** present menu via AskUserQuestion:
 ```
-
-**Chain upgrade heuristic** — single commands may upgrade to multi-step chains when context warrants it:
-- `follow` on a large module (>500 LOC) → suggest `deep-understand`
-- `decompose` with `--save-spec --save-wiki` → already a full catalog, no upgrade
-- User explicitly mentions "thorough" or "deep" or "全面" → upgrade to multi-step
-
-#### 4b: Assemble arguments
-
-- Replace `{target}` with resolved target path/topic/wiki-id
-- Replace `{flags}` with extracted flags (--depth, --days, --mode, --scope, etc.)
-- Clean empty placeholders
-
-#### 4c: Confirm (skip if autoYes)
-
-**If `$DRY_RUN`:**
+What would you like to do?
+1. Read through code/docs → follow
+2. Investigate a question → investigate
+3. Find patterns in code → decompose
+4. Get a second opinion → second-opinion
+5. Retrospective → retro
 ```
-============================================================
-  MAESTRO LEARN: {chain_name} (dry run)
-============================================================
-  Intent: {original_intent}
-  Target: {resolved_target}
 
-  Pipeline:
-    1. [{command}] args: {assembled_args}
-    ...
+Max 1 clarification round. If still unclear: error.
 
-  (Use without --dry-run to execute)
-============================================================
-```
-Exit after display.
+### Step 2: Resolve Target & Build Args
 
-**If not autoYes:**
-```
-AskUserQuestion:
-  header: "Confirm: {chain_name}"
-  question: |
-    Execute this learning chain?
-
-    Pipeline:
-      1. {command} — {description}
-      ...
+- File path → pass directly
+- Wiki ID → pass directly
+- Topic string → pass as quoted argument
+- Extract any flags (--depth, --days, --lens, --mode, --scope, etc.)
 
-  options:
-    - "Execute" → proceed
-    - "Cancel" → exit
+**Chain → command mapping:**
 ```
-
----
-
-### Step 5: Setup Tracking
-
-```bash
-SESSION_ID="learn-$(date +%Y%m%d-%H%M%S)"
-SESSION_DIR=".workflow/learning/.maestro-learn/${SESSION_ID}"
-mkdir -p "${SESSION_DIR}"
+follow          → Skill("learn-follow", "{target} {flags}")
+investigate     → Skill("learn-investigate", "\"{target}\" {flags}")
+decompose       → Skill("learn-decompose", "{target} {flags}")
+second-opinion  → Skill("learn-second-opinion", "{target} {flags}")
+retro           → Skill("learn-retro", "{flags}")
+deep-understand → [learn-follow --depth deep, learn-decompose --save-spec, learn-second-opinion --mode challenge]
+pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opinion --mode review]
 ```
 
-Write `${SESSION_DIR}/status.json`:
-```json
-{
-  "session_id": "{SESSION_ID}",
-  "created_at": "{ISO timestamp}",
-  "intent": "{original_intent}",
-  "chain": "{chain_name}",
-  "steps": [
-    { "index": 0, "cmd": "{command}", "args": "{args}", "status": "pending" }
-  ],
-  "current_step": 0,
-  "auto_mode": false
-}
-```
+### Step 3: Confirm & Execute
 
----
-
-### Step 6: Execute Chain
-
-For each step in the chain (starting from `$STEP_INDEX` or 0):
-
-1. Update `status.json`: set step status to `"running"`
-2. Display step header:
-   ```
-   ── Step {N}/{total}: {command} ──────────────────────────
-   ```
-3. Execute: `Skill({ skill: "{command}", args: "{assembled_args}" })`
-4. On success:
-   - Update step status to `"completed"`
-   - Record duration
-   - Continue to next step
-5. On failure:
-   - Update step status to `"failed"`, record error
-   - **If autoYes**: skip and continue (log warning)
-   - **If interactive**:
-     ```
-     AskUserQuestion:
-       header: "Step {N} failed"
-       question: "{error summary}"
-       options:
-         - "Retry" → re-execute same step
-         - "Skip" → continue to next step
-         - "Abort" → exit chain
-     ```
-
----
-
-### Step 7: Session Summary
-
-After all steps complete (or chain aborted):
-
-```
-=== MAESTRO LEARN SESSION COMPLETE ===
-Session: {session_id}
-Chain:   {chain_name} ({steps_completed}/{steps_total} steps)
-Mode:    {auto | interactive}
-
-Steps:
-  [{status_icon}] {N}. {command_name} — {duration}
-
-Artifacts:
-  - {list of files written to .workflow/learning/}
-
-Next:
-  {suggested_next_action based on chain type}
-```
+**If `--dry-run`:** display chain plan and exit.
 
-**Next-step routing by chain type:**
+**If not `-y`:** show plan, ask for confirmation.
 
-| Chain | Suggested next |
-|-------|---------------|
-| `follow` | "Decompose patterns? → `/maestro-learn --chain decompose`" |
-| `investigate` | "Follow-along on discovered code? → `/maestro-learn follow <path>`" |
-| `decompose` | "Get second opinion? → `/maestro-learn --chain second-opinion`" |
-| `second-opinion` | "Create issue for findings? → `/manage-issue create`" |
-| `retro-git` | "Deep dive on hotspot? → `/maestro-learn follow <path>`" |
-| `retro-decision` | "Investigate stale decision? → `/maestro-learn investigate <question>`" |
-| `deep-understand` | "Browse insights → `/manage-learn list`" |
-| `pattern-catalog` | "Load specs → `/spec-load`" |
-| `full-retro` | "Browse all insights → `/manage-learn list --tag retro`" |
+**Execute:**
+1. Create session dir: `.workflow/learning/.maestro-learn/learn-{timestamp}/`
+2. Write `status.json` with chain steps
+3. Execute each step via `Skill()`:
+   - On success: mark completed, continue
+   - On failure (interactive): ask retry/skip/abort
+   - On failure (auto): skip and continue
+4. Display session summary with artifact list and next-step suggestion
 
 </execution>
 
 <error_codes>
 | Code | Severity | Description | Recovery |
 |------|----------|-------------|----------|
-| E001 | error | No intent provided and no learning context | Provide a learning goal or target |
-| E002 | error | Clarity too low after 2 clarification rounds | Show parsed intent, ask user to rephrase |
-| E003 | error | Chain step failed + user chose abort | Record partial progress in status.json |
-| E005 | error | Invalid chain name provided with --chain | Show valid chain names: follow, investigate, decompose, second-opinion, retro-git, retro-decision, deep-understand, pattern-catalog, full-retro |
-| W001 | warning | Intent ambiguous between two commands | Present options, let user choose |
+| E001 | error | No intent provided | Provide a learning goal or use --chain |
+| E002 | error | Cannot determine intent after clarification | Rephrase or use --chain directly |
+| E003 | error | Chain step failed + user chose abort | Partial progress saved in status.json |
+| E005 | error | Invalid --chain name | Show valid chains |
+| W001 | warning | Intent ambiguous between commands | Present options |
 | W002 | warning | Chain step completed with warnings | Log and continue |
-| W003 | warning | `.workflow/learning/` not found | Auto-create and proceed |
 </error_codes>
 
 <success_criteria>
-- [ ] Intent classified with action, target, clarity_score
-- [ ] Command/chain selected and confirmed (or auto-confirmed with -y)
-- [ ] Session directory created at `.workflow/learning/.maestro-learn/{session_id}/`
-- [ ] status.json tracks per-step progress
-- [ ] All chain steps executed via Skill() with proper argument propagation
-- [ ] Target resolved (file path, wiki-id, topic) and passed to downstream commands
-- [ ] Error handling: retry/skip/abort per step (auto-skip in -y mode)
-- [ ] Session summary displayed on completion with next-step routing
+- [ ] Intent routed to correct chain (or --chain validated)
+- [ ] Target resolved and arguments assembled
+- [ ] Session directory created with status.json
+- [ ] All chain steps executed via Skill()
+- [ ] Error handling: retry/skip/abort per step
+- [ ] Session summary displayed with next-step routing
 - [ ] No files modified outside `.workflow/learning/`
 </success_criteria>

package/.claude/commands/manage-learn.md

@@ -1,7 +1,7 @@
 ---
 name: manage-learn
-description: Capture, search, and review atomic learning insights into .workflow/learning/lessons.jsonl
-argument-hint: "[<text>|list|search|show <id>] [--category ...] [--tag t1,t2] [--phase N] [--confidence ...]"
+description: Capture, search, and review atomic learning insights and tips into .workflow/learning/lessons.jsonl
+argument-hint: "[<text>|tip <text>|list|search|show <id>] [--category ...] [--tag t1,t2] [--phase N] [--confidence ...]"
 allowed-tools:
   - Read
   - Write
@@ -12,7 +12,11 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Atomic insight capture for the workflow learning library. Lightweight gstack-style "eureka moment" log that complements `quality-retrospective`: where retrospective extracts insights from a completed phase in bulk, `manage-learn` captures one timeless insight at a time during active work. Insights are appended to `.workflow/learning/lessons.jsonl` with auto-detected phase linkage and a simple keyword-based category inference. Same store as retrospective output, so search and list see both manual captures and retrospective-distilled insights.
+Unified atomic knowledge capture for the workflow learning library. Captures two types of knowledge:
+- **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode
+- **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-memory-capture tip`)
+
+Both types are stored in `.workflow/learning/lessons.jsonl` with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
 </purpose>
 
 <required_reading>
@@ -23,30 +27,31 @@ Atomic insight capture for the workflow learning library. Lightweight gstack-sty
 Arguments: $ARGUMENTS
 
 **Modes (auto-detected from first token):**
-- `"<insight text>"` (or any non-keyword text) → capture mode
-- `list` → list recent insights (default 20)
+- `"<insight text>"` (or any non-keyword text) → insight capture mode
+- `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
+- `list` → list recent entries (default 20)
 - `search <query>` → text search across lessons.jsonl
-- `show <INS-id>` → full insight detail with phase context
-- empty → AskUserQuestion to prompt for insight text
+- `show <INS-id>` → full detail with phase context
+- empty → AskUserQuestion to prompt for text
 
-**Capture flags:**
-- `--category <name>` — pattern | antipattern | decision | tool | gotcha | technique. Default: inferred from text via keyword heuristics.
-- `--tag t1,t2` — comma-separated tags. Always implicitly adds `manual`.
+**Capture flags (both insight and tip modes):**
+- `--category <name>` — pattern | antipattern | decision | tool | gotcha | technique | tip. Default: inferred from text via keyword heuristics. Tip mode defaults to `tip`.
+- `--tag t1,t2` — comma-separated tags. Insight mode implicitly adds `manual`, tip mode implicitly adds `tip`.
 - `--phase <N>` — override auto-detected current phase. Use `--phase 0` to force "no phase".
-- `--confidence <level>` — high | medium | low. Default: medium.
+- `--confidence <level>` — high | medium | low. Default: medium (insight), low (tip).
 
 **List/search flags:**
 - `--tag t1,t2` — filter by tag
 - `--category <name>` — filter by category
 - `--phase <N>` — filter by phase
-- `--lens <name>` — filter by retrospective lens (technical | process | quality | decision)
+- `--lens <name>` — filter by retrospective lens (technical | process | quality | decision | git). Note: `git` matches `source: "retro-git"` from learn-retro; others match `lens` field from quality-retrospective.
 - `--limit <N>` — list mode row limit (default 20)
 
 **Storage:**
 - `.workflow/learning/lessons.jsonl` — append-only JSONL row per insight (shared with `quality-retrospective` output)
 - `.workflow/learning/learning-index.json` — searchable index (mirrors `memory-index.json` schema)
 
-**Shared store rationale:** Manual captures (`source: "manual"`, `lens: null`) and retrospective-distilled insights (`source: "retrospective"`, `lens: <name>`) live side by side so search and list see the entire knowledge corpus. The `source` and `lens` fields disambiguate.
+**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.
 </context>
 
 <execution>
@@ -55,16 +60,17 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. Key invariants:
 1. **No agent or CLI calls** — this is a pure file operation: parse → infer → append → confirm. Category inference is keyword-based, not LLM-based.
 2. **Auto-link phase** — read `.workflow/state.json` for `current_phase` and resolve the matching directory slug. `--phase 0` forces no link.
 3. **Match memory-index pattern** — `learning-index.json` schema mirrors `memory-index.json` from `workflows/memory.md` (entries[] with id, type, timestamp, file, summary, tags, plus learn-specific fields: lens, category, phase, phase_slug, confidence, routed_to, routed_id).
-4. **Stable INS ids** — `INS-{8 lowercase hex}` from `hash(insight_text + timestamp)`.
+4. **Stable INS ids** — `INS-{8 lowercase hex}` from `hash(insight_text + category + phase)`. Deterministic: same content in same context always produces the same ID.
 5. **Append-only lessons.jsonl** — never rewrite existing rows; duplicate detection is the user's job at search time.
 6. **Bootstrap on demand** — create `.workflow/learning/`, `lessons.jsonl`, `learning-index.json` on first use; do not require them to exist upfront.
+7. **Tip mode** — when first token is `tip`, set `source: "tip"`, `category: "tip"`, `confidence: "low"`, and implicitly add `tip` tag. Everything else follows the same pipeline as insight capture. This replaces the former `manage-memory-capture tip` mode.
 </execution>
 
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
 | E001 | error | `.workflow/` not initialized — run `Skill({ skill: "maestro-init" })` first | parse_input |
-| E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique) | parse_input |
+| E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
 | E003 | error | `show` mode requires an INS-id argument | show |
 | E004 | error | Insight id not found in lessons.jsonl | show |
 | W001 | warning | Auto-phase detection found a current_phase but no matching directory; phase set to null | capture |

package/.claude/commands/manage-memory-capture.md

@@ -1,7 +1,7 @@
 ---
 name: manage-memory-capture
-description: Capture session memory (compact or tips) into .workflow/memory/ with JSON index
-argument-hint: "[compact|tip] [description] [--tag tag1,tag2]"
+description: Capture session memory (compact mode) into .workflow/memory/ with JSON index
+argument-hint: "[compact] [description]"
 allowed-tools:
   - Read
   - Write
@@ -12,7 +12,9 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Capture session working memory into `.workflow/memory/` for cross-session recovery. Supports two modes: compact (full session compression for recovery) and tip (quick note-taking with tags). Maintains a `memory-index.json` for search and retrieval. Invoked when saving session state before context loss or recording insights during work.
+Capture session working memory into `.workflow/memory/` for cross-session recovery. Compact mode only: full session compression for recovery. Maintains a `memory-index.json` for search and retrieval. Invoked when saving session state before context loss.
+
+**Note:** Quick tips/notes have been moved to `manage-learn tip <text>`. Use that command for atomic knowledge capture.
 </purpose>
 
 <required_reading>
@@ -22,13 +24,9 @@ Capture session working memory into `.workflow/memory/` for cross-session recove
 <context>
 Arguments: $ARGUMENTS
 
-**Modes:**
+**Mode:**
 - `compact` — Full session memory compression (files, decisions, plan state, pending work)
-- `tip` — Quick note with optional tags and context
-- No arguments — Auto-detect or ask user
-
-**Flags:**
-- `--tag tag1,tag2` — Categorization tags (tip mode)
+- No arguments — Defaults to compact mode
 
 **Storage:**
 - `.workflow/memory/` — Memory entries directory
@@ -43,19 +41,19 @@ Follow '~/.maestro/workflows/memory.md' Part B (Memory Capture) completely.
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
 | E001 | error | `.workflow/` not initialized — run Skill({ skill: "maestro-init" }) first | parse_input |
-| E002 | error | Empty note content in tip mode — provide text to save | parse_input |
+| E002 | error | Tip mode removed — use `Skill({ skill: "manage-learn", args: "tip <text>" })` instead | parse_input |
 | W001 | warning | No active workflow session found — compact will capture conversation only | analyze_session |
 | W002 | warning | Plan detection found no explicit plan — using inferred plan | analyze_session |
 </error_codes>
 
 <success_criteria>
-- [ ] Mode correctly detected (compact or tip)
+- [ ] Compact mode executed
 - [ ] Entry markdown file written to `.workflow/memory/`
 - [ ] `memory-index.json` updated with new entry metadata
-- [ ] Compact: all session fields populated (objective, files, decisions, plan)
-- [ ] Compact: execution plan preserved VERBATIM (not summarized)
-- [ ] Compact: all file paths are ABSOLUTE
-- [ ] Tip: content, tags, and context captured
+- [ ] All session fields populated (objective, files, decisions, plan)
+- [ ] Execution plan preserved VERBATIM (not summarized)
+- [ ] All file paths are ABSOLUTE
 - [ ] Confirmation banner displayed with entry ID
 - [ ] Next step: Skill({ skill: "manage-status" }) to resume workflow, or Skill({ skill: "manage-memory", args: "view <entry_id>" }) to verify captured memory
+- [ ] For tips: redirect user to `Skill({ skill: "manage-learn", args: "tip <text>" })`
 </success_criteria>

package/.claude/commands/manage-memory.md

@@ -30,7 +30,7 @@ Arguments: $ARGUMENTS
 
 | Store | Path | Format | Index |
 |-------|------|--------|-------|
-| `workflow` | `.workflow/memory/` | `MEM-*.md`, `TIP-*.md` | `memory-index.json` |
+| `workflow` | `.workflow/memory/` | `MEM-*.md`, `TIP-*.md` (legacy only — new tips go to `manage-learn tip`) | `memory-index.json` |
 | `system` | `~/.claude/projects/{project}/memory/` | `MEMORY.md` + topic `.md` files | None (flat files) |
 
 **System memory path detection:**

package/.claude/commands/quality-retrospective.md

@@ -22,7 +22,7 @@ Post-execution multi-perspective retrospective (复盘) for completed phases. Co
 
 <deferred_reading>
 - @~/.maestro/workflows/issue.md (issues.jsonl schema for auto-creation)
-- @~/.maestro/workflows/memory.md (Part B for note routing via manage-memory-capture)
+- @~/.maestro/workflows/learn.md (tip routing via manage-learn tip)
 - @~/.maestro/workflows/verify.md (verification.json schema for quality lens parsing)
 - @~/.maestro/workflows/review.md (review.json schema for quality lens parsing)
 </deferred_reading>
@@ -47,7 +47,7 @@ Arguments: $ARGUMENTS
 - `.workflow/phases/{NN}-{slug}/retrospective.json` — structured record
 - `.workflow/specs/SPEC-retro-*.md` — spec stubs (one per spec-routed insight)
 - `.workflow/issues/issues.jsonl` — appended issue rows (`source: "retrospective"`)
-- `.workflow/memory/TIP-*.md` — memory tips (via `manage-memory-capture` skill)
+- `.workflow/learning/lessons.jsonl` — tips routed via `manage-learn tip` (formerly manage-memory-capture)
 - `.workflow/learning/lessons.jsonl` — append-only insight log
 - `.workflow/learning/learning-index.json` — searchable index
 
@@ -64,7 +64,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 1. **Read-only until Stage 6** — Stages 1–5 must not write anything except the in-memory retrospective record.
 2. **Parallel lens dispatch** — Stage 4 spawns one Agent per active lens in a single message (multiple Agent tool calls). All agents use `subagent_type: "general-purpose"` and `run_in_background: false`.
 3. **Match canonical issues schema** — Stage 6 issue routing must produce rows that pass `jq` parsing and match the schema in `workflows/issue.md` Step 4 exactly (status `"open"`, full `issue_history` entry, all required fields).
-4. **Reuse `manage-memory-capture` for note routing** — do not duplicate the memory pipeline; invoke via `Skill()`.
+4. **Reuse `manage-learn tip` for note routing** — do not duplicate the learning pipeline; invoke via `Skill({ skill: "manage-learn", args: "tip ..." })`.
 5. **Backward-compat with phase-transition** — append a one-line summary per insight to `.workflow/specs/learnings.md` if and only if that file already exists. Never create it.
 6. **Stable insight IDs** — `INS-{8 hex}` from `hash(phase_num + lens + title)` so re-runs do not duplicate.
 7. **Archive before overwrite** — if existing `retrospective.{md,json}` are being replaced, move them to `{phase_dir}/.history/` with a timestamp suffix first.
@@ -80,7 +80,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 | E005 | error | Phase argument out of range / phase directory not found | scan_unreviewed |
 | W001 | warning | One or more lens agents failed — proceeding with partial coverage | multi_lens_analysis |
 | W002 | warning | Existing retrospective.json found and not `--all` — prompted user to overwrite | scan_unreviewed |
-| W003 | warning | `manage-memory-capture` did not return parseable TIP id; fell back to direct write | route_outputs |
+| W003 | warning | `manage-learn tip` did not return parseable INS id; fell back to direct write | route_outputs |
 | W004 | warning | `--compare` target phase has no retrospective.json; delta omitted | load_artifacts |
 </error_codes>
 
@@ -94,7 +94,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
 - [ ] Spec stubs (if any) written to `.workflow/specs/SPEC-retro-*.md` with proper frontmatter
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
-- [ ] Note tips (if any) created via `Skill({ skill: "manage-memory-capture", args: "tip ..." })`
+- [ ] Note tips (if any) created via `Skill({ skill: "manage-learn", args: "tip ..." })`
 - [ ] `lessons.jsonl` appended with one row per insight regardless of routing target
 - [ ] `learning-index.json` updated and parseable
 - [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)