maestro-flow 0.1.0

package/workflows/status.md

@@ -0,0 +1,241 @@
+# Workflow: status
+
+Status dashboard with intelligent routing.
+
+---
+
+## Step 1: Load State
+
+1. Check `.workflow/state.json` exists:
+   - If missing → display "No project initialized. Run `/workflow:init` to start." → exit
+
+2. Read `.workflow/state.json`:
+   - Extract: project_name, current_milestone, current_phase, status, phases_summary
+   - Extract: accumulated_context (key_decisions, blockers, deferred)
+
+3. Read `.workflow/roadmap.md`:
+   - Extract phase list with titles
+
+4. Load Issue State:
+   - If `.workflow/issues/issues.jsonl` exists:
+     - Read all lines, parse each as JSON
+     - Compute statistics:
+       ```
+       by_status: {
+         registered: count(status == "registered"),
+         diagnosed:  count(status == "diagnosed"),
+         planning:   count(status == "planning"),
+         planned:    count(status == "planned"),
+         executing:  count(status == "executing")
+       }
+       by_severity: {
+         critical: count(severity == "critical"),
+         high:     count(severity == "high"),
+         medium:   count(severity == "medium"),
+         low:      count(severity == "low")
+       }
+       total_open:    count where status NOT in [completed, failed, deferred]
+       critical_open: count where severity == "critical" AND status NOT in [completed, failed, deferred]
+       critical_issues: list of {id, title, status} where severity == "critical" AND status NOT in [completed, failed, deferred]
+       ```
+     - Store as issue_state
+   - Else:
+     - issue_state = null (no issues tracked)
+
+---
+
+## Step 2: Load Phase Details
+
+For each phase directory in `.workflow/phases/*/`:
+
+1. Read `index.json` if exists:
+   - Extract: phase number, slug, title, status, goal
+   - Extract: plan (task_count, tasks_completed), execution progress
+   - Extract: verification status, validation status, uat status
+
+2. Build phase summary array:
+   ```
+   phases[] = {
+     number, slug, title, status,
+     tasks_total, tasks_completed,
+     verification_status, validation_status
+   }
+   ```
+
+---
+
+## Step 2.5: Roadmap ↔ State Consistency Check
+
+Verify that `roadmap.md` and `state.json` agree on phase structure:
+
+```
+IF .workflow/roadmap.md exists:
+  roadmap_phases = parse phase headings from roadmap.md (count "### Phase N:" entries)
+  state_total = state.json.phases_summary.total
+  actual_dirs = count .workflow/phases/*/ directories
+
+  IF roadmap_phases != state_total OR roadmap_phases != actual_dirs:
+    Display WARNING:
+      ⚠️  STATE SYNC WARNING
+      Roadmap phases: {roadmap_phases}
+      State total:    {state_total}
+      Phase dirs:     {actual_dirs}
+      Run /maestro-roadmap or /maestro-phase-add to reconcile.
+
+ELSE IF NOT .workflow/roadmap.md exists AND state.json.phases_summary.total > 0:
+  Display WARNING:
+    ⚠️  Roadmap missing but state.json references {total} phases.
+    This may indicate a completed milestone. Run /maestro continue to plan next milestone.
+```
+
+---
+
+## Step 3: Compute Progress
+
+1. Count by status:
+   ```
+   total     = phases.length
+   completed = phases.filter(status == "completed").length
+   executing = phases.filter(status == "executing").length
+   planning  = phases.filter(status == "planning").length
+   exploring = phases.filter(status == "exploring").length
+   pending   = phases.filter(status == "pending").length
+   blocked   = phases.filter(status == "blocked").length
+   ```
+
+2. Calculate overall progress:
+   ```
+   progress_pct = (completed / total) * 100
+   ```
+
+---
+
+## Step 4: Display Dashboard
+
+```
+====================================================
+  PROJECT: {project_name}
+  MILESTONE: {current_milestone}
+  STATUS: {status}
+  PROGRESS: [{progress_bar}] {completed}/{total} phases ({progress_pct}%)
+====================================================
+
+PHASES:
+  {for each phase}
+  [{status_icon}] Phase {number}: {title}
+      Status: {status}
+      Tasks: {tasks_completed}/{tasks_total}
+      Verification: {verification_status}
+  {/for}
+
+CONTEXT:
+  Key Decisions: {key_decisions, comma-separated}
+  Blockers: {blockers or "none"}
+  Deferred: {deferred or "none"}
+
+====================================================
+```
+
+### Step 4.1: Render Issue Summary
+
+If issue_state is not null:
+
+```
+┌─────────────────────────────────────────┐
+│ ISSUES                                  │
+├─────────────────────────────────────────┤
+│ Open: {total_open}                      │
+│   Critical: {critical_open}             │
+│   By Status:                            │
+│     registered: {N} | diagnosed: {N}    │
+│     planning: {N}   | planned: {N}      │
+│     executing: {N}                      │
+│                                         │
+│ Critical Issues:                        │
+│   {id} | {title (truncated 40ch)} | {status}  │
+│   ...                                   │
+└─────────────────────────────────────────┘
+```
+
+If critical_issues is empty, omit the "Critical Issues:" sub-section.
+
+If accumulated_context.blockers is non-empty AND issue_state has critical issues:
+  - Print: "Note: Blockers are now tracked as critical issues in .workflow/issues/issues.jsonl"
+
+If accumulated_context.deferred is non-empty:
+  - Print: "Note: Deferred items are tracked as deferred issues. Use /manage-issue list --status deferred"
+
+Else (issue_state is null):
+  - Print: "ISSUES: No issues tracked. Use /manage-issue create or /maestro-verify to discover issues."
+
+Status icons:
+- `[x]` completed
+- `[>]` executing / in_progress
+- `[~]` planning / exploring
+- `[ ]` pending
+- `[!]` blocked
+
+---
+
+## Step 5: Route Next Step
+
+### Step 5.0: Issue-Aware Routing
+
+If issue_state is not null, evaluate issue-based recommendations BEFORE status routing:
+
+If critical_open > 0:
+  - Recommend: "{critical_open} critical issues require attention"
+  - Suggest: Skill({ skill: "manage-issue", args: "list --severity critical" })
+  - Suggest: Skill({ skill: "quality-debug", args: "--from-uat" })
+
+If by_status.diagnosed > 0:
+  - Recommend: "{diagnosed} issues diagnosed and ready for planning"
+  - Suggest: Skill({ skill: "maestro-plan", args: "--gaps" })
+
+If by_status.registered > 0:
+  - Recommend: "{registered} new issues need investigation"
+  - Suggest: Skill({ skill: "quality-debug" })
+
+### Step 5.1: Status-Based Routing
+
+Based on current project status, suggest the next command:
+
+```
+STATUS ROUTING TABLE:
+-------------------------------------------------------------
+Current Status    | Suggested Command           | Reason
+-------------------------------------------------------------
+idle              | /workflow:init              | Project needs initialization
+exploring         | /maestro-analyze -q        | Continue exploration, lock decisions
+                  | /workflow:plan {phase}      | Ready to plan
+planning          | /workflow:plan {phase}      | Resume planning
+executing         | /workflow:execute {phase}   | Resume execution
+verifying         | /workflow:verify {phase}    | Complete verification
+                  | /workflow:review {phase}    | Code quality review
+                  | /workflow:test {phase}      | Run tests
+reviewing         | /workflow:review {phase}    | Complete review
+testing           | /workflow:test {phase}      | Complete testing
+completed (phase) | /workflow:phase-transition  | Move to next phase
+completed (all)   | /workflow:milestone-audit   | Audit milestone
+blocked           | /workflow:debug             | Resolve blockers
+-------------------------------------------------------------
+```
+
+Display:
+```
+NEXT STEP: /workflow:{suggested_command}
+  {reason}
+```
+
+If there are blockers, display them prominently before the routing suggestion.
+
+---
+
+## Step 6: Scratch Tasks (if any)
+
+Check `.workflow/scratch/` for active tasks:
+
+1. For each `scratch/*/index.json` where status != "completed":
+   - Display: type, title, status, progress
+2. If active scratch tasks exist:
+   - Note: "Active scratch tasks found. These are independent of phase pipeline."

package/workflows/sync.md

@@ -0,0 +1,244 @@
+# Workflow: sync
+
+Change detection, impact chain traversal, and codebase documentation synchronization.
+
+## Trigger
+
+- Auto-triggered after `/workflow:execute` completes
+- Manual via `/workflow:sync [--since <ref>] [--dry-run]`
+
+## Arguments
+
+| Arg | Description | Default |
+|-----|-------------|---------|
+| `--full` | Complete resync of all tracked files (ignores git diff, rebuilds all docs) | `false` |
+| `--since <ref>` | Git ref for diff baseline (commit hash, `HEAD~N`, branch) | `HEAD~1` |
+| `--dry-run` | Show impact analysis without writing changes | `false` |
+
+## Prerequisites
+
+- `.workflow/codebase/doc-index.json` must exist (run `/workflow:codebase rebuild` first if missing)
+- Git repository initialized with at least one commit
+
+---
+
+## Workflow Steps
+
+### Step 1: Parse Input and Validate
+
+```
+Parse $ARGUMENTS for flags:
+  --full = complete resync mode (process all tracked files)
+  --since <ref> = diff since specific commit or ref
+  --dry-run = preview mode, no writes
+  No flags = incremental sync since last tracked sync point
+
+Verify .workflow/ directory exists.
+  If not initialized: abort with E001.
+```
+
+### Step 2: Detect Changed Files
+
+```
+If --full flag:
+  Collect all files tracked in doc-index.json code_locations as changed_files[]
+
+Else:
+  Run: git diff --name-only <since-ref>
+    If --since not provided: git diff --name-only HEAD~1
+    If no prior commit: git diff --name-only --cached
+
+  Output: changed_files[] — list of file paths that changed
+
+If no files changed: emit W001 ("No changes detected") and exit.
+```
+
+### Step 3: Load Doc Index
+
+```
+Read: .workflow/codebase/doc-index.json
+
+Extract:
+  - components[] (with code_locations, feature_ids, symbols)
+  - features[] (with component_ids, requirement_ids)
+  - requirements[]
+  - architecture_decisions[]
+```
+
+### Step 4: Impact Chain Traversal
+
+For each `changed_file` in `changed_files[]`:
+
+```
+a. Find matching components:
+   Filter components where code_locations[] contains changed_file
+   (use path matching — file may be relative or absolute)
+
+b. From components -> find features:
+   For each matched component:
+     Collect feature_ids from the component entry
+     OR: Find features where component_ids[] contains the component.id
+
+c. From features -> find requirements:
+   For each matched feature:
+     Collect requirement_ids from the feature entry
+     OR: Find requirements where feature_id matches
+
+d. Aggregate all affected:
+   affected = {
+     files: [changed_file],
+     components: [unique component entries],
+     features: [unique feature entries],
+     requirements: [unique requirement entries]
+   }
+```
+
+Deduplicate across all changed files to build the total impact set.
+
+### Step 5: Update Doc Index (skip if --dry-run)
+
+```
+For each affected component in doc-index.json:
+  Update last_updated timestamp
+  Re-scan code_locations to refresh symbols[] if the component's files changed
+    - Read each code_location file
+    - Extract exported symbols (classes, functions, interfaces, types, constants)
+    - Update symbols[] array
+
+For each affected feature in doc-index.json:
+  Update last_updated timestamp
+  Update status if needed (based on component changes)
+
+Write updated doc-index.json
+```
+
+### Step 6: Regenerate Affected Docs (skip if --dry-run)
+
+```
+For each affected component:
+  Regenerate .workflow/codebase/tech-registry/{component-slug}.md
+  Content template:
+    # {component.name}
+    - **ID**: {component.id}
+    - **Type**: {component.type}
+    - **Code Locations**: {code_locations joined}
+    - **Features**: {feature_ids joined}
+    ## Symbols
+    {symbols as bullet list}
+    ## Last Updated
+    {timestamp}
+
+For each affected feature:
+  Regenerate .workflow/codebase/feature-maps/{feature-slug}.md
+  Content template:
+    # {feature.name}
+    - **ID**: {feature.id}
+    - **Status**: {feature.status}
+    - **Phase**: {feature.phase}
+    - **Components**: {component_ids joined}
+    - **Requirements**: {requirement_ids joined}
+    ## Component Details
+    {for each component: name, type, key symbols}
+    ## Last Updated
+    {timestamp}
+```
+
+### Step 7: Update State and Specs (skip if --dry-run)
+
+```
+Update state.json:
+  - Set last_sync timestamp to current time
+  - Record change summary (files changed, components/features affected)
+  - Update last_updated timestamp
+
+Update index.json:
+  - For each affected phase (if phase-scoped files changed), update the phase index
+
+Check if changes warrant spec updates:
+  - If patterns or conventions changed: append learnings to relevant spec files
+  - If new architectural patterns emerged: note in appropriate spec
+  - Skip if no spec-relevant changes detected
+
+Check if dependency manifests changed (project-tech.json refresh):
+  dependency_files = ["package.json", "go.mod", "pyproject.toml", "Cargo.toml",
+                      "requirements.txt", "pom.xml", "build.gradle", "Gemfile"]
+  changed_deps = changed_files.filter(f => dependency_files.includes(basename(f)))
+  If changed_deps.length > 0 AND .workflow/project-tech.json exists:
+    Re-scan dependency manifests for current tech stack
+    Update .workflow/project-tech.json with detected changes
+    Display: "project-tech.json: refreshed from {changed_deps.join(', ')}"
+```
+
+### Step 8: Create Action Log
+
+```
+Determine action hash:
+  git rev-parse --short HEAD (or use the since-ref hash)
+
+Write .workflow/codebase/action-logs/{hash}.md:
+
+  # Changes in {hash}
+
+  **Date**: {ISO timestamp}
+  **Sync Baseline**: {since-ref}
+
+  ## Files Changed
+  {bullet list of changed_files}
+
+  ## Components Affected
+  {bullet list: component.id - component.name (component.type)}
+
+  ## Features Affected
+  {bullet list: feature.id - feature.name}
+
+  ## Requirements Affected
+  {bullet list: requirement.id - requirement.title}
+
+  ## Impact Summary
+  - Files changed: {count}
+  - Components affected: {count}
+  - Features affected: {count}
+  - Requirements affected: {count}
+```
+
+### Step 9: Report
+
+Display summary to user:
+
+```
+Sync complete:
+  Changed files: N
+  Components affected: N (list IDs)
+  Features affected: N (list IDs)
+  Requirements affected: N (list IDs)
+  Specs updated: {list or "none"}
+  Action log: .workflow/codebase/action-logs/{hash}.md
+  If --dry-run: note that no changes were written
+```
+
+---
+
+## Error Handling
+
+| Code | Meaning |
+|------|---------|
+| E001 | .workflow/ not initialized — suggest running Skill({ skill: "maestro-init" }) first |
+| W001 | No changes detected since last sync — report clean state, skip updates |
+
+| Error | Action |
+|-------|--------|
+| .workflow/ missing | Fail with E001 |
+| doc-index.json missing | Suggest `/workflow:codebase rebuild` |
+| No git repo | Fail with message: "Git repository required for sync" |
+| Changed file not in any component | Log as "untracked file" in action log (no impact chain) |
+| doc-index.json parse error | Fail with error details |
+
+## Output Files
+
+| File | Action |
+|------|--------|
+| `.workflow/codebase/doc-index.json` | Updated (timestamps, symbols) |
+| `.workflow/codebase/tech-registry/{slug}.md` | Regenerated for affected components |
+| `.workflow/codebase/feature-maps/{slug}.md` | Regenerated for affected features |
+| `.workflow/codebase/action-logs/{hash}.md` | Created |
+| `.workflow/project-tech.json` | Updated if dependency manifests changed |