maestro-flow 0.3.10 → 0.3.12

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

@@ -1,82 +1,93 @@
----
-name: manage-codebase-refresh
-description: Incremental refresh of codebase docs based on recent git changes
-argument-hint: "[--since <date>] [--deep]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# Codebase Refresh
-
-## Usage
-
-```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
-
----
-
-## Implementation
-
-### Step 1: Validate Preconditions
-
-```bash
-test -d .workflow || exit 1        # E001: not initialized
-test -d .workflow/codebase || exit 1  # E002: no docs, use codebase-rebuild
-```
-
-### Step 2: Detect Changes
-
-Determine baseline timestamp:
-1. If `--since` provided, use that date
-2. Else read `state.json` field `codebase_last_refreshed` or `codebase_last_rebuilt`
-3. Fallback to last 7 days
-
-```bash
-git diff --name-only --since="{baseline}" HEAD
-```
-
-If no changes detected, report clean state (W001) and exit.
-
-### Step 3: Map Changes to Docs
-
-Read `.workflow/codebase/doc-index.json` to find which documentation entries cover the changed files.
-Build a list of affected doc entries that need refresh.
-
-### Step 4: Refresh Affected Docs
-
-For each affected documentation entry:
-1. Re-read the source files that changed
-2. Update the corresponding doc section in `.workflow/codebase/`
-3. Update the entry's timestamp in `doc-index.json`
-
-If `--deep` flag is set, also re-scan adjacent files for context changes.
-
-### Step 5: Update State
-
-Update `doc-index.json` timestamps for all refreshed entries.
-Update `state.json` with `codebase_last_refreshed: "{ISO timestamp}"`.
-
-Display summary:
-```
-=== CODEBASE REFRESH ===
-Changes detected: {N} files
-Docs refreshed: {M} entries
-Skipped (unchanged): {K} entries
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | fatal | `.workflow/` not initialized |
-| E002 | fatal | No codebase docs exist -- use `Skill({ skill: "codebase-rebuild" })` instead |
-| W001 | warning | No changes detected since last refresh |
+---
+name: manage-codebase-refresh
+description: Incremental refresh of codebase docs based on recent git 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
+
+```bash
+test -d .workflow || exit 1        # E001: not initialized
+test -d .workflow/codebase || exit 1  # E002: no docs, use codebase-rebuild
+```
+
+### Step 2: Detect Changes
+
+Determine baseline timestamp:
+1. If `--since` provided, use that date
+2. Else read `state.json` field `codebase_last_refreshed` or `codebase_last_rebuilt`
+3. Fallback to last 7 days
+
+```bash
+git diff --name-only --since="{baseline}" HEAD
+```
+
+If no changes detected, report clean state (W001) and exit.
+
+### Step 3: Map Changes to Docs
+
+Read `.workflow/codebase/doc-index.json` to find which documentation entries cover the changed files.
+Build a list of affected doc entries that need refresh.
+
+### Step 4: Refresh Affected Docs
+
+For each affected documentation entry:
+1. Re-read the source files that changed
+2. Update the corresponding doc section in `.workflow/codebase/`
+3. Update the entry's timestamp in `doc-index.json`
+
+If `--deep` flag is set, also re-scan adjacent files for context changes.
+
+### Step 5: Update State
+
+Update `doc-index.json` timestamps for all refreshed entries.
+Update `state.json` with `codebase_last_refreshed: "{ISO timestamp}"`.
+
+Display summary:
+```
+=== CODEBASE REFRESH ===
+Changes detected: {N} files
+Docs refreshed: {M} entries
+Skipped (unchanged): {K} entries
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/` not initialized |
+| E002 | fatal | No codebase docs exist -- use `Skill({ skill: "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
+- [ ] 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>

package/.codex/skills/manage-harvest/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: manage-harvest
+description: Extract knowledge fragments from workflow artifacts (analysis, brainstorm, debug, lite-plan, scratchpad, sessions) and route to wiki / spec / issue stores. Dedup via stable fragment IDs. Closed-loop with downstream consumers.
+argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Knowledge extraction from workflow artifacts, routed into three stores: wiki entries,
+spec conventions, and trackable issues. Prevents knowledge loss from completed sessions.
+
+**Closed-loop**: harvest extracts → stores → downstream consumers (wiki-digest, spec-load, maestro-plan --gaps).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/harvest.md
+</required_reading>
+
+<context>
+$ARGUMENTS — session-id, path, or empty for scan mode.
+
+**Modes:**
+- No args → `scan`: discover all harvestable artifacts, interactive selection
+- `<session-id>` → `session`: harvest specific session
+- `<path>` → `path`: harvest from explicit directory
+
+**Flags:**
+- `--to <target>` — Force routing: wiki, spec, issue, auto (default: auto)
+- `--source <type>` — Filter: analysis, brainstorm, debug, lite-plan, lite-fix, scratchpad, session, learning, all
+- `--recent N` — Artifacts within last N days (default: 30)
+- `--dry-run` — Preview without writing
+- `-y` — Skip confirmations
+- `--min-confidence N` — Minimum 0.0-1.0 (default: 0.5)
+
+**Source registry:**
+| Source | Scan Path | Key Files |
+|--------|-----------|-----------|
+| analysis | `.workflow/.analysis/ANL-*/` | conclusions.json |
+| brainstorm | `.workflow/scratch/brainstorm-*/` | guidance-specification.md |
+| lite-plan | `.workflow/.lite-plan/*/` | plan.json |
+| lite-fix | `.workflow/.lite-fix/*/` | fix-plan.json |
+| debug | `.workflow/.debug/*/` | debug-log.md |
+| scratchpad | `.workflow/.scratchpad/` | *.md |
+| session | `.workflow/active/WFS-*/` | workflow-session.json |
+| learning | `.workflow/learning/` | lessons.jsonl |
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/harvest.md' Stages 1–8.
+
+**Key invariants:**
+1. **Read-only until Stage 6** — extraction/classification in-memory only
+2. **Dedup before write** — check harvest-log.jsonl + existing stores
+3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)`
+4. **Never modify source artifacts** — purely extractive
+5. **Confidence filtering** — below threshold logged but not routed
+
+**Next steps:** `maestro wiki list --type note`, `/wiki-connect --fix`, `/manage-issue list --source harvest`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Run $maestro-init |
+| E002 | error | Invalid --to target | Valid: wiki, spec, issue, auto |
+| E003 | error | Invalid --source type | Display valid types |
+| E004 | error | Session ID not found | Show available sessions |
+| W001 | warning | No harvestable artifacts in window | Widen --recent |
+| W003 | warning | Fragments below threshold | Lower --min-confidence |
+| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode resolved (scan / session / path)
+- [ ] Artifacts discovered and parsed
+- [ ] Fragments extracted with category, confidence, tags
+- [ ] Dedup check passed against harvest-log.jsonl and stores
+- [ ] If not dry-run: routed items written to target stores
+- [ ] harvest-log.jsonl updated with provenance
+- [ ] harvest-report-{date}.md written
+- [ ] No source artifacts modified
+</success_criteria>

package/.codex/skills/manage-issue/SKILL.md

@@ -1,65 +1,80 @@
----
-name: manage-issue
-description: Issue CRUD -- create, list, status, update, close, and link issues to tasks
-argument-hint: "<create|list|status|update|close|link> [options]"
-allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
----
-
-# Issue Management
-
-## Usage
-
-```bash
-$manage-issue "create --title 'Auth token expiry bug' --severity high --source manual"
-$manage-issue "list --status open --severity high"
-$manage-issue "status ISS-20260318-001"
-$manage-issue "update ISS-20260318-001 --priority critical --tags auth,security"
-$manage-issue "close ISS-20260318-001 --resolution fixed"
-$manage-issue "link ISS-20260318-001 --task TASK-003"
-```
-
----
-
-## Implementation
-
-### Step 1: Parse Subcommand
-
-Extract first token as subcommand. Valid: `create`, `list`, `status`, `update`, `close`, `link`.
-If missing or invalid, display usage and prompt user (E_NO_SUBCOMMAND, E_INVALID_SUBCOMMAND).
-
-### Step 2: Ensure Storage
-
-```bash
-mkdir -p .workflow/issues
-touch .workflow/issues/issues.jsonl 2>/dev/null
-```
-
-Auto-create directory and empty file if missing (E_ISSUES_DIR_MISSING handled silently).
-
-### Step 3: Execute Subcommand
-
-**create**: Read `~/.maestro/templates/issue.json` for schema. Generate ID `ISS-{YYYYMMDD}-{NNN}`. Prompt for missing required fields (title, severity). Append JSON line to `issues.jsonl`.
-
-**list**: Read `issues.jsonl`, filter by `--status`, `--phase`, `--severity`, `--source`. Display as table:
-```
-ID              | Severity | Status | Title
-ISS-20260318-001 | high     | open   | Auth token expiry bug
-```
-
-**status**: Find issue by ID in `issues.jsonl`. Display all fields in detail format.
-
-**update**: Find issue by ID, merge provided fields, rewrite the line in `issues.jsonl`. Track `updated_at` timestamp.
-
-**close**: Find issue by ID, set status to `closed`, add `resolution` and `closed_at`. Move line from `issues.jsonl` to `issue-history.jsonl`.
-
-**link**: Find issue by ID, add task reference to issue's `linked_tasks` array. If task JSON exists (`.task/TASK-*.json`), add issue reference to task's `linked_issues`. Bidirectional cross-reference.
-
----
-
-## Error Handling
-
-| Code | Severity | Description |
-|------|----------|-------------|
-| E_NO_SUBCOMMAND | error | No subcommand provided -- display valid subcommands |
-| E_INVALID_SUBCOMMAND | error | Unrecognized subcommand |
-| E_ISSUES_DIR_MISSING | warning | `.workflow/issues/` not found -- auto-created |
+---
+name: manage-issue
+description: Issue CRUD -- create, list, status, update, close, and link issues to tasks
+argument-hint: "<create|list|status|update|close|link> [options]"
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Issue CRUD operations: create, list, status, update, close, and link issues to tasks.
+All data stored in `.workflow/issues/issues.jsonl` with auto-created directory on first use.
+</purpose>
+
+<context>
+$ARGUMENTS — subcommand followed by options.
+
+```bash
+$manage-issue "create --title 'Auth token expiry bug' --severity high --source manual"
+$manage-issue "list --status open --severity high"
+$manage-issue "status ISS-20260318-001"
+$manage-issue "update ISS-20260318-001 --priority critical --tags auth,security"
+$manage-issue "close ISS-20260318-001 --resolution fixed"
+$manage-issue "link ISS-20260318-001 --task TASK-003"
+```
+
+**Subcommands**: `create`, `list`, `status`, `update`, `close`, `link`.
+</context>
+
+<execution>
+
+### Step 1: Parse Subcommand
+
+Extract first token as subcommand. Valid: `create`, `list`, `status`, `update`, `close`, `link`.
+If missing or invalid, display usage and prompt user (E_NO_SUBCOMMAND, E_INVALID_SUBCOMMAND).
+
+### Step 2: Ensure Storage
+
+```bash
+mkdir -p .workflow/issues
+touch .workflow/issues/issues.jsonl 2>/dev/null
+```
+
+Auto-create directory and empty file if missing (E_ISSUES_DIR_MISSING handled silently).
+
+### Step 3: Execute Subcommand
+
+**create**: Read `~/.maestro/templates/issue.json` for schema. Generate ID `ISS-{YYYYMMDD}-{NNN}`. Prompt for missing required fields (title, severity). Append JSON line to `issues.jsonl`.
+
+**list**: Read `issues.jsonl`, filter by `--status`, `--phase`, `--severity`, `--source`. Display as table:
+```
+ID              | Severity | Status | Title
+ISS-20260318-001 | high     | open   | Auth token expiry bug
+```
+
+**status**: Find issue by ID in `issues.jsonl`. Display all fields in detail format.
+
+**update**: Find issue by ID, merge provided fields, rewrite the line in `issues.jsonl`. Track `updated_at` timestamp.
+
+**close**: Find issue by ID, set status to `closed`, add `resolution` and `closed_at`. Move line from `issues.jsonl` to `issue-history.jsonl`.
+
+**link**: Find issue by ID, add task reference to issue's `linked_tasks` array. If task JSON exists (`.task/TASK-*.json`), add issue reference to task's `linked_issues`. Bidirectional cross-reference.
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E_NO_SUBCOMMAND | error | No subcommand provided -- display valid subcommands |
+| E_INVALID_SUBCOMMAND | error | Unrecognized subcommand |
+| E_ISSUES_DIR_MISSING | warning | `.workflow/issues/` not found -- auto-created |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed and validated
+- [ ] Storage directory and files auto-created on first use
+- [ ] create: generates unique ISS-id, prompts for required fields, appends to JSONL
+- [ ] list: filters by status/phase/severity/source, renders table
+- [ ] status: displays full detail for given ISS-id
+- [ ] update: merges fields, tracks updated_at timestamp
+- [ ] close: sets status closed, moves to history file
+- [ ] link: bidirectional cross-reference between issue and task
+</success_criteria>