maestro-flow 0.1.0

package/workflows/cli-tools-usage.md

@@ -0,0 +1,220 @@
+# CLI Tools Execution Specification
+
+<purpose>
+Unified reference for `maestro cli` — runs agent tools (gemini, qwen, codex, claude, opencode) with a shared interface for prompt, mode, model, directory, templates, and session resume.
+</purpose>
+
+**References**: `~/.maestro/cli-tools.json` (tool config), `~/.maestro/templates/cli/` (protocol + prompt templates)
+
+---
+
+## 1. Quick Reference
+
+<context>
+
+### Command Syntax
+
+```bash
+maestro cli -p "<PROMPT>" [options]
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --prompt` | **Required**. Prompt text | — |
+| `--tool <name>` | Tool: gemini, qwen, codex, claude, opencode | First enabled in config |
+| `--mode <mode>` | `analysis` (read-only) or `write` (create/modify/delete) | `analysis` |
+| `--model <model>` | Model override | Tool's `primaryModel` |
+| `--cd <dir>` | Working directory | Current directory |
+| `--includeDirs <dirs>` | Additional directories (comma-separated) | — |
+| `--rule <template>` | Load protocol + prompt template | — (optional) |
+| `--id <id>` | Execution ID | Auto: `{prefix}-{HHmmss}-{rand4}` |
+| `--resume [id]` | Resume session (last if no id, comma-separated for merge) | — |
+
+### Mode Definition (Authoritative)
+
+| Mode | Permission | Auto-Invoke Safe | Use For |
+|------|-----------|------------------|---------|
+| `analysis` | Read-only | Yes | Review, exploration, diagnosis, architecture analysis |
+| `write` | Create/Modify/Delete | No — requires explicit intent | Implementation, bug fixes, refactoring |
+
+> `--mode` is the **authoritative** permission control for maestro cli. The `MODE:` field inside prompt text is a hint for the agent — both should be consistent, but `--mode` governs actual behavior.
+</context>
+
+---
+
+## 2. Configuration
+
+<context>
+
+### Config File: `~/.maestro/cli-tools.json`
+
+| Field | Description |
+|-------|-------------|
+| `enabled` | Tool availability |
+| `primaryModel` | Default model |
+| `secondaryModel` | Fallback model |
+| `tags` | Capability tags (for caller-side routing) |
+| `type` | `builtin` / `cli-wrapper` / `api-endpoint` |
+
+> `api-endpoint` tools support **analysis only** — no file write capability.
+
+### Supported Tools
+
+| Tool | Agent Type | Adapter |
+|------|-----------|---------|
+| `gemini` | gemini | StreamJsonAdapter |
+| `qwen` | qwen | StreamJsonAdapter |
+| `codex` | codex | CodexCliAdapter |
+| `claude` | claude-code | ClaudeCodeAdapter |
+| `opencode` | opencode | OpenCodeAdapter |
+
+### Tool Selection
+
+1. Explicit `--tool` specified → use it (validate enabled)
+2. No `--tool` → first enabled tool in config order
+
+### Fallback Chain
+
+Primary model fails → `secondaryModel` → next enabled tool → first enabled (default).
+</context>
+
+---
+
+## 3. Prompt Construction
+
+<context>
+
+### Assembly Order
+
+`maestro cli` builds the final prompt as:
+
+1. **Mode protocol** — `~/.maestro/templates/cli/protocols/{mode}-protocol.md`
+2. **User prompt** — the `-p` value
+3. **Rule template** — `~/.maestro/templates/cli/prompts/{rule}.txt` (if `--rule` specified)
+
+### Prompt Template (6 Fields)
+
+```
+PURPOSE: [goal] + [why] + [success criteria]
+TASK: [step 1] | [step 2] | [step 3]
+MODE: analysis|write
+CONTEXT: @[file patterns] | Memory: [prior work context]
+EXPECTED: [output format] + [quality criteria]
+CONSTRAINTS: [scope limits] | [special requirements]
+```
+
+- **PURPOSE**: What + Why + Success. Not "Analyze code" but "Identify auth vulnerabilities; success = OWASP Top 10 covered"
+- **TASK**: Specific verbs. Not "Review code" but "Scan for SQL injection | Check XSS | Verify CSRF"
+- **MODE**: Must match `--mode` flag
+- **CONTEXT**: File scope + memory from prior work
+- **EXPECTED**: Deliverable format, not just "Report"
+- **CONSTRAINTS**: Task-specific limits (vs `--rule` which loads generic templates)
+
+### CONTEXT: File Patterns + Directory
+
+- `@**/*` — all files in working directory (default)
+- `@src/**/*.ts` — scoped pattern
+- `@../shared/**/*` — sibling directory (**requires `--includeDirs`**)
+
+**Rule**: If CONTEXT uses `@../dir/**/*`, must add `--includeDirs ../dir`.
+
+```bash
+# Cross-directory example
+maestro cli -p "CONTEXT: @**/* @../shared/**/*" --tool gemini --mode analysis \
+  --cd "src/auth" --includeDirs "../shared"
+```
+
+### CONTEXT: Memory
+
+Include when building on previous work:
+
+```
+Memory: Building on auth refactoring (commit abc123), implementing refresh tokens
+Memory: Integration with auth module, using shared error patterns
+```
+
+### --rule Templates
+
+**Universal**: `universal-rigorous-style`, `universal-creative-style`
+
+**Analysis**: `analysis-trace-code-execution`, `analysis-diagnose-bug-root-cause`, `analysis-analyze-code-patterns`, `analysis-analyze-technical-document`, `analysis-review-architecture`, `analysis-review-code-quality`, `analysis-analyze-performance`, `analysis-assess-security-risks`
+
+**Planning**: `planning-plan-architecture-design`, `planning-breakdown-task-steps`, `planning-design-component-spec`, `planning-plan-migration-strategy`
+
+**Development**: `development-implement-feature`, `development-refactor-codebase`, `development-generate-tests`, `development-implement-component-ui`, `development-debug-runtime-issues`
+
+### Complete Example
+
+```bash
+maestro cli -p "PURPOSE: Identify OWASP Top 10 vulnerabilities in auth module; success = all critical/high documented with remediation
+TASK: Scan for injection flaws | Check auth bypass vectors | Evaluate session management | Assess data exposure
+MODE: analysis
+CONTEXT: @src/auth/**/* @src/middleware/auth.ts | Memory: Using bcrypt + JWT
+EXPECTED: Severity matrix, file:line references, remediation snippets, priority ranking
+CONSTRAINTS: Focus on authentication | Ignore test files
+" --tool gemini --mode analysis --rule analysis-assess-security-risks --cd "src/auth"
+```
+</context>
+
+---
+
+## 4. Execution
+
+<execution>
+
+### Execution ID
+
+ID prefix: gemini→`gem`, qwen→`qwn`, codex→`cdx`, claude→`cld`, opencode→`opc`
+
+Output to stderr: `[MAESTRO_EXEC_ID=<id>]`
+
+```bash
+maestro cli -p "<PROMPT>" --tool gemini --mode analysis    # auto-ID: gem-143022-a7f2
+maestro cli -p "<PROMPT>" --tool gemini --mode write --id my-task-1  # custom ID
+```
+
+### Session Resume
+
+```bash
+maestro cli -p "<PROMPT>" --tool gemini --resume              # last session
+maestro cli -p "<PROMPT>" --tool gemini --mode write --resume <id>  # specific
+maestro cli -p "<PROMPT>" --tool gemini --resume <id1>,<id2>     # merge multiple
+```
+
+Resume auto-assembles previous conversation context. Warning emitted when context exceeds 32KB.
+
+### Subcommands
+
+```bash
+maestro cli show                     # recent 20 executions
+maestro cli show --all               # up to 100
+maestro cli output <id>              # final assistant output
+maestro cli output <id> --verbose    # full metadata + output
+```
+</execution>
+
+---
+
+## 5. Auto-Invoke Triggers
+
+<execution>
+
+Proactively invoke `maestro cli` when these conditions are met — no user confirmation needed for `analysis` mode:
+
+| Trigger | Suggested Rule |
+|---------|---------------|
+| Self-repair fails (1+ attempts) | `analysis-diagnose-bug-root-cause` |
+| Ambiguous requirements | `planning-breakdown-task-steps` |
+| Architecture decisions needed | `planning-plan-architecture-design` |
+| Pattern uncertainty | `analysis-analyze-code-patterns` |
+| Critical/security code paths | `analysis-assess-security-risks` |
+
+### Principles
+
+- Default `--mode analysis` (safe, read-only)
+- Wait for results before next action
+- Tool fallback: `gemini` → `qwen` → `codex`
+- Rule suggestions are guidelines — choose the best fit
+</execution>

package/workflows/codebase-rebuild.md

@@ -0,0 +1,332 @@
+# Workflow: codebase-rebuild
+
+Full rebuild of the `.workflow/codebase/` documentation system.
+
+## Trigger
+
+- Manual via `/workflow:codebase-rebuild [--force] [--skip-commit]`
+- Auto-triggered by `/workflow:init` when existing code is detected
+- Auto-triggered by `/workflow:map`
+
+## Arguments
+
+| Arg | Description | Default |
+|-----|-------------|---------|
+| `--force` | Clear existing codebase/ and rebuild from scratch | `false` |
+| `--skip-commit` | Skip the final git commit of generated docs | `false` |
+
+## Prerequisites
+
+- Project source code exists (src/ or equivalent)
+- `.workflow/` directory exists
+
+---
+
+## Workflow Steps
+
+### Step 1: Prepare Directory Structure
+
+```
+Create (or clear if --force) the codebase directory:
+
+.workflow/codebase/
+  doc-index.json
+  tech-registry/
+    _index.md
+  feature-maps/
+    _index.md
+  action-logs/
+
+If directories exist and --force not set:
+  AskUserQuestion: "Codebase docs already exist. Rebuild will overwrite. Continue? [y/N]"
+  If no: exit
+```
+
+### Step 2: Scan Project Structure — Components
+
+```
+Scan src/ (and other source directories) for components:
+
+a. Identify source directories:
+   - Check for: src/, lib/, app/, packages/
+   - Use project-tech.json source_dirs if available
+
+b. For each source directory, scan for component-forming files:
+   - Directories that represent modules (contain index.ts/index.js or multiple files)
+   - Key file patterns:
+     - Models: *model*, *entity*, *schema* files
+     - Services: *service*, *provider* files
+     - Controllers: *controller*, *handler*, *route* files
+     - Utils: *util*, *helper*, *common* files
+     - Types: *type*, *interface*, *.d.ts files
+     - Config: *config*, *constant* files
+     - Middleware: *middleware*, *guard*, *interceptor* files
+     - Core: *core*, *registry*, *loader* files
+
+c. For each identified component:
+   - Read the file(s)
+   - Extract exported symbols (classes, functions, interfaces, types, constants)
+   - Determine component type (model, service, controller, util, config, middleware, core)
+   - Build component entry:
+     {
+       "id": "TC-{NNN}",          // Sequential, zero-padded 3 digits
+       "name": "{PascalCase name}",
+       "type": "{type}",
+       "code_locations": ["{relative paths}"],
+       "feature_ids": [],          // Populated in Step 3
+       "symbols": ["{exported symbol names}"],
+       "last_updated": "{ISO timestamp}"
+     }
+
+d. ID assignment: TC-001, TC-002, ... in discovery order
+```
+
+### Step 2.5: Load Project Specs
+
+```
+specs_content = maestro spec load --category planning
+```
+
+Used in Step 2-4 to produce architecture-aware documentation.
+
+---
+
+### Step 3: Scan Project Structure — Features
+
+```
+Group components by domain/functional area:
+
+a. Heuristics for grouping:
+   - Directory proximity (components in same directory = likely same feature)
+   - Naming patterns (auth.service + auth.controller + auth.model = "Authentication")
+   - Import relationships (files that import each other = related)
+   - task-specs/ requirements mapping (if available)
+
+b. For each identified feature group:
+   - Determine feature name from common prefix or directory name
+   - Collect component IDs
+   - Map to requirements if task-specs/ REQ-* files exist
+   - Determine phase association from roadmap.md if available
+   - Build feature entry:
+     {
+       "id": "FT-{NNN}",
+       "name": "{Feature Name}",
+       "status": "active",
+       "requirement_ids": [],      // From task-specs mapping
+       "component_ids": ["TC-001", "TC-002"],
+       "phase": null               // From roadmap mapping
+     }
+
+c. Back-fill component.feature_ids with the feature IDs
+```
+
+### Step 4: Map Requirements (if task-specs exist)
+
+```
+If .workflow/task-specs/ directories exist:
+  For each SPEC-*/requirements/REQ-*.md:
+    - Parse requirement metadata (title, priority, acceptance_criteria)
+    - Match to features by keyword/domain analysis
+    - Build requirement entry:
+      {
+        "id": "REQ-{NNN}",
+        "title": "{requirement title}",
+        "priority": "must|should|could|wont",
+        "feature_id": "FT-{NNN}",
+        "status": "pending|in_progress|completed",
+        "acceptance_criteria": ["{criteria}"]
+      }
+
+If no task-specs exist:
+  requirements = []  (empty, populated later by spec-generate)
+```
+
+### Step 5: Record Architecture Decisions (if ADRs exist)
+
+```
+If .workflow/task-specs/*/architecture/ADR-*.md exist:
+  For each ADR file:
+    - Parse ADR metadata (title, decision, rationale)
+    - Map to components by keyword analysis
+    - Build ADR entry:
+      {
+        "id": "ADR-{NNN}",
+        "title": "{ADR title}",
+        "component_ids": ["TC-{NNN}"],
+        "decision": "{decision summary}",
+        "rationale": "{rationale summary}"
+      }
+
+If no ADRs exist:
+  architecture_decisions = []
+```
+
+### Step 6: Write doc-index.json
+
+```
+Assemble the complete doc-index.json:
+
+{
+  "version": "1.0",
+  "schema_version": "1.0",
+  "project": "{project name from state.json or package.json}",
+  "last_updated": "{ISO timestamp}",
+  "features": [{feature entries}],
+  "components": [{component entries}],
+  "requirements": [{requirement entries}],
+  "architecture_decisions": [{ADR entries}],
+  "actions": []
+}
+
+Write to: .workflow/codebase/doc-index.json
+```
+
+### Step 7: Generate Tech Registry Docs
+
+```
+For each component in doc-index.json:
+  Compute slug: lowercase(name), replace spaces with hyphens
+
+  Write .workflow/codebase/tech-registry/{slug}.md:
+
+    # {component.name}
+
+    | Field | Value |
+    |-------|-------|
+    | **ID** | {id} |
+    | **Type** | {type} |
+    | **Features** | {feature_ids joined with ", "} |
+
+    ## Code Locations
+    {bullet list of code_locations}
+
+    ## Exported Symbols
+    {bullet list of symbols}
+
+    ## Dependencies
+    {extracted from import statements in code_locations}
+
+    ---
+    *Auto-generated by codebase-rebuild at {timestamp}*
+
+Write .workflow/codebase/tech-registry/_index.md:
+  # Tech Registry
+
+  | ID | Name | Type | Locations |
+  |----|------|------|-----------|
+  {table row per component}
+
+  ---
+  *{count} components registered*
+```
+
+### Step 8: Generate Feature Map Docs
+
+```
+For each feature in doc-index.json:
+  Compute slug: lowercase(name), replace spaces with hyphens
+
+  Write .workflow/codebase/feature-maps/{slug}.md:
+
+    # {feature.name}
+
+    | Field | Value |
+    |-------|-------|
+    | **ID** | {id} |
+    | **Status** | {status} |
+    | **Phase** | {phase or "unassigned"} |
+
+    ## Requirements
+    {bullet list of requirement_ids with titles}
+
+    ## Components
+    | ID | Name | Type |
+    |----|------|------|
+    {table row per component in component_ids}
+
+    ---
+    *Auto-generated by codebase-rebuild at {timestamp}*
+
+Write .workflow/codebase/feature-maps/_index.md:
+  # Feature Maps
+
+  | ID | Name | Status | Components | Requirements |
+  |----|------|--------|------------|--------------|
+  {table row per feature}
+
+  ---
+  *{count} features mapped*
+```
+
+### Step 8.5: Update State and Project Artifacts
+
+```
+a. Update state.json:
+   Read .workflow/state.json
+   Set last_codebase_rebuild: "{ISO timestamp}"
+   Set last_updated: "{ISO timestamp}"
+   Write updated state.json
+
+b. Update project-tech.json (if exists):
+   Read .workflow/project-tech.json
+   Compare detected tech stack (from Step 2 scan) against existing entries:
+     - New languages, frameworks, databases, tools discovered
+     - Version changes detected (from package.json, go.mod, pyproject.toml, etc.)
+   If differences found:
+     Update project-tech.json with current detected stack
+     Display: "project-tech.json: updated with {count} changes"
+
+c. Update project.md Tech Stack (if exists):
+   Read .workflow/project.md
+   Compare "## Tech Stack" section against detected stack from Step 2
+   If new entries or changes detected:
+     Update the Tech Stack section with current values
+     Update the "Last updated" footer timestamp
+     Write updated project.md
+     Display: "project.md: Tech Stack section refreshed"
+```
+
+### Step 9: Report and Commit
+
+```
+Display summary:
+  Codebase rebuild complete:
+    Components: {count}
+    Features: {count}
+    Requirements: {count}
+    ADRs: {count}
+    Files generated: {count}
+
+If any mapper agents failed: log W001 with the failed mapper name.
+
+If not --skip-commit:
+  Suggest committing the generated docs
+
+Suggest next:
+  - Skill({ skill: "manage-status" }) to review
+  - Skill({ skill: "manage-codebase-refresh" }) for future incremental updates
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No source directories found | Warn and create empty doc-index.json |
+| .workflow/ missing | Fail: "Run /workflow:init first" |
+| File read errors | Log warning, skip file, continue scan |
+| Existing codebase/ without --force | Prompt user for confirmation |
+
+## Output Files
+
+| File | Description |
+|------|-------------|
+| `.workflow/codebase/doc-index.json` | Single source of truth for all components/features/requirements |
+| `.workflow/codebase/tech-registry/_index.md` | Component index |
+| `.workflow/codebase/tech-registry/{slug}.md` | Per-component documentation |
+| `.workflow/codebase/feature-maps/_index.md` | Feature index |
+| `.workflow/codebase/feature-maps/{slug}.md` | Per-feature documentation |
+| `.workflow/state.json` | Updated: last_codebase_rebuild timestamp |
+| `.workflow/project-tech.json` | Updated: detected tech stack changes |
+| `.workflow/project.md` | Updated: Tech Stack section refreshed |