maestro-flow 0.5.36 → 0.5.38

package/.agy/skills/spec-remove/SKILL.md

@@ -10,45 +10,45 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<purpose>
-Remove a `<spec-entry>` from a specs file. Symmetric with `/spec-add`.
-Uses `maestro wiki remove-entry` for atomic removal with index auto-update.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-remove.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-conventions-001`)
-
-**Entry ID format**: `spec-{file-stem}-{NNN}` — the sub-node ID assigned by WikiIndexer when indexing `<spec-entry>` blocks.
-
-**Discovery**: Use `maestro wiki list --type spec --json` or `/spec-load --keyword <term>` to find entry IDs.
-
-**Flags:**
-- `--cascade` — When the target spec is a ref-type entry (created via `spec-add --ref` and linked to a knowhow document), also delete the referenced knowhow file. Without this flag, ref-type removal leaves an orphan knowhow file.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/specs-remove.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | Entry ID is required -- usage: `/spec-remove <entry-id>` | parse_input |
-| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate |
-| E003 | fatal | Entry ID not found in wiki index | lookup |
-| E004 | fatal | Entry is not a spec sub-node (wrong type) | validate |
-</error_codes>
-
-<success_criteria>
-- [ ] Entry ID parsed and validated
-- [ ] Entry found in wiki index (type=spec, is sub-node)
-- [ ] User confirmed removal (unless -y flag)
-- [ ] Entry removed from container file via `maestro wiki remove-entry`
-- [ ] Wiki index auto-updated
-- [ ] If `--cascade` and entry has a `ref` attribute: referenced knowhow file deleted, orphan avoided
-- [ ] Confirmation displayed with removed entry details (and cascaded knowhow path if applicable)
-</success_criteria>
+<purpose>
+Remove a `<spec-entry>` from a specs file. Symmetric with `/spec-add`.
+Uses `maestro wiki remove-entry` for atomic removal with index auto-update.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-remove.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-conventions-001`)
+
+**Entry ID format**: `spec-{file-stem}-{NNN}` — the sub-node ID assigned by WikiIndexer when indexing `<spec-entry>` blocks.
+
+**Discovery**: Use `maestro wiki list --type spec --json` or `/spec-load --keyword <term>` to find entry IDs.
+
+**Flags:**
+- `--cascade` — When the target spec is a ref-type entry (created via `spec-add --ref` and linked to a knowhow document), also delete the referenced knowhow file. Without this flag, ref-type removal leaves an orphan knowhow file.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-remove.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Entry ID is required -- usage: `/spec-remove <entry-id>` | parse_input |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate |
+| E003 | fatal | Entry ID not found in wiki index | lookup |
+| E004 | fatal | Entry is not a spec sub-node (wrong type) | validate |
+</error_codes>
+
+<success_criteria>
+- [ ] Entry ID parsed and validated
+- [ ] Entry found in wiki index (type=spec, is sub-node)
+- [ ] User confirmed removal (unless -y flag)
+- [ ] Entry removed from container file via `maestro wiki remove-entry`
+- [ ] Wiki index auto-updated
+- [ ] If `--cascade` and entry has a `ref` attribute: referenced knowhow file deleted, orphan avoided
+- [ ] Confirmation displayed with removed entry details (and cascaded knowhow path if applicable)
+</success_criteria>

package/.agy/skills/spec-setup/SKILL.md

@@ -8,40 +8,40 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<purpose>
-Initialize `.workflow/specs/` by scanning codebase for conventions. Core files always created; optional files created when signals detected. Also generates recipe knowhow for detected workflows.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-setup.md
-</required_reading>
-
-<context>
-$ARGUMENTS (no arguments expected)
-
-**Preconditions:**
-- `.workflow/` directory must exist (created by `/maestro-init`)  # (see code: E001)
-- Project must contain source files to scan  # (see code: E002)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/specs-setup.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | `.workflow/` directory not initialized -- run `/maestro-init` first | parse_input |
-| E002 | fatal | No source files found in project -- nothing to scan | scan_codebase |
-| W001 | warning | Convention detection uncertain for one or more categories -- marked `[UNCERTAIN]` | generate_specs |
-| W002 | warning | Workflow recipe signals detected but commands ambiguous -- recipe skipped | generate_recipes |
-| W003 | warning | Existing recipe slug found -- new content written as `.proposed.md` for manual diff | generate_recipes |
-</error_codes>
-
-<success_criteria>
-- [ ] `.workflow/specs/` directory created
-- [ ] Core spec files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
-- [ ] Optional spec files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `ui-conventions.md` (frontend framework). `debug-notes.md` / `review-standards.md` deferred (on demand via `/spec-add`).
-- [ ] Workflow recipe knowhow created in `.workflow/knowhow/` for each detected operational workflow (test / debug / build / dev / lint). Each recipe matches the `recipe` schema in `~/.maestro/workflows/knowhow.md` Part B and contains at least one runnable command.
-- [ ] Report displayed grouped by destination (specs / recipes / skipped / deferred), with `.proposed.md` files surfaced when an existing recipe slug was preserved.
-</success_criteria>
+<purpose>
+Initialize `.workflow/specs/` by scanning codebase for conventions. Core files always created; optional files created when signals detected. Also generates recipe knowhow for detected workflows.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-setup.md
+</required_reading>
+
+<context>
+$ARGUMENTS (no arguments expected)
+
+**Preconditions:**
+- `.workflow/` directory must exist (created by `/maestro-init`)  # (see code: E001)
+- Project must contain source files to scan  # (see code: E002)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-setup.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` directory not initialized -- run `/maestro-init` first | parse_input |
+| E002 | fatal | No source files found in project -- nothing to scan | scan_codebase |
+| W001 | warning | Convention detection uncertain for one or more categories -- marked `[UNCERTAIN]` | generate_specs |
+| W002 | warning | Workflow recipe signals detected but commands ambiguous -- recipe skipped | generate_recipes |
+| W003 | warning | Existing recipe slug found -- new content written as `.proposed.md` for manual diff | generate_recipes |
+</error_codes>
+
+<success_criteria>
+- [ ] `.workflow/specs/` directory created
+- [ ] Core spec files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
+- [ ] Optional spec files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `ui-conventions.md` (frontend framework). `debug-notes.md` / `review-standards.md` deferred (on demand via `/spec-add`).
+- [ ] Workflow recipe knowhow created in `.workflow/knowhow/` for each detected operational workflow (test / debug / build / dev / lint). Each recipe matches the `recipe` schema in `~/.maestro/workflows/knowhow.md` Part B and contains at least one runnable command.
+- [ ] Report displayed grouped by destination (specs / recipes / skipped / deferred), with `.proposed.md` files surfaced when an existing recipe slug was preserved.
+</success_criteria>

package/.agy/skills/team-arch-opt/SKILL.md

@@ -1,6 +1,18 @@
 ---
 name: team-arch-opt
 description: Unified team skill for architecture optimization. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team arch-opt".
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - mcp__maestro__team_msg
+  - replace_file_content
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
 agy-subagents:
   - team-worker
 ---
@@ -16,133 +28,133 @@ Before any `invoke_subagent` call below, register each sub-agent type once per s
 **ConversationId tracking**: `invoke_subagent` returns a ConversationId per spawned instance. Subsequent `send_message(Recipient=<ConversationId>, Message=...)` calls require that ConversationId — never use the role name as the recipient.
 
 ---
-
-# Team Architecture Optimization
-
-Orchestrate multi-agent architecture optimization: analyze codebase → design refactoring plan → implement changes → validate improvements → review code quality.
-
-## Architecture
-
-```
-view_file(AbsolutePath="<agy-skills-dir>/team-arch-opt/SKILL.md") + execute inline (args: "task description")
-                    |
-         SKILL.md (this file) = Router
-                    |
-     +--------------+--------------+
-     |                             |
-  no --role flag              --role <name>
-     |                             |
-  Coordinator                  Worker
-  roles/coordinator/role.md    roles/<name>/role.md
-     |
-     +-- analyze → dispatch → spawn workers → STOP
-                                    |
-                    +-------+-------+-------+-------+
-                    v       v       v       v       v
-                 [analyzer][designer][refactorer][validator][reviewer]
-```
-
-## Role Registry
-
-| Role | Path | Prefix | Inner Loop |
-|------|------|--------|------------|
-| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
-| analyzer | [roles/analyzer/role.md](roles/analyzer/role.md) | ANALYZE-* | false |
-| designer | [roles/designer/role.md](roles/designer/role.md) | DESIGN-* | false |
-| refactorer | [roles/refactorer/role.md](roles/refactorer/role.md) | REFACTOR-*, FIX-* | true |
-| validator | [roles/validator/role.md](roles/validator/role.md) | VALIDATE-* | false |
-| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-*, QUALITY-* | false |
-
-
-## Pre-load (coordinator, before dispatch)
-
-1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for module boundaries
-2. **Specs (arch)**: `maestro spec load --category arch` — load arch constraints as shared context
-3. **Specs (coding)**: `maestro spec load --category coding` — load coding constraints as shared context
-4. **Wiki knowledge**: `maestro search "architecture optimization refactor" --json` — top 5 entries as prior context
-5. All optional — proceed without if unavailable
-## Role Router
-
-Parse `$ARGUMENTS`:
-- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → `@roles/coordinator/role.md`, execute entry router
-
-## Shared Constants
-
-- **Session prefix**: `TAO`
-- **Session path**: `.workflow/.team/TAO-<slug>-<date>/`
-- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
-- **Message bus**: `mcp__maestro__team_msg(session_id=<session-id>, ...)`
-
-## Worker Spawn Template
-
-Coordinator spawns workers using this template:
-
-```
-invoke_subagent([{ TypeName: "team-worker", Role: "<role>", Prompt: "<Prompt>", Workspace: "inherit" }])
-```
-
-**Inner Loop roles** (refactorer): Set `inner_loop` dynamically — `true` for single mode, `false` for fan-out/independent (parallel branches).
-**Single-task roles** (analyzer, designer, validator, reviewer): Set `inner_loop: false`.
-
-## User Commands
-
-| Command | Action |
-|---------|--------|
-| `check` / `status` | View execution status graph (branch-grouped), no advancement |
-| `resume` / `continue` | Check worker states, advance next step |
-| `revise <TASK-ID> [feedback]` | Revise specific task + cascade downstream |
-| `feedback <text>` | Analyze feedback impact, create targeted revision chain |
-| `recheck` | Re-run quality check |
-| `improve [dimension]` | Auto-improve weakest dimension |
-
-## Session Directory
-
-```
-.workflow/.team/TAO-<slug>-<date>/
-├── session.json                    # Session metadata + status + parallel_mode
-├── task-analysis.json              # Coordinator analyze output
-├── artifacts/
-│   ├── architecture-baseline.json  # Analyzer: pre-refactoring metrics
-│   ├── architecture-report.md      # Analyzer: ranked structural issue findings
-│   ├── refactoring-plan.md         # Designer: prioritized refactoring plan
-│   ├── validation-results.json     # Validator: post-refactoring validation
-│   ├── review-report.md            # Reviewer: code review findings
-│   ├── aggregate-results.json      # Fan-out/independent: aggregated results
-│   ├── branches/                   # Fan-out mode branch artifacts
-│   │   └── B{NN}/
-│   │       ├── refactoring-detail.md
-│   │       ├── validation-results.json
-│   │       └── review-report.md
-│   └── pipelines/                  # Independent mode pipeline artifacts
-│       └── {P}/
-│           └── ...
-├── explorations/
-│   ├── cache-index.json            # Shared explore cache
-│   └── <hash>.md
-├── wisdom/
-│   └── patterns.md                 # Discovered patterns and conventions
-├── discussions/
-│   ├── DISCUSS-REFACTOR.md
-│   └── DISCUSS-REVIEW.md
-└── .msg/
-    ├── messages.jsonl              # Message bus log
-    └── meta.json                   # Session state + cross-role state
-```
-
-## Specs Reference
-
-- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions, task registry, parallel modes
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| Unknown command | Error with available command list |
-| Role not found | Error with role registry |
-| CLI tool fails | Worker fallback to direct implementation |
-| Fast-advance conflict | Coordinator reconciles on next callback |
-| Completion action fails | Default to Keep Active |
-| consensus_blocked HIGH | Coordinator creates revision task or pauses pipeline |
-| Branch fix cycle >= 3 | Escalate only that branch to user, others continue |
-| max_branches exceeded | Coordinator truncates to top N at CP-2.5 |
+
+# Team Architecture Optimization
+
+Orchestrate multi-agent architecture optimization: analyze codebase → design refactoring plan → implement changes → validate improvements → review code quality.
+
+## Architecture
+
+```
+view_file(AbsolutePath="<agy-skills-dir>/team-arch-opt/SKILL.md") + execute inline (args: "task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- analyze → dispatch → spawn workers → STOP
+                                    |
+                    +-------+-------+-------+-------+
+                    v       v       v       v       v
+                 [analyzer][designer][refactorer][validator][reviewer]
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
+| analyzer | [roles/analyzer/role.md](roles/analyzer/role.md) | ANALYZE-* | false |
+| designer | [roles/designer/role.md](roles/designer/role.md) | DESIGN-* | false |
+| refactorer | [roles/refactorer/role.md](roles/refactorer/role.md) | REFACTOR-*, FIX-* | true |
+| validator | [roles/validator/role.md](roles/validator/role.md) | VALIDATE-* | false |
+| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-*, QUALITY-* | false |
+
+
+## Pre-load (coordinator, before dispatch)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for module boundaries
+2. **Specs (arch)**: `maestro load --type spec --category arch` — load arch constraints as shared context
+3. **Specs (coding)**: `maestro load --type spec --category coding` — load coding constraints as shared context
+4. **Wiki knowledge**: `maestro search "architecture optimization refactor" --json` — top 5 entries as prior context
+5. All optional — proceed without if unavailable
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
+
+## Shared Constants
+
+- **Session prefix**: `TAO`
+- **Session path**: `.workflow/.team/TAO-<slug>-<date>/`
+- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
+- **Message bus**: `mcp__maestro__team_msg(session_id=<session-id>, ...)`
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+invoke_subagent([{ TypeName: "team-worker", Role: "<role>", Prompt: "<Prompt>", Workspace: "inherit" }])
+```
+
+**Inner Loop roles** (refactorer): Set `inner_loop` dynamically — `true` for single mode, `false` for fan-out/independent (parallel branches).
+**Single-task roles** (analyzer, designer, validator, reviewer): Set `inner_loop: false`.
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph (branch-grouped), no advancement |
+| `resume` / `continue` | Check worker states, advance next step |
+| `revise <TASK-ID> [feedback]` | Revise specific task + cascade downstream |
+| `feedback <text>` | Analyze feedback impact, create targeted revision chain |
+| `recheck` | Re-run quality check |
+| `improve [dimension]` | Auto-improve weakest dimension |
+
+## Session Directory
+
+```
+.workflow/.team/TAO-<slug>-<date>/
+├── session.json                    # Session metadata + status + parallel_mode
+├── task-analysis.json              # Coordinator analyze output
+├── artifacts/
+│   ├── architecture-baseline.json  # Analyzer: pre-refactoring metrics
+│   ├── architecture-report.md      # Analyzer: ranked structural issue findings
+│   ├── refactoring-plan.md         # Designer: prioritized refactoring plan
+│   ├── validation-results.json     # Validator: post-refactoring validation
+│   ├── review-report.md            # Reviewer: code review findings
+│   ├── aggregate-results.json      # Fan-out/independent: aggregated results
+│   ├── branches/                   # Fan-out mode branch artifacts
+│   │   └── B{NN}/
+│   │       ├── refactoring-detail.md
+│   │       ├── validation-results.json
+│   │       └── review-report.md
+│   └── pipelines/                  # Independent mode pipeline artifacts
+│       └── {P}/
+│           └── ...
+├── explorations/
+│   ├── cache-index.json            # Shared explore cache
+│   └── <hash>.md
+├── wisdom/
+│   └── patterns.md                 # Discovered patterns and conventions
+├── discussions/
+│   ├── DISCUSS-REFACTOR.md
+│   └── DISCUSS-REVIEW.md
+└── .msg/
+    ├── messages.jsonl              # Message bus log
+    └── meta.json                   # Session state + cross-role state
+```
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions, task registry, parallel modes
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| CLI tool fails | Worker fallback to direct implementation |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |
+| consensus_blocked HIGH | Coordinator creates revision task or pauses pipeline |
+| Branch fix cycle >= 3 | Escalate only that branch to user, others continue |
+| max_branches exceeded | Coordinator truncates to top N at CP-2.5 |

package/.agy/skills/team-arch-opt/roles/analyzer/role.md

@@ -2,84 +2,85 @@
 role: analyzer
 prefix: ANALYZE
 inner_loop: false
+message_types: [state_update]
 ---
-
-# Architecture Analyzer
-
-Analyze codebase architecture to identify structural issues: dependency cycles, coupling/cohesion problems, layering violations, God Classes, code duplication, dead code, and API surface bloat. Produce quantified baseline metrics and a ranked architecture report.
-
-## Phase 2: Context & Environment Detection
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
-
-1. Extract session path and target scope from task description
-2. Detect project type by scanning for framework markers:
-
-| Signal File | Project Type | Analysis Focus |
-|-------------|-------------|----------------|
-| package.json + React/Vue/Angular | Frontend | Component tree, prop drilling, state management, barrel exports |
-| package.json + Express/Fastify/NestJS | Backend Node | Service layer boundaries, middleware chains, DB access patterns |
-| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | Module boundaries, trait/interface usage, dependency injection |
-| Mixed framework markers | Full-stack / Monorepo | Cross-package dependencies, shared types, API contracts |
-| CLI entry / bin/ directory | CLI Tool | Command structure, plugin architecture, configuration layering |
-| No detection | Generic | All architecture dimensions |
-
-3. Use `explore` CLI tool to map module structure, dependency graph, and layer boundaries within target scope
-4. Detect available analysis tools (linters, dependency analyzers, build tools)
-
-## Phase 3: Architecture Analysis
-
-Execute analysis based on detected project type:
-
-**Dependency analysis**:
-- Build import/require graph across modules
-- Detect circular dependencies (direct and transitive cycles)
-- Identify layering violations (e.g., UI importing from data layer, utils importing from domain)
-- Calculate fan-in/fan-out per module (high fan-out = fragile hub, high fan-in = tightly coupled)
-
-**Structural analysis**:
-- Identify God Classes / God Modules (> 500 LOC, > 10 public methods, too many responsibilities)
-- Calculate coupling metrics (afferent/efferent coupling per module)
-- Calculate cohesion metrics (LCOM -- Lack of Cohesion of Methods)
-- Detect code duplication (repeated logic blocks, copy-paste patterns)
-- Identify missing abstractions (repeated conditionals, switch-on-type patterns)
-
-**API surface analysis**:
-- Count exported symbols per module (export bloat detection)
-- Identify dead exports (exported but never imported elsewhere)
-- Detect dead code (unreachable functions, unused variables, orphan files)
-- Check for pattern inconsistencies (mixed naming conventions, inconsistent error handling)
-
-**All project types**:
-- Collect quantified architecture baseline metrics (dependency count, cycle count, coupling scores, LOC distribution)
-- Rank top 3-7 architecture issues by severity (Critical / High / Medium)
-- Record evidence: file paths, line numbers, measured values
-
-### Tech Profile Scan
-
-After analysis, scan findings for context-aware trigger signals (based on detected codebase characteristics):
-
-1. Check dependency analysis → signals (`sql_detected`, `auth_detected`, `ml_detected`)
-2. Check structural analysis → risk signals (`perf_sensitive`, `legacy_patterns`, `scaling_concern`)
-3. Include `tech_profile` in Phase 5 state_update data
-
-## Phase 4: Report Generation
-
-1. Write architecture baseline to `<session>/artifacts/architecture-baseline.json`:
-   - Module count, dependency count, cycle count, average coupling, average cohesion
-   - God Class candidates with LOC and method count
-   - Dead code file count, dead export count
-   - Timestamp and project type details
-
-2. Write architecture report to `<session>/artifacts/architecture-report.md`:
-   - Ranked list of architecture issues with severity, location (file:line or module), measured impact
-   - Issue categories: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT
-   - Evidence summary per issue
-   - Detected project type and analysis methods used
-
-3. Update `<session>/wisdom/.msg/meta.json` under `analyzer` namespace:
-   - Read existing -> merge `{ "analyzer": { project_type, issue_count, top_issue, scope, categories } }` -> write back
+
+# Architecture Analyzer
+
+Analyze codebase architecture to identify structural issues: dependency cycles, coupling/cohesion problems, layering violations, God Classes, code duplication, dead code, and API surface bloat. Produce quantified baseline metrics and a ranked architecture report.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and target scope from task description
+2. Detect project type by scanning for framework markers:
+
+| Signal File | Project Type | Analysis Focus |
+|-------------|-------------|----------------|
+| package.json + React/Vue/Angular | Frontend | Component tree, prop drilling, state management, barrel exports |
+| package.json + Express/Fastify/NestJS | Backend Node | Service layer boundaries, middleware chains, DB access patterns |
+| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | Module boundaries, trait/interface usage, dependency injection |
+| Mixed framework markers | Full-stack / Monorepo | Cross-package dependencies, shared types, API contracts |
+| CLI entry / bin/ directory | CLI Tool | Command structure, plugin architecture, configuration layering |
+| No detection | Generic | All architecture dimensions |
+
+3. Use `explore` CLI tool to map module structure, dependency graph, and layer boundaries within target scope
+4. Detect available analysis tools (linters, dependency analyzers, build tools)
+
+## Phase 3: Architecture Analysis
+
+Execute analysis based on detected project type:
+
+**Dependency analysis**:
+- Build import/require graph across modules
+- Detect circular dependencies (direct and transitive cycles)
+- Identify layering violations (e.g., UI importing from data layer, utils importing from domain)
+- Calculate fan-in/fan-out per module (high fan-out = fragile hub, high fan-in = tightly coupled)
+
+**Structural analysis**:
+- Identify God Classes / God Modules (> 500 LOC, > 10 public methods, too many responsibilities)
+- Calculate coupling metrics (afferent/efferent coupling per module)
+- Calculate cohesion metrics (LCOM -- Lack of Cohesion of Methods)
+- Detect code duplication (repeated logic blocks, copy-paste patterns)
+- Identify missing abstractions (repeated conditionals, switch-on-type patterns)
+
+**API surface analysis**:
+- Count exported symbols per module (export bloat detection)
+- Identify dead exports (exported but never imported elsewhere)
+- Detect dead code (unreachable functions, unused variables, orphan files)
+- Check for pattern inconsistencies (mixed naming conventions, inconsistent error handling)
+
+**All project types**:
+- Collect quantified architecture baseline metrics (dependency count, cycle count, coupling scores, LOC distribution)
+- Rank top 3-7 architecture issues by severity (Critical / High / Medium)
+- Record evidence: file paths, line numbers, measured values
+
+### Tech Profile Scan
+
+After analysis, scan findings for context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check dependency analysis → signals (`sql_detected`, `auth_detected`, `ml_detected`)
+2. Check structural analysis → risk signals (`perf_sensitive`, `legacy_patterns`, `scaling_concern`)
+3. Include `tech_profile` in Phase 5 state_update data
+
+## Phase 4: Report Generation
+
+1. Write architecture baseline to `<session>/artifacts/architecture-baseline.json`:
+   - Module count, dependency count, cycle count, average coupling, average cohesion
+   - God Class candidates with LOC and method count
+   - Dead code file count, dead export count
+   - Timestamp and project type details
+
+2. Write architecture report to `<session>/artifacts/architecture-report.md`:
+   - Ranked list of architecture issues with severity, location (file:line or module), measured impact
+   - Issue categories: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT
+   - Evidence summary per issue
+   - Detected project type and analysis methods used
+
+3. Update `<session>/wisdom/.msg/meta.json` under `analyzer` namespace:
+   - Read existing -> merge `{ "analyzer": { project_type, issue_count, top_issue, scope, categories } }` -> write back