pi-maestro-flow 0.2.0 → 0.3.0

package/workflows/specs-remove.md

@@ -0,0 +1,104 @@
+# Spec Remove Workflow
+
+Remove a `<spec-entry>` block from a specs container file. Symmetric with `specs-add.md`.
+
+Uses `maestro wiki remove-entry` for atomic removal — the entry is deleted from the markdown file and the unified wiki index is auto-updated by WikiIndexer.
+
+---
+
+## Prerequisites
+
+- `.workflow/specs/` initialized (at least one specs file exists)
+- `maestro wiki` CLI available
+- Entry ID known (use `maestro wiki list --type spec` to discover)
+
+---
+
+## Argument Shape
+
+```
+/spec-remove spec-learnings-003                → remove entry 003 from learnings.md
+/spec-remove spec-coding-conventions-001       → remove entry 001 from coding-conventions.md
+/spec-remove spec-quality-rules-005 -y         → remove without confirmation
+```
+
+| Flag | Effect |
+|------|--------|
+| `<entry-id>` | Required. The spec sub-node ID to remove |
+| `-y` / `--yes` | Skip confirmation prompt |
+
+---
+
+## Stage 1: Parse Input
+
+1. Extract entry ID from arguments
+2. Validate non-empty (E001 if missing)
+3. Check `.workflow/specs/` exists (E002 if not)
+
+---
+
+## Stage 2: Lookup Entry
+
+1. Run `maestro wiki get <entry-id> --json` to fetch entry metadata
+2. Validate entry exists (E003 if not found)
+3. Validate entry is a spec sub-node — must have:
+   - `type` = "spec"
+   - `parent` field set (sub-nodes have parent pointing to container)
+   - If not a sub-node, error E004
+4. Extract: title, category, keywords, container file path, body preview
+
+---
+
+## Stage 3: Confirm Removal
+
+Display entry details for user confirmation:
+
+```
+== Spec Entry to Remove ==
+ID:        {entry-id}
+Title:     {title}
+Category:  {category}
+Keywords:  {keywords}
+Container: .workflow/specs/{filename}
+Preview:   {first 80 chars of body}
+
+Remove this entry? [y/N]
+```
+
+If `-y` flag: skip confirmation.
+If user declines: abort with "Cancelled."
+
+---
+
+## Stage 4: Remove Entry
+
+Execute removal via wiki CLI:
+
+```bash
+maestro wiki remove-entry <entry-id>
+```
+
+This command:
+1. Reads the container file
+2. Locates the `<spec-entry>` block by index position
+3. Removes the block (including opening tag, body, closing tag)
+4. Writes the updated file
+5. WikiIndexer auto-updates `.workflow/wiki-index.json`
+
+---
+
+## Stage 5: Verify & Report
+
+1. Verify entry no longer appears: `maestro wiki get <entry-id>` should return not-found
+2. Display confirmation:
+
+```
+== Entry Removed ==
+ID:        {entry-id}
+From:      .workflow/specs/{filename}
+Remaining: {remaining entry count} entries in {filename}
+
+To verify:  maestro wiki list --type spec --category {category}
+To re-add:  /spec-add {category} {content}
+```
+

package/workflows/specs-setup.md

@@ -0,0 +1,316 @@
+---
+name: spec-setup
+alias: spec-setup
+---
+
+# Workflow: spec-setup
+
+System specs initialization -- scan project structure, detect tech stack, generate convention files.
+
+## Trigger
+
+- First `/maestro-init` (automatic)
+- Manual `/spec-setup`
+
+## Prerequisites
+
+- Project root must exist
+- `.workflow/` directory should exist (create if missing)
+
+## Execution Steps
+
+### Step 1: Ensure Directory Structure
+
+Ensure `.workflow/` and `.workflow/specs/` exist (create if missing).
+
+### Step 2: Scan Project Structure
+
+Scan project root for tech stack indicators:
+
+```
+Manifest files → runtime: package.json (Node), tsconfig.json (TS), pyproject.toml/requirements.txt (Python),
+  go.mod (Go), Cargo.toml (Rust), pom.xml (Maven), build.gradle (Gradle), composer.json (PHP),
+  Gemfile (Ruby), .csproj/.sln (.NET), Dockerfile/docker-compose.yml (containers)
+
+Dependency analysis → frameworks: react/next, vue, angular, express/fastify, django/flask, gin/echo, spring
+```
+
+### Step 3: Detect Code Patterns
+
+Scan source files for coding conventions:
+
+```
+Detect from first 20 source files: indentation style, naming conventions (camelCase/PascalCase/snake_case),
+import style (named/default, aliases, barrels), formatter configs (.prettierrc, .editorconfig, eslint),
+file naming pattern (kebab/camel/Pascal)
+```
+
+### Step 4: Generate Core Files (always created)
+
+#### 4a: coding-conventions.md
+
+Output: `.workflow/specs/coding-conventions.md`
+
+```markdown
+---
+title: "Coding Conventions"
+category: coding
+---
+# Coding Conventions
+
+Auto-generated from project analysis. Update manually as patterns evolve.
+
+## Formatting
+- Indentation: {detected}
+- Line length: {detected or "not configured"}
+- Trailing commas: {detected}
+- Semicolons: {detected}
+
+## Naming
+- Variables/functions: {camelCase | snake_case}
+- Classes/types: {PascalCase}
+- Constants: {UPPER_SNAKE_CASE | camelCase}
+- Files: {kebab-case | camelCase | PascalCase}
+
+## Imports
+- Style: {named imports | default imports | mixed}
+- Path aliases: {@ | ~ | none}
+- Order: {built-in, external, internal, relative}
+
+## Patterns
+{list detected patterns from codebase analysis}
+
+## Entries
+{empty section for spec-add entries}
+```
+
+#### 4b: architecture-constraints.md
+
+Output: `.workflow/specs/architecture-constraints.md`
+
+```markdown
+---
+title: "Architecture Constraints"
+category: arch
+---
+# Architecture Constraints
+
+Auto-generated from project structure. Update manually as architecture evolves.
+
+## Module Structure
+- Type: {monorepo | single-package | multi-package}
+- Key modules: {list detected top-level directories with purposes}
+
+## Layer Boundaries
+{detected layers: e.g., commands/ -> core/ -> tools/ -> types/}
+
+## Dependency Rules
+{detected from imports: which modules import from which}
+
+## Technology Constraints
+- Runtime: {Node.js >= X | Python >= X | ...}
+- Module system: {ESM | CommonJS | ...}
+- Strict mode: {yes | no}
+
+## Entries
+{empty section for spec-add entries}
+```
+
+#### 4c: learnings.md
+
+Output: `.workflow/specs/learnings.md`
+
+```markdown
+---
+title: "Learnings"
+category: learning
+---
+# Learnings
+
+Bugs, gotchas, and lessons learned during development.
+Add entries with: `/spec-add learning <description>`
+
+## Entries
+
+{empty -- entries added via spec-add}
+```
+
+### Step 5: Generate Optional Files (when signals detected)
+
+#### 5a: quality-rules.md (when linter config or CI detected)
+
+Output: `.workflow/specs/quality-rules.md`
+
+```markdown
+---
+title: "Quality Rules"
+category: quality
+---
+# Quality Rules
+
+## Entries
+
+{empty -- entries added via spec-add}
+```
+
+#### 5b: test-conventions.md (when test framework or test files detected)
+
+Scan existing test files for conventions (framework, naming, directory structure, patterns).
+
+Output: `.workflow/specs/test-conventions.md`
+
+```markdown
+---
+title: "Test Conventions"
+category: test
+---
+# Test Conventions
+
+Auto-generated from project analysis. Update manually as patterns evolve.
+
+## Framework
+- Framework: {detected: Jest | Vitest | pytest | Mocha | none}
+- Run command: {detected: npm test | pytest | etc.}
+
+## Directory Structure
+- Pattern: {detected: __tests__/ | tests/ | co-located | etc.}
+
+## Naming Conventions
+- Test files: {detected: *.test.ts | *.spec.ts | test_*.py | etc.}
+
+## Patterns
+{detected patterns from existing test files}
+
+## Entries
+{empty section for spec-add entries}
+```
+
+#### 5c: ui-conventions.md (when frontend framework detected)
+
+Scan for frontend frameworks (React, Vue, Angular, Svelte, etc.) and UI libraries.
+
+Output: `.workflow/specs/ui-conventions.md`
+
+```markdown
+---
+title: "UI Conventions"
+category: ui
+---
+# UI Conventions
+
+Auto-generated from project analysis. Update manually as patterns evolve.
+
+## Entries
+
+{empty section for spec-add entries}
+```
+
+#### 5d: debug-notes.md and review-standards.md
+
+These are NOT created during setup. They are created on demand when `spec-add debug` or `spec-add review` is first used.
+
+### Step 6: Generate Workflow Knowhow Recipes (when signals detected)
+
+Spec files in Step 4-5 capture *conventions*. This step captures *operational workflows* — "how to do X in this project" — as **recipe-type knowhow** so future agents can discover them via `maestro wiki search` and `maestro knowhow list --type recipe`.
+
+Output directory: `.workflow/knowhow/` (knowhow store, NOT `.workflow/specs/`).
+Schema: matches `recipe` type defined in `~/.maestro/workflows/knowhow.md` Part B.
+
+**Detection → recipe matrix:**
+
+| Recipe slug | Trigger signals | Step extraction source |
+|-------------|----------------|------------------------|
+| `test-workflow` | Test framework detected in Step 5b (jest/vitest/pytest/mocha/go test/cargo test) | `package.json` `scripts.test*`, `pytest.ini`/`pyproject.toml [tool.pytest]`, `go test ./...`, test layout from Step 5b |
+| `debug-workflow` | `.vscode/launch.json` OR logging lib import (pino/winston/loguru/zap/log) OR error tracker SDK (sentry/bugsnag/rollbar) OR `DEBUG=` env usage in code | launch.json entries, `--inspect` flags in scripts, logger config files, observed `log.debug(...)` / `logger.info(...)` patterns |
+| `build-workflow` | `scripts.build` in package.json OR Makefile `build:` target OR `cargo build` OR `gradle build` OR `go build` | Verbatim script chain; multi-step pipelines noted explicitly |
+| `dev-workflow` | `scripts.dev`/`scripts.start` OR `manage.py runserver` OR `air`/`reflex` config OR docker-compose dev override | Dev command + detected port from config + hot-reload flag |
+| `lint-workflow` | Linter+formatter pair detected: eslint+prettier / ruff+black / golangci-lint+gofmt / rustfmt+clippy | Configured commands, pre-commit hooks from `.pre-commit-config.yaml` or `husky/`, CI lint job |
+
+**Skip rule:** If signals are missing, skip the recipe — do NOT generate placeholders.
+
+**Idempotency rule:** Before writing, glob `.workflow/knowhow/RCP-*-{slug}.md`. If a file matching the slug exists, do NOT overwrite — write `.workflow/knowhow/RCP-{YYYYMMDD}-{slug}.proposed.md` instead and mention it in Step 7 summary so the user can diff and merge manually.
+
+**Filename:** `.workflow/knowhow/RCP-{YYYYMMDD}-{slug}.md` (date + semantic slug for readability).
+
+**Tags rule:** Match content language (English codebase → English tags). Always include `workflow`, the slug, and the detected framework (e.g. `vitest`, `pytest`). Add `auto-generated` so users can identify spec-setup output for later pruning.
+
+**Recipe template** (one file per detected workflow):
+
+```markdown
+---
+title: "{Project name} — {Workflow name}"
+type: recipe
+tags: [workflow, {slug}, {framework}, auto-generated]
+created: {ISO timestamp}
+source: spec-setup
+---
+
+# {title}
+
+## Goal
+{One sentence stating the operational outcome — "Run the test suite locally and in CI", "Reproduce and inspect a runtime bug with full stack context", etc.}
+
+## Prerequisites
+- {Required runtime/version from manifest, e.g. "Node.js >= 18"}
+- {Required env vars detected in .env.example or code}
+- {Required services if docker-compose detected}
+
+## Steps
+1. {Copy-paste-ready command 1 — derived from detected scripts}
+2. {Command 2}
+3. ...
+
+## Expected Outcome
+{Concrete success signal — "All tests green, coverage report at coverage/index.html" / "Dev server reachable at http://localhost:PORT with HMR active"}
+
+## Common Pitfalls
+- {Inferred from detected patterns — e.g. "Vitest watch mode locks DB if integration suite is selected"}
+- {Generic gotchas: port conflicts, missing env, stale dist/}
+
+## Related
+- [[test-conventions]] / [[architecture-constraints]] — convention specs (link when they exist)
+```
+
+**Per-recipe extraction guides:**
+
+- **`test-workflow`** — Steps must list: (a) install command if first run, (b) full-suite command, (c) watch/filter command, (d) coverage command. For pytest, include marker selection if `pytest.ini` declares markers. For Go, document `-race` and `-tags` flags if used in CI.
+- **`debug-workflow`** — Steps must cover: (a) attach/launch via debugger (cite the exact `launch.json` configuration name), (b) increase log verbosity (cite the env var or config flag actually used in code), (c) reproduce-and-capture pattern (point at the project's logging entry pattern with one file:line example). Mention error-tracker DSN env if Sentry/Bugsnag SDK is wired.
+- **`build-workflow`** — Reproduce the `scripts.build` chain verbatim; if it spans multiple commands, number them. Note the output directory (`dist/`, `build/`, `target/`) and any required `prepublishOnly`/`postbuild` side effects.
+- **`dev-workflow`** — Dev server command, detected default port, hot-reload flag, and any companion process (e.g. `npm run dev` + `npm run mcp` if both are typically run together — detect this when both appear under `scripts` and one is `dev`).
+- **`lint-workflow`** — Linter command, formatter command, fix command (`--fix` / `--write`), pre-commit hook trigger if `husky/_/pre-commit` or `.pre-commit-config.yaml` exists.
+
+**Quality bar:** Every generated recipe must contain at least one runnable command. If signals are present but no concrete command can be extracted with confidence, do NOT write the file — emit `W002: <slug> signals detected but commands ambiguous, skipped` and continue.
+
+**Wiki indexing:** Files in `.workflow/knowhow/` are auto-indexed by WikiIndexer (`type=knowhow`). No separate index step required — they appear in `maestro wiki list --type knowhow` after the next index pass.
+
+### Step 7: Summary
+
+Glob created spec/recipe files MUST exist before Step 7 summary; BLOCKED if missing.
+
+Display list of all created files grouped by destination:
+
+```
+## Specs (.workflow/specs/)
+- coding-conventions.md
+- architecture-constraints.md
+- learnings.md
+- {optional spec files created}
+
+## Workflow Recipes (.workflow/knowhow/)
+- RCP-{ts}-test-workflow.md       (vitest detected)
+- RCP-{ts}-debug-workflow.md      (pino + .vscode/launch.json detected)
+- {other recipes}
+
+## Skipped (signals missing)
+- build-workflow — no build script detected
+- {other skips}
+
+## Deferred (created on demand)
+- debug-notes.md, review-standards.md — use /spec-add when needed
+```
+
+Note that `debug-notes.md` and `review-standards.md` are created on demand via `/spec-add`, and any `.proposed.md` files indicate an existing recipe was not overwritten — review and merge manually.
+
+## Output
+
+All files listed above under `.workflow/specs/` and `.workflow/knowhow/`.

package/workflows/status.md

@@ -0,0 +1,149 @@
+# 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, status, milestones, artifacts
+   - Derive current_phase and phases_summary from artifacts[] (see src/utils/state-schema.ts)
+   - Extract: accumulated_context (key_decisions, blockers, deferred)
+
+3. Read `.workflow/roadmap.md`:
+   - Extract phase list with titles
+
+4. Load Issue State from `.workflow/issues/issues.jsonl` (if exists):
+   ```
+   Compute: by_status (registered/diagnosed/planning/planned/executing counts),
+     by_severity (critical/high/medium/low counts),
+     total_open (exclude completed/failed/deferred),
+     critical_open + critical_issues list {id, title, status}
+   ```
+   If file missing → issue_state = null
+
+---
+
+## Step 2: Build Virtual Phase View from Artifact Registry
+
+Derive phase progress from `state.json.artifacts[]`:
+
+```
+milestone_artifacts = artifacts filtered by current_milestone
+phases_from_roadmap = parse roadmap.md → { number, slug, title }
+
+Per phase: check completed artifact types (analyze/plan/execute/verify)
+  → derive status: verified > executed > planned > analyzed > pending
+  → get task counts from plan artifact's plan.json if available
+
+Output: phases[] = { number, slug, title, status, tasks_total, tasks_completed, has_verify }
+Also collect: adhoc_artifacts (scope == "adhoc")
+```
+
+---
+
+## Step 2.5: Artifact Registry Consistency Check
+
+```
+If roadmap exists → warn if any artifacts reference phases not in roadmap (orphan check)
+If roadmap missing but artifacts exist → warn: may indicate completed milestone, suggest /maestro continue
+```
+
+---
+
+## Step 3: Compute Progress
+
+```
+Count phases by status: completed, executing, planning, exploring, pending, blocked
+progress_pct = (completed / total) * 100
+```
+
+---
+
+## Step 4: Display Dashboard
+
+```
+PROJECT / MILESTONE / STATUS / PROGRESS bar ({completed}/{total} phases)
+Per phase: [{status_icon}] Phase {N}: {title} — status, task counts, verification
+CONTEXT: key_decisions, blockers, deferred
+```
+
+### Step 4.1: Render Issue Summary
+
+If issue_state exists: display ISSUES panel (open count, critical count, by-status breakdown, critical issues list).
+- Omit critical sub-section if none. Note blockers→issues migration if applicable. Note deferred items.
+
+If issue_state is null: "No issues tracked. Use /manage-issue create to discover issues."
+
+Status icons:
+- `[x]` completed
+- `[>]` executing / in_progress
+- `[~]` planning / exploring
+- `[ ]` pending
+- `[!]` blocked
+
+### Step 4.2: Render Worktree Status
+
+```
+If .workflow/worktree-scope.json exists → WORKTREE MODE panel: milestone, branch, owned_phases, main_worktree
+Else if .workflow/worktrees.json has active entries → ACTIVE WORKTREES panel: milestone/branch/path per worktree,
+  with sync (/maestro-fork --sync) and merge (/maestro-merge) hints
+```
+
+---
+
+## Step 5: Route Next Step
+
+### Step 5.0: Issue-Aware Routing
+
+If issue_state exists, evaluate BEFORE status routing:
+- critical_open > 0 → suggest manage-issue list --severity critical, quality-debug --from-uat
+- diagnosed > 0 → suggest maestro-plan --gaps
+- registered > 0 → suggest quality-debug
+
+### Step 5.1: Status-Based Routing
+
+Based on current project state, suggest the next command:
+
+| Current State | Suggested Command |
+|---|---|
+| No phases planned | /maestro-brainstorm 1 or /maestro-plan 1 |
+| Phase pending, needs analysis | /maestro-analyze \<N\> |
+| Phase pending, needs decisions | /maestro-analyze \<N\> -q |
+| Phase planned, not executed | /maestro-execute \<N\> |
+| Phase executing, tasks blocked | /quality-debug \<N\> |
+| Phase executed, not verified | /quality-review \<N\> |
+| Phase verified with gaps | /maestro-plan \<N\> --gaps |
+| Phase verified, not reviewed | /quality-review \<N\> |
+| Phase reviewed, BLOCK verdict | /maestro-plan \<N\> --gaps |
+| Phase reviewed, PASS/WARN | /quality-test \<N\> |
+| Low test coverage | /quality-auto-test \<N\> |
+| UAT passed, all phases done | /maestro-milestone-audit |
+| UAT has failures | /quality-debug --from-uat \<N\> |
+| Need integration tests | /quality-auto-test \<N\> |
+| All milestone phases complete | /maestro-milestone-audit |
+| Milestone audit passed | /maestro-milestone-complete |
+| Ad-hoc small task | /maestro-quick \<task\> |
+
+Display:
+```
+NEXT STEP: {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,116 @@
+# Workflow: sync
+
+Change detection, impact chain traversal, and codebase doc synchronization. Auto-triggered after execute, or manual via `/workflow:sync`.
+
+## 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` |
+
+---
+
+## Workflow Steps
+
+### Step 1: Parse Input and Validate
+
+```
+Parse flags: --full (resync all), --since <ref> (diff baseline), --dry-run (preview)
+Default: incremental sync since last tracked sync point
+Require .workflow/ exists → else abort E001
+```
+
+### Step 2: Detect Changed Files
+
+```
+--full → collect all files from doc-index.json code_locations
+else  → git diff --name-only <since-ref|HEAD~1|--cached>
+No files changed → emit W001, exit
+```
+
+### Step 3: Load Doc Index
+
+```
+Read .workflow/codebase/doc-index.json
+Extract: components[], features[], requirements[], architecture_decisions[]
+
+If missing: prompt → (a) MUST run /manage-codebase-rebuild then re-run
+             or    → (b) DEGRADED_MODE: git-diff-only, skip Steps 3-5; flag sync as [LOW CONFIDENCE] (git-diff-only, Steps 3-5 skipped)
+```
+
+### Step 4: Impact Chain Traversal
+
+For each `changed_file` in `changed_files[]`:
+
+```
+Traverse impact chain: file → components (via code_locations match)
+  → features (via component.feature_ids) → requirements (via feature.requirement_ids)
+Aggregate deduplicated: { files, components, features, requirements }
+```
+
+GATE Step 4→5: impact_chain non-empty BEFORE update index; BLOCKED if impact_chain empty (no affected components/features/requirements identified)
+
+### Step 5: Update Doc Index (skip if --dry-run)
+
+```
+Affected components → refresh last_updated, re-scan code_locations for symbols[]
+Affected features   → refresh last_updated, update status
+Write updated doc-index.json
+```
+
+### Step 6: Regenerate Affected Docs (skip if --dry-run)
+
+```
+Components → regenerate .workflow/codebase/tech-registry/{component-slug}.md
+Features   → regenerate .workflow/codebase/feature-maps/{feature-slug}.md
+```
+
+### Step 7: Update State and Specs (skip if --dry-run)
+
+```
+state.json → last_sync timestamp, change summary
+index.json → update affected phase indexes
+Dependency manifests changed + project.md exists → refresh Tech Stack section
+```
+
+### Step 8: Create Action Log
+
+```
+Write .workflow/codebase/action-logs/{hash}.md:
+  date, baseline, files changed, affected components/features/requirements, impact counts
+```
+
+### Step 9: Report
+
+```
+Display: changed files, affected components/features/requirements, specs updated, action log path
+```
+
+---
+
+## 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.md` | Tech Stack section updated if dependency manifests changed |