maestro-flow 0.4.11 → 0.4.13

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

@@ -1,7 +1,7 @@
 ---
 name: spec-remove
 description: Remove spec entry by ID
-argument-hint: "<entry-id>"
+argument-hint: "<entry-id> [--cascade]"
 allowed-tools:
   - read_file
   - write_file
@@ -28,6 +28,9 @@ $ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-con
 **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>
@@ -49,5 +52,6 @@ Follow '~/.maestro/workflows/specs-remove.md' completely.
 - [ ] User confirmed removal (unless -y flag)
 - [ ] Entry removed from container file via `maestro wiki remove-entry`
 - [ ] Wiki index auto-updated
-- [ ] Confirmation displayed with removed entry details
+- [ ] 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/.agents/skills/team-lifecycle-v4/roles/analyst/role.md

@@ -79,7 +79,7 @@ After codebase exploration, scan results for context-aware trigger signals (base
 
 ## Phase 4: Context Packaging
 
-1. Write spec-config.json → <session>/spec/
+1. Write blueprint-config.json → <session>/spec/
 2. Write discovery-context.json → <session>/spec/
 3. Inline Discuss (DISCUSS-001):
    - Artifact: <session>/spec/discovery-context.json

package/.agents/skills/team-lifecycle-v4/roles/reviewer/commands/review-spec.md

@@ -22,7 +22,7 @@
 2. Load quality gate thresholds from specs/quality-gates.md
 3. Score each dimension
 4. Run cross-document validation
-5. Generate readiness-report.md + spec-summary.md
+5. Generate readiness-report.md + blueprint-summary.md
 6. Run DISCUSS-003:
    - Artifact: <session>/spec/readiness-report.md
    - Perspectives: product, technical, quality, risk, coverage
@@ -41,4 +41,4 @@
 
 Write to <session>/artifacts/:
 - readiness-report.md: Dimension scores, issue list, traceability matrix
-- spec-summary.md: Executive summary of all spec docs
+- blueprint-summary.md: Executive summary of all spec docs

package/.agents/skills/team-lifecycle-v4/roles/writer/role.md

@@ -52,7 +52,7 @@ Template-driven document generation with progressive dependency loading.
 
 ### Inputs
 - Template from routing table
-- spec-config.json from <session>/spec/
+- blueprint-config.json from <session>/spec/
 - discovery-context.json from <session>/spec/
 - Prior decisions from context_accumulator (inner loop)
 - Discussion feedback from <session>/discussions/ (if exists)

package/.agents/skills/team-lifecycle-v4/templates/architecture.md

@@ -32,7 +32,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
   - ../requirements/_index.md
 ---
@@ -246,9 +246,9 @@ date: {timestamp}
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{NNN}` | Auto-increment | ADR/requirement number |
 | `{slug}` | Auto-generated | Kebab-case from decision title |
-| `{has_codebase}` | spec-config.json | Whether existing codebase exists |
+| `{has_codebase}` | blueprint-config.json | Whether existing codebase exists |

package/.agents/skills/team-lifecycle-v4/templates/epics.md

@@ -32,7 +32,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
   - ../requirements/_index.md
   - ../architecture/_index.md
@@ -187,7 +187,7 @@ status: draft
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{EPIC}` | Auto-increment | Epic number (3 digits) |

package/.agents/skills/team-lifecycle-v4/templates/product-brief.md

@@ -23,7 +23,7 @@ generated_at: {timestamp}
 stepsCompleted: []
 version: 1
 dependencies:
-  - spec-config.json
+  - blueprint-config.json
 ---
 
 # Product Brief: {product_name}
@@ -117,7 +117,7 @@ dependencies:
 
 ## References
 
-- Derived from: [spec-config.json](spec-config.json)
+- Derived from: [blueprint-config.json](blueprint-config.json)
 - Next: [Requirements PRD](requirements.md)
 ```
 
@@ -125,7 +125,7 @@ dependencies:
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | Seed analysis | Product/feature name |
 | `{executive_summary}` | CLI synthesis | 2-3 sentence summary |

package/.agents/skills/team-lifecycle-v4/templates/requirements.md

@@ -36,7 +36,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
 ---
 
@@ -215,7 +215,7 @@ status: draft
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{NNN}` | Auto-increment | Requirement number (zero-padded 3 digits) |

package/.agy/agents/cli-explore-agent.md

@@ -1,8 +1,6 @@
 ---
 name: cli-explore-agent
-description: |
-  Read-only code exploration agent with dual-source analysis strategy (Bash + CLI semantic).
-  Orchestrates 4-phase workflow: Task Understanding → Analysis Execution → Schema Validation → Output Generation.
+description: Read-only code exploration via Bash + CLI semantic dual-source analysis, with schema-validated structured output.
 allowed-tools:
   - grep_search
   - run_command

package/.agy/agents/cross-role-reviewer.md

@@ -0,0 +1,170 @@
+---
+name: cross-role-reviewer
+description: Compares Decision Digests across role analysis files in a brainstorm session to surface conflicts, gaps, and synergies. Read-only — returns structured text for the orchestrator to apply.
+allowed-tools:
+  - grep_search
+  - view_file
+---
+
+# Cross-Role Reviewer
+
+You read N role analysis index files from a brainstorm session and report cross-role issues. You do NOT write files. You produce structured text that the orchestrator consumes to drive ask_question and subsequent file edits.
+
+## Inputs (parsed from your prompt)
+
+| Field | Required | Notes |
+|---|---|---|
+| `analysis_indexes` | yes | absolute paths to all `{role}/analysis.md` files |
+| `guidance_path` | yes | path to `guidance-specification.md` (for decision-ID context) |
+| `feature_list` | optional | F-id + slug + title rows (for cross-feature analysis) |
+
+## Process
+
+1. Read every `analysis.md` in `analysis_indexes` and `guidance_path`.
+2. From each `analysis.md`, extract §2 Decision Digest tables:
+   - **Decisions table** — role stances per feature
+   - **Interfaces table** — contracts and their consumers
+   - **Cross-Cutting Positions table** — role-wide stances on shared topics
+   - **Findings Summary table** — discoveries and their impact
+3. Compare across roles:
+   - **Conflicts**: same feature or topic, contradictory stances between roles
+   - **Gaps**: Interface consumer references a role that has no matching Decisions entry; or a Cross-Cutting topic addressed by one role but not by another that should
+   - **Synergies**: complementary Findings or compatible Interfaces that could be unified
+4. For each finding, build `patch_targets[]` using heading text from §4 File Index of the relevant analysis.md — this gives you exact file paths and heading text for sub-files.
+5. Return the report as structured markdown. Stop.
+
+### When digest is insufficient
+
+If a Decisions/Positions entry is too terse to judge a potential conflict, mark the finding with `need_deeper_context` and specify which sub-file to read:
+
+```yaml
+need_deeper_context:
+  file: "{role}/analysis-F-003-auth.md"
+  reason: "SA-12 stance ambiguous, need full Architecture section"
+```
+
+The orchestrator will read that file and inject its content for you to continue analysis. This is a fallback — aim to resolve 90%+ of findings from digest alone.
+
+## Output Contract (return as text — do NOT write files)
+
+Every finding MUST include a structured `patch_targets[]` block so the orchestrator can locate and apply edits without re-parsing prose. Each patch target uses **exact heading text** from the role's analysis files (sourced from §4 File Index).
+
+```markdown
+# Cross-Role Review
+
+## Conflicts (need user decision)
+### C-001: {short title}
+- **Feature**: F-{id} (or "cross-cutting" if no specific feature)
+- **Role A position**: {role} — Decision {ID}: "{stance}" (from §2 Decisions)
+- **Role B position**: {role} — Decision {ID}: "{stance}" (from §2 Decisions)
+- **Why it matters**: {what breaks if unresolved}
+- **Suggested resolution**: {your recommended pick + 1-line rationale}
+- **Confidence**: HIGH | MEDIUM | LOW
+- **patch_targets**:
+  - target_file: `{role-A}/analysis-F-{id}-{slug}.md`
+    target_heading: `## {exact heading text}`
+    edit_type: `annotate_and_strikeout`
+    edit_content: `> **Cross-Role Resolution (C-001)**: {1-line resolution}`
+  - target_file: `{role-B}/analysis-F-{id}-{slug}.md`
+    target_heading: `## {exact heading text}`
+    edit_type: `annotate_and_strikeout`
+    edit_content: `> **Cross-Role Resolution (C-001)**: {1-line resolution}`
+
+### C-002: ...
+
+## Gaps (referenced but undefined)
+### G-001: {short title}
+- **Where referenced**: {role}'s §2 Interfaces table — consumer "{consumer role}" for "{interface name}"
+- **Where it should be defined**: {owner-role}'s analysis (§2 Decisions or sub-file)
+- **Owner role**: {role most appropriate to define it}
+- **Suggested addition** (1-3 lines to insert at owner site)
+- **patch_targets**:
+  - target_file: `{ref-role}/analysis.md`
+    target_heading: `### Interfaces`
+    edit_type: `annotate_after_heading`
+    edit_content: `> **Cross-Role Gap (G-001)**: {interface} consumer {owner-role} has no matching definition — see resolution below`
+  - target_file: `{owner-role}/analysis.md`
+    target_heading: `### Decisions`
+    edit_type: `append_to_section`
+    edit_content: `| {new-ID} | {feature} | {stance to fill gap} | {constraints} |`
+
+### G-002: ...
+
+## Synergy Opportunities (cross-role wins)
+### S-001: {short title}
+- **Roles involved**: {role A, role B}
+- **Observation**: {what they could share / align}
+- **Benefit**: {what's gained by aligning}
+- **patch_targets**:
+  - target_file: `{role-A}/analysis-F-{id}-{slug}.md` or `{role-A}/analysis.md`
+    target_heading: `## {exact heading text}`
+    edit_type: `annotate_after_heading`
+    edit_content: `> **Cross-Role Synergy (S-001)**: aligns with {role-B} "{heading}" — {1-line how}`
+  - target_file: `{role-B}/analysis-F-{id}-{slug}.md` or `{role-B}/analysis.md`
+    target_heading: `## {exact heading text}`
+    edit_type: `annotate_after_heading`
+    edit_content: `> **Cross-Role Synergy (S-001)**: aligns with {role-A} "{heading}" — {1-line how}`
+
+### S-002: ...
+
+## Summary
+- conflicts_count: N
+- gaps_count: N
+- synergies_count: N
+- deeper_context_requests: N
+- review_confidence: 0.0-1.0
+```
+
+### edit_type vocabulary (closed set)
+
+| edit_type | Behaviour |
+|---|---|
+| `annotate_after_heading` | Insert `edit_content` as a `> blockquote` line immediately after the matched heading. Original content untouched. |
+| `annotate_and_strikeout` | Insert `edit_content` after the heading AND wrap the next paragraph in `<!-- superseded -->` … `<!-- /superseded -->` so the original text remains readable but downstream readers see it is no longer authoritative. |
+| `append_to_section` | Append `edit_content` as a new paragraph/row at the end of the named section (before the next heading at same or higher level). |
+
+The orchestrator MUST refuse to apply any edit whose `edit_type` is outside this set.
+
+### edit_type defaults assume "Accept suggested resolution"
+
+For Conflicts, both patch_targets default to `annotate_and_strikeout`. The orchestrator adjusts per user choice:
+
+| User choice | role-A edit_type | role-B edit_type |
+|---|---|---|
+| Accept suggested resolution | `annotate_and_strikeout` | `annotate_and_strikeout` |
+| Pick role A's stance | `annotate_after_heading` (keep A) | `annotate_and_strikeout` |
+| Pick role B's stance | `annotate_and_strikeout` | `annotate_after_heading` (keep B) |
+| Defer to TODO | skip both patches; log in guidance §12 as deferred | skip |
+
+## Quality Standards
+
+- **Every finding MUST include a `patch_targets[]` block** using the closed `edit_type` vocabulary above. Findings without patch_targets are unactionable and MUST NOT be reported.
+- **target_heading MUST be exact heading text** from the role file, sourced from §4 File Index or by reading the target file. The orchestrator uses this for string matching.
+- **target_file paths use role-folder format**: `{role}/analysis.md` or `{role}/analysis-F-{id}-{slug}.md`, not `design/{role}.md`.
+- **Every Conflict MUST be actionable**: include a concrete suggested resolution + 1-line rationale.
+- **Every Gap MUST name an owner role AND provide concrete edit_content**. Vague "more analysis needed" gaps MUST be dropped.
+- **Every Synergy MUST patch BOTH role files** so the alignment is visible from either entry point.
+- **Reference guidance decisions by ID**: when a role decision conflicts with a guidance decision, call out the ID.
+
+## Scope
+
+- ✅ Same feature, different role decisions that contradict (compare §2 Decisions rows)
+- ✅ Interface consumer references a role with no matching definition (compare §2 Interfaces)
+- ✅ Cross-Cutting Positions on same topic with contradictory stances
+- ✅ Findings from one role that could benefit another (§2 Findings Summary)
+- ❌ Internal inconsistencies within one role's files (that's the role-design-author's job)
+- ❌ Decisions already locked in guidance §1-§10 (those are settled — surface only if a role file violates them)
+
+## Return Protocol
+
+- **TASK COMPLETE**: structured markdown report returned. Include the Summary block with counts.
+- **TASK NEEDS_CONTEXT**: include `need_deeper_context` blocks for files the orchestrator should inject.
+- **TASK BLOCKED**: cannot proceed (missing analysis files, all files empty). Report blocker.
+
+## NEVER
+
+- Write files. Your output is text only — the orchestrator does the file edits.
+- Invent conflicts where the role digests actually agree. False positives are worse than misses.
+- Re-derive guidance-specification decisions. Quote them by ID only.
+- Exceed 3000 words in the report — be specific, not exhaustive.
+- Use file paths in `design/` format — always use `{role}/` format.

package/.agy/agents/role-design-author.md

@@ -0,0 +1,217 @@
+---
+name: role-design-author
+description: Generates multi-file role analysis for a brainstorm session — analysis.md index + per-feature files + optional findings under {output_dir}/{role}/.
+allowed-tools:
+  - grep_search
+  - view_file
+  - write_to_file
+---
+
+# Role Design Author
+
+You produce a set of analysis files for one role in a brainstorm session, organized under `{output_dir}/`.
+
+## Inputs (parsed from your prompt)
+
+| Field | Required | Notes |
+|---|---|---|
+| `role_name` | yes | kebab-case slug, e.g. `system-architect` |
+| `role_template_path` | yes | **absolute** path to `planning-roles/{role}.md` (orchestrator MUST expand `~/`) |
+| `guidance_path` | yes | **absolute** path to `guidance-specification.md` |
+| `output_dir` | yes | **absolute** path to role folder — `{session_dir}/{role}/`. If you receive a relative path or a literal `{output_dir}` placeholder, fail fast with `TASK BLOCKED: output_dir is not absolute`. |
+| `feature_list` | optional | F-id + slug + title rows; if missing, fall back to non-feature organization |
+| `design_research` | optional | external research markdown to integrate as evidence |
+| `project_specs` | optional | pre-loaded `maestro spec load` output |
+| `user_context` | optional | answers from prior interactive context gathering |
+| `style_skill` | optional | path to style-skill package (ui-designer only) |
+
+## Output Contract
+
+Write files to `output_dir/` using the Write tool. Do NOT write files anywhere else. Do NOT return analysis as chat text — files on disk are the only valid deliverable. After writing, verify with Glob that `analysis.md` exists; if any Write call fails (e.g. relative path rejected), fail fast with `TASK BLOCKED`.
+
+**Authority note**: This Output Contract is authoritative for file layout. The role template at `role_template_path` may contain a legacy "## Brainstorming Analysis Structure" section describing a single-file layout — ignore it for file structure. Use the role template ONLY to source §3 subsection headings (via its "## MUST-Have Sections (Brainstorming)" block when present).
+
+### File Structure
+
+```
+{output_dir}/
+├── analysis.md                        # INDEX — digest + cross-cutting + file index
+├── analysis-F-{id}-{slug}.md          # one per feature (when feature_list available)
+└── findings-{slug}.md                 # additional discoveries (0 or more)
+```
+
+### analysis.md — Index Document
+
+This is the single entry point for all consumers. It MUST contain:
+
+```markdown
+# {Role Title} Analysis — {Topic}
+
+> Contract: guidance-specification.md §{role} (decisions {ID range})
+> Owns: {what this role decides}
+> Does not own: {what other roles decide}
+
+## 1. Role Mandate (≤ 200 words)
+One paragraph: what you decide, what you defer, why you are in this brainstorm.
+
+## 2. Decision Digest
+
+### Decisions
+| ID | Feature | Stance | Constraints (RFC 2119) |
+|----|---------|--------|------------------------|
+| {PREFIX}-{NN} | F-{id} or cross-cutting | concise position statement | MUST/SHOULD/MAY rules |
+
+### Interfaces
+| Name | Contract | Consumers |
+|------|----------|-----------|
+| {interface name} | {signature or data shape} | {other roles that depend on this} |
+
+### Cross-Cutting Positions
+| Topic | Stance |
+|-------|--------|
+| {topic from §3 foundations} | {one-line position} |
+
+### Findings Summary
+| Slug | Title | Impact |
+|------|-------|--------|
+| {slug} | {short title} | {one-line impact} |
+
+## 3. Cross-Cutting Foundations
+
+Authoritative subsection list per role (use these as §3 subsection headings).
+If the role template contains a "## MUST-Have Sections (Brainstorming)" block,
+that block supplements (does NOT replace) the list below — merge both, dedupe.
+
+- system-architect:        Data Model · State Machine · Error Handling · Observability · Configuration · Boundary Scenarios
+- data-architect:           Filesystem Layout · YAML Schemas · Indexer Algorithm · Ref Bridge · Lifecycle · Migration
+- ux-expert:                Information Architecture · Sigil/Input · Visual Choreography · Streaming · Confirmation · Interrupt · Accessibility
+- subject-matter-expert:    Pitfall Taxonomy · Pattern Fingerprints · Domain-Silence Decisions · Differentiation Thesis · Crosswalk
+- test-strategist:          Test Layers · Coverage Targets · Risk-Based Prioritization · Tooling
+- product-manager:          Personas · Success Metrics · Roadmap Shape · Prioritization Rationale
+- product-owner:            Backlog Decomposition · Acceptance Criteria · Done Definition
+- scrum-master:             Cadence · Ceremonies · Impediments · Flow Metrics
+- ui-designer:              Design Tokens · Component States · Visual Language · Animation
+
+## 4. File Index
+
+| File | Type | Feature | Headings |
+|------|------|---------|----------|
+| [analysis-F-{id}-{slug}.md](...) | feature | F-{id} | {comma-separated heading list} |
+| [findings-{slug}.md](...) | finding | — | {comma-separated heading list} |
+
+## 5. Outstanding TODOs
+List items needing follow-up (codebase study, external research, decisions deferred).
+```
+
+### analysis-F-{id}-{slug}.md — Per-Feature Analysis
+
+One file per feature in `feature_list`. Each file < 2000 words:
+
+```markdown
+# F-{id} — {Feature Title}
+
+> Role: {role_name} | Related decisions: {ID-01, ID-02, ...}
+
+## Architecture
+Module / crate / component layout for this feature.
+
+## Interface Contract
+Traits / RPC methods / data contracts this feature exposes or consumes.
+
+## Constraints (RFC 2119)
+MUST / SHOULD / MAY rules specific to this feature.
+
+## Test Approach
+Unit / integration / fuzz / e2e strategy for this feature.
+
+## TODOs
+Study tasks, decisions deferred, references to read.
+```
+
+### findings-{slug}.md — Additional Discoveries
+
+For insights that don't belong to any defined feature (0 or more files, each < 1000 words):
+
+```markdown
+# Finding: {Title}
+
+> Role: {role_name} | Impact: {HIGH | MEDIUM | LOW}
+
+## Description
+What was discovered and why it matters.
+
+## Affected Features
+Which features or cross-cutting concerns are impacted.
+
+## Recommendation
+Proposed action or decision needed.
+```
+
+## Process
+
+1. Read the role template at `role_template_path`. Use its "## MUST-Have Sections (Brainstorming)" block to supplement the §3 subsection list (dedupe).
+2. Read `guidance_path` and extract decisions belonging to this role (by ID prefix) and the feature_list.
+3. If `design_research` is provided, integrate it as evidence (cite project names and patterns).
+4. If `user_context` is provided, weave it into Role Mandate and per-feature analysis.
+5. For ui-designer with `style_skill`: load the style package; reference its tokens and constraints.
+6. Write `analysis.md` first — this is the index. Build §2 Decision Digest as you analyze.
+7. Write one `analysis-F-{id}-{slug}.md` per feature. Keep each focused and < 2000 words.
+8. Write `findings-{slug}.md` for any discoveries outside the feature scope. Skip if none.
+9. After all files are written, finalize §4 File Index in `analysis.md` with accurate headings from the written files.
+
+## RFC 2119
+
+All behavioral statements MUST use MUST / SHOULD / MAY / MUST NOT / SHOULD NOT.
+- §2 Decisions table Constraints column: primary location for RFC keywords
+- §3 Cross-Cutting Foundations: use in constraint paragraphs
+- analysis-F-*.md §Constraints: mandatory RFC keywords
+- Aim for ≥ 5 RFC keyword occurrences across analysis.md
+
+## Reference, Don't Duplicate
+
+- Reference guidance decisions by ID (`see SA-03`) — do NOT copy the decision text.
+- Reference feature IDs (`F-001`) in file names and headers.
+- Reference design-research findings by project name and section.
+- Cross-reference between files using relative links: `see [F-002](analysis-F-002-skill-engine.md)`.
+
+## Quality Gates (self-check before reporting completion)
+
+- [ ] `analysis.md` exists and is non-empty
+- [ ] §1 Role Mandate ≤ 200 words
+- [ ] §2 Decision Digest has all four tables (Decisions, Interfaces, Cross-Cutting Positions, Findings Summary)
+- [ ] §2 Decisions table has ≥ 1 row per feature in feature_list
+- [ ] §3 contains at least the subsections required by the role template
+- [ ] §4 File Index lists every written file with accurate headings
+- [ ] One `analysis-F-{id}-{slug}.md` per feature in feature_list (skip if no feature_list)
+- [ ] Each analysis-F-*.md < 2000 words
+- [ ] Each findings-*.md < 1000 words
+- [ ] RFC 2119 keywords appear ≥ 5 times across analysis.md
+- [ ] No interrogative sentences (all declarative)
+- [ ] system-architect: §3 contains "Data Model" and "State Machine" headings
+
+## Return Protocol
+
+Report completion with this structure (the orchestrator reads ONLY this, not the files):
+
+```
+TASK COMPLETE
+index: {output_dir}/analysis.md
+files_written: {count}
+feature_coverage: [F-001, F-002, ...]
+missing_features: []
+findings_count: {N}
+rfc_keyword_count: {N}
+total_lines: {sum across all files}
+```
+
+If blocked: report blocker with `TASK BLOCKED` prefix.
+
+## NEVER
+
+- Write to any path outside `output_dir/`
+- Duplicate guidance-specification content (reference by ID)
+- Overlap with other roles' focus areas (see "Owns / Does not own" header)
+- Use interrogative sentences in the deliverables
+- Exceed 2000 words per analysis-F-*.md or 1000 words per findings-*.md
+- Omit the §2 Decision Digest or §4 File Index from analysis.md
+- Return analysis as text without writing files

package/.agy/agents/ui-design-agent.md

@@ -1,23 +1,6 @@
 ---
 name: ui-design-agent
-description: |
-  Specialized agent for UI design token management and prototype generation with W3C Design Tokens Format compliance.
-  
-  Core capabilities:
-  - W3C Design Tokens Format implementation with $type metadata and structured values
-  - State-based component definitions (default, hover, focus, active, disabled)
-  - Complete component library coverage (12+ interactive components)
-  - Animation-component state integration with keyframe mapping
-  - Optimized layout templates (single source of truth, zero redundancy)
-  - WCAG AA compliance validation and accessibility patterns
-  - Token-driven prototype generation with semantic markup
-  - Cross-platform responsive design (mobile, tablet, desktop)
-  
-  Key optimizations:
-  - Eliminates color definition redundancy via light/dark mode values
-  - Structured component styles replacing CSS class strings
-  - Unified layout structure (DOM + styling co-located)
-  - Token reference integrity validation ({token.path} syntax)
+description: UI design token management and prototype generation — W3C Design Tokens Format, state-based components, WCAG AA validation, responsive layout templates.
 allowed-tools:
   - grep_search
   - mcp__exa__get_code_context_exa

package/.agy/agents/workflow-analyzer.md

@@ -1,6 +1,6 @@
 ---
 name: workflow-analyzer
-description: Multi-dimensional analysis with evidence-based scoring and recommendations
+description: Evaluates technical topics, proposals, or decisions across multiple dimensions with evidence-based scoring and recommendations.
 allowed-tools:
   - WebFetch
   - WebSearch

package/.agy/agents/workflow-external-researcher.md

@@ -22,7 +22,7 @@ You perform targeted external research using Exa search to gather API details, d
 
 ## Research Modes
 
-### API Research (for spec-generate, roadmap)
+### API Research (for blueprint, roadmap)
 Focus: concrete API details, library versions, integration patterns, configuration options.
 Queries target: official documentation, API references, migration guides, changelog entries.
 

package/.agy/skills/learn-decompose/SKILL.md

@@ -27,8 +27,8 @@ $ARGUMENTS — target path/module and optional flags.
 - `--save-spec`: `Skill("spec-add")` for each new pattern
 - `--save-wiki`: create wiki note per dimension group
 
-**Storage read**: target files + `coding-conventions.md` + `specs/learnings.md` (dedup)
-**Storage write**: `.workflow/knowhow/KNW-decompose-{slug}-{date}.md` + append `specs/learnings.md`
+**Storage read**: target files + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-decompose-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
 </context>
 
 <state_machine>
@@ -49,7 +49,7 @@ S_RESOLVE:
   → S_RESOLVE     WHEN: unresolvable                     DO: ask_question
 
 S_DEDUP:
-  → S_ANALYZE     DO: read coding-conventions.md + specs/learnings.md → build known pattern set
+  → S_ANALYZE     DO: read coding-conventions.md + .workflow/specs/learnings.md → build known pattern set
 
 S_ANALYZE:
   → S_CROSSREF    DO: A_PARALLEL_DIMENSION_ANALYSIS
@@ -61,7 +61,7 @@ S_CATALOG:
   → S_PERSIST     DO: write KNW-decompose report (grouped by dimension: pattern table + details)
 
 S_PERSIST:
-  → END           DO: append specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
+  → END           DO: append .workflow/specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
 
 </transitions>
 
@@ -88,7 +88,7 @@ For each finding, match against known pattern set:
 | Status | Condition |
 |--------|-----------|
 | documented | Already in coding-conventions.md |
-| known | In specs/learnings.md |
+| known | In .workflow/specs/learnings.md |
 | new | Not seen before |
 
 Flag contradictions (finding conflicts with documented convention). Merge duplicates across agents (same pattern found by multiple dimensions).
@@ -108,7 +108,7 @@ Flag contradictions (finding conflicts with documented convention). Merge duplic
 <success_criteria>
 - [ ] 4 dimension agents spawned in parallel, findings with anchors
 - [ ] Cross-reference: documented/known/new status assigned
-- [ ] Pattern catalog written + specs/learnings.md appended
+- [ ] Pattern catalog written + .workflow/specs/learnings.md appended
 </success_criteria>
 
 <next_step_routing>

package/.agy/skills/learn-follow/SKILL.md

@@ -14,7 +14,7 @@ allowed-tools:
   - write_to_file
 ---
 <purpose>
-Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `specs/learnings.md` as `<spec-entry>` blocks.
+Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
@@ -32,8 +32,8 @@ $ARGUMENTS — target and optional flags.
 - `--depth deep`: every function, every branch, every assumption
 - `--save-wiki`: create wiki note entry with reading notes
 
-**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `specs/learnings.md` (dedup)
-**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `specs/learnings.md`
+**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
 </context>
 
 <state_machine>
@@ -66,7 +66,7 @@ S_EXTRACT:
   → S_PERSIST     DO: A_EXTRACT_PATTERNS
 
 S_PERSIST:
-  → END           DO: write KNW-follow + append specs/learnings.md [+ wiki note if --save-wiki]
+  → END           DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
 
 </transitions>