maestro-flow 0.5.35 → 0.5.37

package/.codex/skills/maestro-overlay/SKILL.md

@@ -1,119 +1,119 @@
----
-name: maestro-overlay
-description: Create or edit command overlays from natural language
-argument-hint: "<intent> | --list | --remove <name>"
-allowed-tools: Read, Write, Bash, Glob, Grep
----
-
-<purpose>
-4-step pipeline: parse intent → identify targets + injection points → draft overlay JSON → install via CLI and report. Overlays are JSON patch files that augment `.claude/commands/*.md` non-invasively. They survive reinstalls because `maestro install` auto-reapplies them. Each overlay is idempotent: the patcher wraps content in hashed HTML-comment markers, so re-running `maestro overlay apply` produces no file changes.
-
-```
-Parse Intent  →  Identify Targets  →  Draft JSON  →  Install + Report
-(or --list /      (read command        (apply_patch    (exec_command +
-  --remove)         XML sections)       to overlays/)    banner)
-```
-
-**Available injection sections**: `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`
-
-**Patch modes**: `append`, `prepend`, `replace`, `new-section`
-</purpose>
-
-<context>
-
-```bash
-$maestro-overlay "always run CLI verification after maestro-execute"
-$maestro-overlay "require reading doc X before maestro-plan"
-$maestro-overlay "--list"
-$maestro-overlay "--remove cli-verify-after-execute"
-```
-
-**Flags**:
-- `<intent>` — Natural-language description of what to inject and where
-- `--list` — Show installed overlays and their applied state
-- `--remove <name>` — Strip overlay from targets and delete its file
-
-**Overlay storage**:
-- User overlays: `~/.maestro/overlays/*.json`
-- Shared docs: `~/.maestro/overlays/docs/*.md`
-- Shipped examples: `~/.maestro/overlays/_shipped/` (read-only)
-
-</context>
-
-<invariants>
-1. **Quick-exit first**: `--list` and `--remove` skip all intent parsing
-2. **Pristine source preferred**: Always read `.claude/commands/<name>.md` for the untouched command spec before deciding injection point
-3. **Idempotent content**: Injected blocks use hashed comment markers — re-runs produce no changes
-4. **Heading required**: Every injected block must start with a `## <Title> (overlay)` heading
-5. **Validate before report**: Run `maestro overlay add` successfully before displaying the report banner
-6. **Max 2 clarification questions**: If intent is ambiguous, ask at most 2 focused questions then proceed with best guess
-</invariants>
-
-<execution>
-
-### Step 1: Parse User Intent
-
-**Quick-exit paths**:
-- `--list` → run `maestro overlay list`, then stop
-- `--remove <name>` → run `maestro overlay remove <name>`, then stop
-
-**Ambiguous intent**: If target command or injection point unclear, ask up to 2 focused questions.
-
-### Step 2: Identify Targets and Injection Points
-
-Read pristine command source from `$PKG_ROOT/.claude/commands/<name>.md` (fallback: `~/.claude/commands/<name>.md`). Select injection point:
-
-| Intent type | Section | Mode |
-|-------------|---------|------|
-| New step after execution | `execution` | `append` |
-| Required reading / prerequisite | `required_reading` | `append` |
-| Preconditions / gating | `context` | `append` |
-| Output quality gate | `success_criteria` | `append` |
-| Brand-new section | `execution` | `new-section` (with `afterSection`) |
-
-### Step 3: Draft Overlay JSON
-
-Build slug from intent (kebab-case, lowercase, max 40 chars). Write overlay to `~/.maestro/overlays/<slug>.json`:
-
-```json
-{
-  "name": "<slug>",
-  "description": "<short summary>",
-  "targets": ["<command-name>"],
-  "priority": 50,
-  "enabled": true,
-  "patches": [{
-    "section": "<section>",
-    "mode": "<append|prepend|replace|new-section>",
-    "content": "<injected markdown with (overlay) heading>"
-  }]
-}
-```
-
-**Content guidelines**: Lead with `## Title (overlay)` heading. Use `@~/.maestro/...` references. Keep concise.
-
-### Step 4: Install via CLI and Report
-
-Run `maestro overlay add ~/.maestro/overlays/<slug>.json`. On validation failure, fix JSON and retry (max 2).
-
-Display report with name, path, targets (applied/skipped), and commands for re-apply/remove/inspect.
-
-</execution>
-
-<error_codes>
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | `maestro overlay add` validation failed | Fix JSON syntax or section name, retry |
-| E002 | error | No targets found (all commands missing) | Check command name spelling |
-| E003 | error | `--remove` target not found in overlay store | Run `--list` to see installed overlays |
-| W001 | warning | One or more targets skipped (command missing from install) | Overlay still installed; applies when command is added |
-
-</error_codes>
-
-<success_criteria>
-- [ ] Intent parsed and targets identified
-- [ ] Overlay JSON drafted with correct section and mode
-- [ ] `maestro overlay add` executed successfully
-- [ ] Report displayed with apply/remove/inspect commands
-</success_criteria>
+---
+name: maestro-overlay
+description: Create or edit command overlays from natural language
+argument-hint: "<intent> | --list | --remove <name>"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+<purpose>
+4-step pipeline: parse intent → identify targets + injection points → draft overlay JSON → install via CLI and report. Overlays are JSON patch files that augment `.claude/commands/*.md` non-invasively. They survive reinstalls because `maestro install` auto-reapplies them. Each overlay is idempotent: the patcher wraps content in hashed HTML-comment markers, so re-running `maestro overlay apply` produces no file changes.
+
+```
+Parse Intent  →  Identify Targets  →  Draft JSON  →  Install + Report
+(or --list /      (read command        (apply_patch    (exec_command +
+  --remove)         XML sections)       to overlays/)    banner)
+```
+
+**Available injection sections**: `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`
+
+**Patch modes**: `append`, `prepend`, `replace`, `new-section`
+</purpose>
+
+<context>
+
+```bash
+$maestro-overlay "always run CLI verification after maestro-execute"
+$maestro-overlay "require reading doc X before maestro-plan"
+$maestro-overlay "--list"
+$maestro-overlay "--remove cli-verify-after-execute"
+```
+
+**Flags**:
+- `<intent>` — Natural-language description of what to inject and where
+- `--list` — Show installed overlays and their applied state
+- `--remove <name>` — Strip overlay from targets and delete its file
+
+**Overlay storage**:
+- User overlays: `~/.maestro/overlays/*.json`
+- Shared docs: `~/.maestro/overlays/docs/*.md`
+- Shipped examples: `~/.maestro/overlays/_shipped/` (read-only)
+
+</context>
+
+<invariants>
+1. **Quick-exit first**: `--list` and `--remove` skip all intent parsing
+2. **Pristine source preferred**: Always read `.claude/commands/<name>.md` for the untouched command spec before deciding injection point
+3. **Idempotent content**: Injected blocks use hashed comment markers — re-runs produce no changes
+4. **Heading required**: Every injected block must start with a `## <Title> (overlay)` heading
+5. **Validate before report**: Run `maestro overlay add` successfully before displaying the report banner
+6. **Max 2 clarification questions**: If intent is ambiguous, ask at most 2 focused questions then proceed with best guess
+</invariants>
+
+<execution>
+
+### Step 1: Parse User Intent
+
+**Quick-exit paths**:
+- `--list` → run `maestro overlay list`, then stop
+- `--remove <name>` → run `maestro overlay remove <name>`, then stop
+
+**Ambiguous intent**: If target command or injection point unclear, ask up to 2 focused questions.
+
+### Step 2: Identify Targets and Injection Points
+
+Read pristine command source from `$PKG_ROOT/.claude/commands/<name>.md` (fallback: `~/.claude/commands/<name>.md`). Select injection point:
+
+| Intent type | Section | Mode |
+|-------------|---------|------|
+| New step after execution | `execution` | `append` |
+| Required reading / prerequisite | `required_reading` | `append` |
+| Preconditions / gating | `context` | `append` |
+| Output quality gate | `success_criteria` | `append` |
+| Brand-new section | `execution` | `new-section` (with `afterSection`) |
+
+### Step 3: Draft Overlay JSON
+
+Build slug from intent (kebab-case, lowercase, max 40 chars). Write overlay to `~/.maestro/overlays/<slug>.json`:
+
+```json
+{
+  "name": "<slug>",
+  "description": "<short summary>",
+  "targets": ["<command-name>"],
+  "priority": 50,
+  "enabled": true,
+  "patches": [{
+    "section": "<section>",
+    "mode": "<append|prepend|replace|new-section>",
+    "content": "<injected markdown with (overlay) heading>"
+  }]
+}
+```
+
+**Content guidelines**: Lead with `## Title (overlay)` heading. Use `@~/.maestro/...` references. Keep concise.
+
+### Step 4: Install via CLI and Report
+
+Run `maestro overlay add ~/.maestro/overlays/<slug>.json`. On validation failure, fix JSON and retry (max 2).
+
+Display report with name, path, targets (applied/skipped), and commands for re-apply/remove/inspect.
+
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | `maestro overlay add` validation failed | Fix JSON syntax or section name, retry |
+| E002 | error | No targets found (all commands missing) | Check command name spelling |
+| E003 | error | `--remove` target not found in overlay store | Run `--list` to see installed overlays |
+| W001 | warning | One or more targets skipped (command missing from install) | Overlay still installed; applies when command is added |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Intent parsed and targets identified
+- [ ] Overlay JSON drafted with correct section and mode
+- [ ] `maestro overlay add` executed successfully
+- [ ] Report displayed with apply/remove/inspect commands
+</success_criteria>

package/.codex/skills/maestro-plan/SKILL.md

@@ -88,7 +88,7 @@ Write resolved milestone into PLN artifact registration and `plan.json.milestone
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-plan-P{N}-{slug}/`
 **Scratch**: `.workflow/scratch/{YYYYMMDD}-plan-P{N}-{slug}/` (.task/ subdir)
 
-**Pre-load** (optional): context-package.json (via `--from`, takes precedence), context.md (prior analyze), conclusions.json, codebase ARCHITECTURE.md, `maestro search`, `maestro spec load --category arch`, team preflight `maestro collab preflight`.
+**Pre-load** (optional): context-package.json (via `--from`, takes precedence), context.md (prior analyze), conclusions.json, codebase ARCHITECTURE.md, `maestro search`, `maestro load --type spec --category arch`, team preflight `maestro collab preflight`.
 
 **D-008 Ad-hoc Milestone Auto-Creation**: When scope resolves to `standalone` via standard resolution (routes 6 or 7, NOT via `--from`), and `state.json.current_milestone == null`, auto-create an adhoc milestone:
 ```
@@ -153,8 +153,13 @@ S_WAVE_1 → S_WAVE_2    DO: spawn parallel explorations, merge results, build p
 
 S_WAVE_2 → S_CHECK     DO: spawn planning agent, merge results
 
-S_CHECK → S_CONFIRM    WHEN: plan passes or max 3 iterations    DO: A_PLAN_CHECK
-S_CHECK → S_WAVE_2     WHEN: plan fails check, iterations < 3   DO: feed checker feedback back
+S_CHECK → S_BOUNDARY_GRILL  WHEN: plan passes or max 3 iterations    DO: A_PLAN_CHECK
+S_CHECK → S_WAVE_2         WHEN: plan fails check, iterations < 3   DO: feed checker feedback back
+
+S_BOUNDARY_GRILL:
+  → S_CONFIRM    WHEN: no boundary conflicts detected     DO: —
+  → S_CONFIRM    WHEN: conflicts detected + resolved      DO: A_BOUNDARY_GRILL
+  GUARD: max 3 conflicts × 3 questions; non-blocking (see boundary-grill.md)
 
 S_CONFIRM → S_REGISTER WHEN: -y OR user confirms
 S_CONFIRM → S_CSV_GEN  WHEN: user wants to modify
@@ -224,6 +229,13 @@ Consumes all exploration findings + context.md + specs. Produces:
 
 Verifies plan.json and every .task/*.json exists on disk before reporting completed; else report blocked.
 
+### A_BOUNDARY_GRILL
+
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after plan-checker pass.
+Input: plan.json tasks + convergence criteria + upstream context. Scope guard: "only plan scope; do not re-analyze or re-scope".
+IF conflicts → results to plan.json `boundary_grill` section + affected TASK files. DEC conflicts add `boundary_warning` to confidence.
+Non-blocking: warnings, not hard stops.
+
 ### A_PLAN_CHECK
 Run plan-checker: coverage, dependency validity, criteria quality, pressure pass on highest-complexity task.
 Confidence: 5-dimension factor model + readiness gate.
@@ -263,6 +275,9 @@ Collision detection against same-milestone plans.
 - [ ] .task/TASK-*.json with read_first[] (file being modified + source of truth files)
 - [ ] Every task has convergence.criteria[] with grep-verifiable conditions (no subjective language)
 - [ ] Every task action and implementation contain concrete values (no "align X with Y")
+- [ ] Boundary grill executed after plan-checker pass (skip if no conflicts detected)
+- [ ] Boundary grill results written to plan.json `boundary_grill` section (if conflicts found)
+- [ ] DEC conflicts reflected in confidence `boundary_warning` factor
 - [ ] Plan confidence scored with 5-dimension factor model
 - [ ] Readiness gate checked before collision detection
 - [ ] Pressure pass completed on highest-complexity task

package/.codex/skills/maestro-quick/SKILL.md

@@ -51,7 +51,7 @@ Extract from arguments:
 
 Read `.workflow/state.json` and `.workflow/project.md` if they exist. If `.workflow/` does not exist, create minimal scratch structure anyway (quick works without full init).
 
-Load coding specs + tools if available: `maestro spec load --category coding`. If the task involves frontend/UI work (description contains component, page, style, layout, CSS, HTML, frontend), also run `maestro spec load --category ui`. Browse wiki: `maestro search --category coding`, load relevant entries via `maestro wiki load <id>`. All optional — proceed without if unavailable.
+Load coding specs + tools if available: `maestro load --type spec --category coding`. If the task involves frontend/UI work (description contains component, page, style, layout, CSS, HTML, frontend), also run `maestro load --type spec --category ui`. Browse wiki: `maestro search --category coding`, load relevant entries via `maestro load --type knowhow --id <id>`. All optional — proceed without if unavailable.
 
 ### Step 3: Create Scratch Directory
 
@@ -70,7 +70,7 @@ Analyze the task for gray areas and ambiguities:
 ### Step 5: Quick Analysis
 
 Rapid codebase exploration focused on the task:
-1. Search for related files using Grep/Glob
+1. Search for related files using `maestro explore` (preferred, fallback Grep/Glob)
 2. Identify existing patterns to follow
 3. Map dependencies and integration points
 4. Write analysis findings to `context.md` (append if --discuss created it)

package/.codex/skills/maestro-ralph/SKILL.md

@@ -294,7 +294,8 @@ resolve_milestone(phase_number):
 |-----------|----------|
 | review.json: verdict=="BLOCK" | `review-failed` |
 | review.json: verdict!="BLOCK" | `test` |
-| uat.md: all passed | `milestone-audit` |
+| uat.md: all passed + `session.milestone` 存在 | `milestone-audit` |
+| uat.md: all passed + `session.milestone=null` (standalone) | 标记 session completed（无 milestone 可审计） |
 | uat.md: has failures | `test-failed` |
 
 ### A_DETERMINE_QUALITY_MODE
@@ -376,7 +377,7 @@ narrow → derive defaults from intent + codebase, skip questions.
 
 ### A_BUILD_STEPS
 
-Generate steps from `session.lifecycle_position` to `milestone-complete`.
+Generate steps from `session.lifecycle_position` to `milestone-complete`（`session.milestone` 存在时）或最后一个质量门（standalone 时）。
 
 | Stage | Skill (independent) | Skill (unified) | Decision after | quality_mode |
 |-------|---------------------|-----------------|----------------|--------------|
@@ -408,7 +409,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 3.5. **grill auto_confirm 跳过**：`auto_confirm == true` 时删除 `grill` stage（grill 为交互式苏格拉底拷问，不支持自动模式）；brainstorm args 不含 `--from grill:*`
 4. **决策节点**：每个 Decision after 非空的 stage 之后插入 `{ decision: "<gate>", retry_count: 0, max_retries: 2, command_scope: null, command_path: null }`
 5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（verify/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
-6. **终点硬约束**：chain 以 `milestone-complete` 结尾
+6. **终点硬约束**：`session.milestone` 存在时 chain 以 `milestone-complete` 结尾；`session.milestone=null`（standalone）时跳过 `milestone-audit` + `milestone-complete` stage，chain 以最后一个质量门 stage 结尾
 7. **goal_ref 传播**：`task_decomposition` 存在时，每个 step 按 `step.stage ∈ g.lifecycle` 匹配 `step.goal_ref = g.id`（多匹配取字典序最小）；decision 节点不打 goal_ref
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
 9. **command_path 解析**（每个执行 step，decision 节点跳过）：

package/.codex/skills/maestro-roadmap/SKILL.md

@@ -11,8 +11,6 @@ Generate a milestone/phase roadmap using `spawn_agents_on_csv` with 2-wave analy
 Wave 1: parallel analysis (scope, risk, dependency). Wave 2: assembly -> roadmap.md with Milestone > Phase hierarchy.
 
 Additional: `--revise` (modify existing roadmap), `--review` (read-only health check).
-
-For formal specification documents (Product Brief, PRD, Architecture, Epics), use `maestro-blueprint` instead.
 </purpose>
 
 <context>
@@ -31,7 +29,7 @@ $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 **Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, `.workflow/roadmap.md`
 
 ### Pre-load (runs unconditionally, including -y auto mode)
-1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints for phase decomposition
+1. **Architecture specs**: `maestro load --type spec --category arch` — load architecture constraints for phase decomposition
 2. **Wiki search**: `maestro search "{requirement keywords}" --json` → prior knowledge for dependency and scope analysis
 3. All optional — proceed without if unavailable (log warning)
 </context>
@@ -40,7 +38,7 @@ $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c`, or input is already specific (clear requirement + mode).
 
 - One decision per turn via request_user_input with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro search`, Glob/Grep/Read, or — for open-ended multi-file scans — `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro load --type spec`, `maestro search`, `maestro explore` (preferred, fallback Glob/Grep/Read). Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
 - Writeback cadence: each settled decision is immediately appended/updated in the `Roadmap Decisions` section at the top of `.workflow/roadmap.md` (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
 - Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.

package/.codex/skills/maestro-tools-execute/SKILL.md

@@ -33,13 +33,13 @@ Empty arguments enters interactive mode: list all tools for user selection.
 
 **By name**:
 ```bash
-maestro spec load --category coding --keyword <name>
+maestro load --type spec --category coding --keyword <name>
 ```
 Match tool entries whose title or keywords contain the name.
 
 **By category**:
 ```bash
-maestro spec load --category <category>
+maestro load --type spec --category <category>
 ```
 Extract tool entries from output, list available tools.
 
@@ -54,7 +54,7 @@ Show tool information:
 
 Expand ref entries:
 ```bash
-maestro wiki load <knowhow-id>
+maestro load --type knowhow --id <knowhow-id>
 ```
 
 ### Step 3: Confirm Execution

package/.codex/skills/maestro-tools-register/SKILL.md

@@ -68,7 +68,7 @@ Parse $ARGUMENTS to determine mode:
 - If unclear, ask user with request_user_input
 
 **Optimize mode**:
-- Load existing tool: `maestro spec load --category coding --keyword <name>`
+- Load existing tool: `maestro load --type spec --category coding --keyword <name>`
 - Analyze improvement points (step splitting, prerequisites, error handling)
 
 **Promote mode** (existing knowhow → tool):
@@ -149,7 +149,7 @@ tool: true
 
 ### Step 6: Verify
 
-- `maestro spec load --category <category> --keyword <keyword>` to confirm loadable
+- `maestro load --type spec --category <category> --keyword <keyword>` to confirm loadable
 - Display result: title, category, keywords, storage location
 
 </execution>

package/.codex/skills/maestro-ui-codify/SKILL.md

@@ -106,7 +106,7 @@ id,wave,title,description,agent_type,deps
 </csv_schema>
 
 <invariants>
-0. **Load UI Specs**: Before extraction, load project UI conventions via `maestro spec load --category ui` (if available). Ensures extracted tokens align with existing conventions.
+0. **Load UI Specs**: Before extraction, load project UI conventions via `maestro load --type spec --category ui` (if available). Ensures extracted tokens align with existing conventions.
 1. **Start Immediately**: First action is argument parsing, then validation
 2. **Wave Order is Sacred**: Never execute wave N+1 before wave N completes and results are merged
 3. **CSV is Source of Truth**: Master tasks.csv holds all state
@@ -396,7 +396,7 @@ Open preview:
 
 Next steps:
   maestro search --category coding    # Browse by role
-  maestro spec load --keyword {package_name}    # Load related specs
+  maestro load --type spec --keyword {package_name}    # Load related specs
 ```
 
 </execution>

package/.codex/skills/manage-codebase-refresh/SKILL.md

@@ -1,72 +1,72 @@
----
-name: manage-codebase-refresh
-description: Refresh codebase docs from recent changes
-argument-hint: "[--since <date>] [--deep]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-<purpose>
-Incremental refresh of codebase documentation based on recent git changes. Detects changed files, maps them to existing doc entries, and updates only affected sections. Use `--deep` for broader context re-scanning.
-</purpose>
-
-<context>
-$ARGUMENTS — optional flags.
-
-```bash
-$manage-codebase-refresh
-$manage-codebase-refresh "--since 2026-03-15"
-$manage-codebase-refresh "--deep"
-$manage-codebase-refresh "--since 3d --deep"
-```
-
-**Flags**:
-- `--since <date>` -- Override change detection window (ISO date or relative like `3d`)
-- `--deep` -- Force deeper re-scan even for minor changes
-</context>
-
-<execution>
-
-### Step 1: Validate Preconditions
-
-Verify `.workflow/` exists (E001) and `.workflow/codebase/` exists (E002 -- use codebase-rebuild instead).
-
-### Step 2: Detect Changes
-
-Resolve baseline: `--since` flag > `state.json.codebase_last_refreshed` > `codebase_last_rebuilt` > 7-day fallback. Run `git diff --name-only --since="{baseline}" HEAD`. If no changes: W001, exit.
-
-### Step 3: Map Changes to Docs
-
-Read `.workflow/codebase/doc-index.json` to find doc entries covering changed files. Build affected entry list.
-
-### Step 3.5: KG Impact Analysis (if KG exists)
-
-If `.workflow/codebase/knowledge-graph.json` exists: run `maestro kg diff-wiki --json`. Parse output for `affectedWiki` entries. If any, log WARNING for each: "KG impact: code changes affect [entry.id] — [entry.title]". Log summary: "{directNodes} direct, {impactedNodes} impacted KG nodes, {affectedWiki.length} wiki entries flagged". If KG does not exist: skip silently.
-
-### Step 4: Refresh Affected Docs
-
-For each affected entry: re-read changed source files, update corresponding doc in `.workflow/codebase/`, update timestamp in `doc-index.json`. With `--deep`: also re-scan adjacent files.
-
-### Step 5: Update State
-
-Update `doc-index.json` timestamps and `state.json.codebase_last_refreshed`. Display summary with change/refresh/skip counts.
-</execution>
-
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | fatal | `.workflow/` not initialized |
-| E002 | fatal | No codebase docs exist -- use `$manage-codebase-rebuild` instead |
-| W001 | warning | No changes detected since last refresh |
-</error_codes>
-
-<success_criteria>
-- [ ] Preconditions validated (.workflow/ and .workflow/codebase/ exist)
-- [ ] Change detection baseline resolved (--since flag, state.json, or 7-day fallback)
-- [ ] Git changes detected and mapped to doc entries via doc-index.json
-- [ ] KG impact analysis run (if knowledge-graph.json exists)
-- [ ] Affected wiki entries flagged with warnings (if any)
-- [ ] Affected docs refreshed with updated source content
-- [ ] --deep flag triggers adjacent file re-scan
-- [ ] doc-index.json timestamps and state.json codebase_last_refreshed updated
-- [ ] Summary displayed with change/refresh/skip counts
-</success_criteria>
+---
+name: manage-codebase-refresh
+description: Refresh codebase docs from recent changes
+argument-hint: "[--since <date>] [--deep]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+<purpose>
+Incremental refresh of codebase documentation based on recent git changes. Detects changed files, maps them to existing doc entries, and updates only affected sections. Use `--deep` for broader context re-scanning.
+</purpose>
+
+<context>
+$ARGUMENTS — optional flags.
+
+```bash
+$manage-codebase-refresh
+$manage-codebase-refresh "--since 2026-03-15"
+$manage-codebase-refresh "--deep"
+$manage-codebase-refresh "--since 3d --deep"
+```
+
+**Flags**:
+- `--since <date>` -- Override change detection window (ISO date or relative like `3d`)
+- `--deep` -- Force deeper re-scan even for minor changes
+</context>
+
+<execution>
+
+### Step 1: Validate Preconditions
+
+Verify `.workflow/` exists (E001) and `.workflow/codebase/` exists (E002 -- use codebase-rebuild instead).
+
+### Step 2: Detect Changes
+
+Resolve baseline: `--since` flag > `state.json.codebase_last_refreshed` > `codebase_last_rebuilt` > 7-day fallback. Run `git diff --name-only --since="{baseline}" HEAD`. If no changes: W001, exit.
+
+### Step 3: Map Changes to Docs
+
+Read `.workflow/codebase/doc-index.json` to find doc entries covering changed files. Build affected entry list.
+
+### Step 3.5: KG Impact Analysis (if KG exists)
+
+If `.workflow/codebase/knowledge-graph.json` exists: run `maestro kg diff-wiki --json`. Parse output for `affectedWiki` entries. If any, log WARNING for each: "KG impact: code changes affect [entry.id] — [entry.title]". Log summary: "{directNodes} direct, {impactedNodes} impacted KG nodes, {affectedWiki.length} wiki entries flagged". If KG does not exist: skip silently.
+
+### Step 4: Refresh Affected Docs
+
+For each affected entry: re-read changed source files, update corresponding doc in `.workflow/codebase/`, update timestamp in `doc-index.json`. With `--deep`: also re-scan adjacent files.
+
+### Step 5: Update State
+
+Update `doc-index.json` timestamps and `state.json.codebase_last_refreshed`. Display summary with change/refresh/skip counts.
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/` not initialized |
+| E002 | fatal | No codebase docs exist -- use `$manage-codebase-rebuild` instead |
+| W001 | warning | No changes detected since last refresh |
+</error_codes>
+
+<success_criteria>
+- [ ] Preconditions validated (.workflow/ and .workflow/codebase/ exist)
+- [ ] Change detection baseline resolved (--since flag, state.json, or 7-day fallback)
+- [ ] Git changes detected and mapped to doc entries via doc-index.json
+- [ ] KG impact analysis run (if knowledge-graph.json exists)
+- [ ] Affected wiki entries flagged with warnings (if any)
+- [ ] Affected docs refreshed with updated source content
+- [ ] --deep flag triggers adjacent file re-scan
+- [ ] doc-index.json timestamps and state.json codebase_last_refreshed updated
+- [ ] Summary displayed with change/refresh/skip counts
+</success_criteria>