maestro-flow 0.1.1 → 0.1.3

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

@@ -1,82 +1,82 @@
----
-name: maestro-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
-$maestro-codebase-refresh
-$maestro-codebase-refresh "--since 2026-03-15"
-$maestro-codebase-refresh "--deep"
-$maestro-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: maestro-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
+$maestro-codebase-refresh
+$maestro-codebase-refresh "--since 2026-03-15"
+$maestro-codebase-refresh "--deep"
+$maestro-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 |

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

@@ -1,65 +1,65 @@
----
-name: maestro-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
-$maestro-issue "create --title 'Auth token expiry bug' --severity high --source manual"
-$maestro-issue "list --status open --severity high"
-$maestro-issue "status ISS-20260318-001"
-$maestro-issue "update ISS-20260318-001 --priority critical --tags auth,security"
-$maestro-issue "close ISS-20260318-001 --resolution fixed"
-$maestro-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: maestro-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
+$maestro-issue "create --title 'Auth token expiry bug' --severity high --source manual"
+$maestro-issue "list --status open --severity high"
+$maestro-issue "status ISS-20260318-001"
+$maestro-issue "update ISS-20260318-001 --priority critical --tags auth,security"
+$maestro-issue "close ISS-20260318-001 --resolution fixed"
+$maestro-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 |

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

@@ -1,89 +1,89 @@
----
-name: maestro-status
-description: Display project dashboard with phase progress, active tasks, and next steps
-argument-hint: ""
-allowed-tools: Read, Bash, Glob, Grep
----
-
-# Status Dashboard
-
-## Usage
-
-```bash
-$maestro-status
-```
-
-No arguments required. Reads `.workflow/` state files and renders a formatted project overview.
-
----
-
-## Implementation
-
-### Step 1: Validate Project
-
-```bash
-# Verify .workflow/ exists
-test -d .workflow || exit 1  # E001: not initialized
-test -f .workflow/state.json || exit 1  # E002: state missing
-```
-
-### Step 2: Load State Files
-
-Read all state sources:
-- `.workflow/state.json` -- project-level state machine
-- `.workflow/roadmap.md` -- milestone and phase structure
-- `.workflow/phases/*/index.json` -- per-phase metadata and progress
-- `.workflow/phases/*/.task/TASK-*.json` -- individual task statuses
-
-### Step 3: Calculate Progress
-
-For each phase directory found:
-1. Count total tasks, completed, failed, blocked, pending
-2. Calculate completion percentage
-3. Determine phase status from index.json
-
-### Step 4: Render Dashboard
-
-Display formatted output:
-
-```
-=== PROJECT DASHBOARD ===
-Project: {name} | Status: {state}
-
---- Milestones & Phases ---
-{For each milestone}
-  M{N}: {title}
-  {For each phase}
-    Phase {N}: {title} [{status}] {progress_bar} {completed}/{total} ({pct}%)
-
---- Active Work ---
-Phase {N}: {title}
-  In-progress: {list}
-  Blocked: {list}
-
---- Next Steps ---
-Based on current state: {suggestion with Skill() reference}
-```
-
-### Step 5: Suggest Next Steps
-
-Use this decision table to suggest the next action:
-
-| Current State | Suggestion |
-|---------------|------------|
-| No phases planned | `Skill({ skill: "maestro-brainstorm" })` or `Skill({ skill: "maestro-plan" })` |
-| Phase planned, not executed | `Skill({ skill: "maestro-execute", args: "<N>" })` |
-| Phase executed, not verified | `Skill({ skill: "maestro-verify", args: "<N>" })` |
-| Phase verified with gaps | `Skill({ skill: "maestro-plan", args: "<N> --gaps" })` |
-| Phase reviewed PASS/WARN | `Skill({ skill: "quality-test", args: "<N>" })` |
-| UAT passed | `Skill({ skill: "maestro-phase-transition" })` |
-| All milestone phases done | `Skill({ skill: "maestro-milestone-audit" })` |
-
----
-
-## Error Handling
-
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | fatal | `.workflow/` not initialized -- run `Skill({ skill: "maestro-init" })` first |
-| E002 | fatal | `state.json` missing or corrupt |
+---
+name: maestro-status
+description: Display project dashboard with phase progress, active tasks, and next steps
+argument-hint: ""
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+# Status Dashboard
+
+## Usage
+
+```bash
+$maestro-status
+```
+
+No arguments required. Reads `.workflow/` state files and renders a formatted project overview.
+
+---
+
+## Implementation
+
+### Step 1: Validate Project
+
+```bash
+# Verify .workflow/ exists
+test -d .workflow || exit 1  # E001: not initialized
+test -f .workflow/state.json || exit 1  # E002: state missing
+```
+
+### Step 2: Load State Files
+
+Read all state sources:
+- `.workflow/state.json` -- project-level state machine
+- `.workflow/roadmap.md` -- milestone and phase structure
+- `.workflow/phases/*/index.json` -- per-phase metadata and progress
+- `.workflow/phases/*/.task/TASK-*.json` -- individual task statuses
+
+### Step 3: Calculate Progress
+
+For each phase directory found:
+1. Count total tasks, completed, failed, blocked, pending
+2. Calculate completion percentage
+3. Determine phase status from index.json
+
+### Step 4: Render Dashboard
+
+Display formatted output:
+
+```
+=== PROJECT DASHBOARD ===
+Project: {name} | Status: {state}
+
+--- Milestones & Phases ---
+{For each milestone}
+  M{N}: {title}
+  {For each phase}
+    Phase {N}: {title} [{status}] {progress_bar} {completed}/{total} ({pct}%)
+
+--- Active Work ---
+Phase {N}: {title}
+  In-progress: {list}
+  Blocked: {list}
+
+--- Next Steps ---
+Based on current state: {suggestion with Skill() reference}
+```
+
+### Step 5: Suggest Next Steps
+
+Use this decision table to suggest the next action:
+
+| Current State | Suggestion |
+|---------------|------------|
+| No phases planned | `Skill({ skill: "maestro-brainstorm" })` or `Skill({ skill: "maestro-plan" })` |
+| Phase planned, not executed | `Skill({ skill: "maestro-execute", args: "<N>" })` |
+| Phase executed, not verified | `Skill({ skill: "maestro-verify", args: "<N>" })` |
+| Phase verified with gaps | `Skill({ skill: "maestro-plan", args: "<N> --gaps" })` |
+| Phase reviewed PASS/WARN | `Skill({ skill: "quality-test", args: "<N>" })` |
+| UAT passed | `Skill({ skill: "maestro-phase-transition" })` |
+| All milestone phases done | `Skill({ skill: "maestro-milestone-audit" })` |
+
+---
+
+## Error Handling
+
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/` not initialized -- run `Skill({ skill: "maestro-init" })` first |
+| E002 | fatal | `state.json` missing or corrupt |