maestro-flow 0.3.15 → 0.3.17

package/workflows/brainstorm.md

@@ -126,16 +126,7 @@ Parse $ARGUMENTS to determine execution mode:
 - None + single role mode → error E002
 
 **Output Directory Resolution**:
-- Phase mode (number):
-  ```
-  Read .workflow/state.json → state
-  artifacts = state.artifacts ?? []
-  art = artifacts.find(a => a.phase === phaseNum)
-  IF art:
-    output_dir = ".workflow/" + art.path + "/.brainstorming/"
-  ELSE:
-    ERROR "Phase {phaseNum} not found in artifact registry"
-  ```
+- Phase mode (number): resolve `state.json.artifacts[phase == phaseNum].path` → `.workflow/{path}/.brainstorming/` (ERROR if phase not found)
 - All output: `.workflow/scratch/brainstorm-{slug}-{date}/`
 - Existing session: use existing session directory
 
@@ -210,19 +201,8 @@ If research fails (W005): `designResearchContext = null`, continue without exter
 
 Load existing project history to ground brainstorming in what's already been built:
 
-```
-IF .workflow/project.md exists:
-  Read project.md:
-    - "### Validated" → already_shipped (features already delivered)
-    - "### Active" → current_scope
-    - "## Context" → project_history (milestone summaries)
-
-IF .workflow/state.json exists:
-  Read state.json.accumulated_context:
-    - deferred[] → deferred_items (candidates for brainstorming focus)
-    - key_decisions[] → existing_constraints
-
-```
+- From `.workflow/project.md`: `### Validated` → already_shipped, `### Active` → current_scope, `## Context` → project_history
+- From `.workflow/state.json.accumulated_context`: `deferred[]` → deferred_items, `key_decisions[]` → existing_constraints
 
 Pass `project_context` into Step 2 (terminology) and Step 3 (framework generation):
 - `already_shipped` informs what exists — brainstorm should explore extensions, not re-invent

package/workflows/codebase-rebuild.md

@@ -27,58 +27,35 @@ Full rebuild of the `.workflow/codebase/` documentation system.
 ### 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
+Create (or clear if --force) .workflow/codebase/:
+  doc-index.json, tech-registry/_index.md, feature-maps/_index.md, action-logs/
+
+If exists and not --force: confirm overwrite or 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/
-   - Read project.md Tech Stack section if available for context
-
-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
+Scan source directories (src/, lib/, app/, packages/) for components.
+Use project.md Tech Stack for context if available.
+
+Classify files by naming pattern:
+  Models (*model*, *entity*, *schema*), Services (*service*, *provider*),
+  Controllers (*controller*, *handler*, *route*), Utils (*util*, *helper*),
+  Types (*type*, *interface*, *.d.ts), Config (*config*, *constant*),
+  Middleware (*middleware*, *guard*, *interceptor*), Core (*core*, *registry*, *loader*)
+
+For each component: read files, extract exported symbols, determine type.
+Build component entry:
+  {
+    "id": "TC-{NNN}",              // Sequential TC-001, TC-002, ...
+    "name": "{PascalCase name}",
+    "type": "{type}",
+    "code_locations": ["{relative paths}"],
+    "feature_ids": [],              // Populated in Step 3
+    "symbols": ["{exported symbol names}"],
+    "last_updated": "{ISO timestamp}"
+  }
 ```
 
 ### Step 2.5: Load Project Specs
@@ -94,71 +71,54 @@ 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
+Group components into features by:
+  directory proximity, naming patterns, import relationships, task-specs/ mapping.
+
+For each feature group: derive name, collect component IDs, map requirements and phase.
+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
+  }
+
+Back-fill component.feature_ids with assigned 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)
+If .workflow/task-specs/ exist: parse each SPEC-*/requirements/REQ-*.md,
+match to features by keyword 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: requirements = [] (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 = []
+If .workflow/task-specs/*/architecture/ADR-*.md exist: parse each ADR,
+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: architecture_decisions = [].
 ```
 
 ### Step 6: Write doc-index.json
@@ -184,118 +144,46 @@ 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}
+For each component (slug = lowercase-hyphenated name):
 
-    ## 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/{slug}.md:
+  Header table (ID, Type, Features) + sections: Code Locations, Exported Symbols, Dependencies.
+  Footer: *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*
+  Summary table (ID, Name, Type, Locations) + component count footer.
 ```
 
 ### 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}
+For each feature (slug = lowercase-hyphenated 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/{slug}.md:
+  Header table (ID, Status, Phase) + sections: Requirements, Components table.
+  Footer: *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*
+  Summary table (ID, Name, Status, Components, Requirements) + feature count footer.
 ```
 
 ### 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
+a. Update state.json: set last_codebase_rebuild and last_updated timestamps.
 
 b. 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"
+   Compare "## Tech Stack" against detected stack from Step 2.
+   If changes detected: update section + footer timestamp.
 ```
 
 ### 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
+Display summary: component/feature/requirement/ADR/file counts.
+If mapper agents failed: log W001.
+If not --skip-commit: suggest committing generated docs.
+Suggest next: manage-status (review) or manage-codebase-refresh (incremental updates).
 ```
 
 ---

package/workflows/codebase-refresh.md

@@ -28,40 +28,25 @@ Detects which files have changed (via git diff), identifies which codebase docs
 ### Step 1: Parse Input and Validate
 
 ```
-Parse $ARGUMENTS for --since and --deep flags.
-
-Verify .workflow/ directory exists and is initialized (project.md, state.json present).
-  If not initialized: abort with E001.
-
-Verify .workflow/codebase/doc-index.json exists.
-  If not: abort with E002 (suggest using codebase-rebuild instead).
+Parse --since and --deep flags from $ARGUMENTS.
+Verify .workflow/ initialized (E001 if not) and doc-index.json exists (E002 if not).
 ```
 
 ### Step 2: Detect Changes
 
 ```
-Determine the change detection window:
-  If --since provided: use that date/ref
-  Otherwise: use codebase_last_rebuilt or codebase_last_refreshed from state.json
-
-Run git diff --name-only since the determined date to get list of changed files.
-
-If no changes detected: emit W001 and exit gracefully ("No changes detected since last refresh").
+Change window: --since value, else codebase_last_rebuilt/codebase_last_refreshed from state.json.
+Run git diff --name-only to get changed files.
+If no changes: emit W001 and exit.
 ```
 
 ### Step 3: Identify Affected Documentation
 
 ```
-Read .workflow/codebase/doc-index.json to map changed files to documentation entries.
-
-For each changed file, identify which doc-index entries reference it:
-  - Which tech-registry components are affected (via code_locations matching)
-  - Which feature-map entries need updating (via component -> feature chain)
-  - Which requirements or ADRs reference changed code
-
-Build a list of affected documentation sections:
-  affected_components = [component entries whose code_locations include changed files]
-  affected_features = [features whose component_ids include affected components]
+Map changed files to doc-index.json entries via code_locations matching.
+Build affected sets:
+  affected_components = components whose code_locations include changed files
+  affected_features = features whose component_ids include affected components
 ```
 
 ### Step 3.5: Load Project Specs
@@ -77,138 +62,55 @@ Used in Step 4-5 to validate refreshed docs against architectural expectations.
 ### Step 4: Re-scan Affected Components
 
 ```
-For each component in affected_components:
-  For each file_path in component.code_locations:
-    a. Check if file still exists
-       If not: mark for removal from code_locations, log warning
+For each affected component:
+  - Verify code_locations still exist (remove missing, log warning)
+  - Re-extract exported symbols (ESM export + CJS module.exports patterns)
+  - Update symbols[] and last_updated timestamp
 
-    b. Read file content
-       Extract exported symbols:
-         - export class {Name}
-         - export function {name}
-         - export interface {Name}
-         - export type {Name}
-         - export const {NAME}
-         - export default {name/class}
-         - module.exports patterns (for CJS)
+If --deep: follow reverse dependency chain to find additional affected components.
 
-    c. Update component entry:
-       - symbols = [newly extracted symbols]
-       - last_updated = current ISO timestamp
-
-  If --deep is set, also re-scan files that import/require the changed files
-  (follow reverse dependency chain to find additional affected components).
-
-  Check for new files that should belong to this component:
-    - Scan same directory as existing code_locations
-    - If new files match the component's naming pattern:
-      Log: "Potential new file for {component.id}: {file}"
-      (Do not auto-add; report for manual review)
+Report new files matching component naming patterns (do not auto-add).
 ```
 
 ### Step 5: Check Relationship Changes
 
 ```
 For each refreshed component:
-  Read import statements from code_locations files
-  Identify imported modules that map to other components
-
-  Compare with current feature_ids:
-    If a component imports from a different feature's components:
-      Log: "Cross-feature dependency detected: {component.id} -> {other_component.id}"
+  Analyze imports to detect cross-feature dependencies (log if found).
 
 For each refreshed feature:
-  Verify all component_ids still exist in components[]
-  Remove any stale component_ids
-  Check if new components should be added (by directory proximity)
+  Remove stale component_ids, check for new components by directory proximity.
 ```
 
 ### Step 6: Update Doc Index
 
 ```
-Write updated entries back to doc-index.json:
-  - Updated component entries (symbols, code_locations, last_updated)
-  - Updated feature entries (component_ids, last_updated)
-  - Update top-level last_updated timestamp
-  - Update global last_refreshed timestamp
-
-Write: .workflow/codebase/doc-index.json
+Write updated component/feature entries + timestamps to .workflow/codebase/doc-index.json.
 ```
 
 ### Step 7: Regenerate Affected Docs
 
 ```
-For each refreshed component:
-  Compute slug from component.name
-  Regenerate: .workflow/codebase/tech-registry/{slug}.md
-
-    # {component.name}
+For each refreshed component: regenerate tech-registry/{slug}.md
+  (header table + Code Locations + Exported Symbols + refresh timestamp).
 
-    | Field | Value |
-    |-------|-------|
-    | **ID** | {id} |
-    | **Type** | {type} |
-    | **Features** | {feature_ids joined} |
+For each refreshed feature: regenerate feature-maps/{slug}.md
+  (header table + Components table + Requirements + refresh timestamp).
 
-    ## Code Locations
-    {bullet list of code_locations}
-
-    ## Exported Symbols
-    {bullet list of symbols}
-
-    ---
-    *Refreshed at {timestamp}*
-
-For each refreshed feature:
-  Compute slug from feature.name
-  Regenerate: .workflow/codebase/feature-maps/{slug}.md
-
-    # {feature.name}
-
-    | Field | Value |
-    |-------|-------|
-    | **ID** | {id} |
-    | **Status** | {status} |
-    | **Phase** | {phase or "unassigned"} |
-
-    ## Components
-    | ID | Name | Type |
-    |----|------|------|
-    {table row per component}
-
-    ## Requirements
-    {bullet list of requirement_ids with titles}
-
-    ---
-    *Refreshed at {timestamp}*
-
-Update _index.md files if any entries changed:
-  Regenerate tech-registry/_index.md
-  Regenerate feature-maps/_index.md
+If entries changed: regenerate tech-registry/_index.md and feature-maps/_index.md.
 ```
 
 ### Step 8: Update Timestamps
 
 ```
-Update .workflow/state.json:
-  - Set codebase_last_refreshed timestamp
-  - Update last_updated timestamp
+Update .workflow/state.json: set codebase_last_refreshed and last_updated timestamps.
 ```
 
 ### Step 9: Report
 
 ```
-Display summary:
-  Refresh complete:
-    Changed files detected: {count}
-    Components refreshed: {count} ({IDs})
-    Features refreshed: {count} ({IDs})
-    Symbols updated: {count new} added, {count removed} removed
-    Files updated in .workflow/codebase/: {list}
-    Warnings: {any warnings from Steps 4-5}
-    If W001: "No changes detected since last refresh"
-
-  Suggest next: Skill({ skill: "manage-status" }) to review
+Display summary: changed files, components/features refreshed, symbols added/removed, warnings.
+Suggest next: manage-status to review.
 ```
 
 ---