ma-agents 3.4.8 → 3.5.0

package/.opencode/skills/bmad-create-ux-design/workflow.md

@@ -1,36 +0,0 @@
-# Create UX Design Workflow
-
-**Goal:** Create comprehensive UX design specifications through collaborative visual exploration and informed decision-making where you act as a UX facilitator working with a product stakeholder.
-
----
-
-## WORKFLOW ARCHITECTURE
-
-This uses **micro-file architecture** for disciplined execution:
-
-- Each step is a self-contained file with embedded rules
-- Sequential progression with user control at each step
-- Document state tracked in frontmatter
-- Append-only document building through conversation
-
----
-
-## INITIALIZATION
-
-### Configuration Loading
-
-Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
-
-- `project_name`, `output_folder`, `planning_artifacts`, `user_name`
-- `communication_language`, `document_output_language`, `user_skill_level`
-- `date` as system-generated current datetime
-
-### Paths
-
-- `default_output_file` = `{planning_artifacts}/ux-design-specification.md`
-
-## EXECUTION
-
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
-- Read fully and follow: `./steps/step-01-init.md` to begin the UX design workflow.

package/.opencode/skills/bmad-distillator/SKILL.md

@@ -1,178 +0,0 @@
----
-name: bmad-distillator
-description: Lossless LLM-optimized compression of source documents. Use when the user requests to 'distill documents' or 'create a distillate'.
-argument-hint: "[to create provide input paths] [--validate distillate-path to confirm distillate is lossless and optimized]"
----
-
-# Distillator: A Document Distillation Engine
-
-## Overview
-
-This skill produces hyper-compressed, token-efficient documents (distillates) from any set of source documents. A distillate preserves every fact, decision, constraint, and relationship from the sources while stripping all overhead that humans need and LLMs don't. Act as an information extraction and compression specialist. The output is a single dense document (or semantically-split set) that a downstream LLM workflow can consume as sole context input without information loss.
-
-This is a compression task, not a summarization task. Summaries are lossy. Distillates are lossless compression optimized for LLM consumption.
-
-## On Activation
-
-1. **Validate inputs.** The caller must provide:
-   - **source_documents** (required) — One or more file paths, folder paths, or glob patterns to distill
-   - **downstream_consumer** (optional) — What workflow/agent consumes this distillate (e.g., "PRD creation", "architecture design"). When provided, use it to judge signal vs noise. When omitted, preserve everything.
-   - **token_budget** (optional) — Approximate target size. When provided and the distillate would exceed it, trigger semantic splitting.
-   - **output_path** (optional) — Where to save. When omitted, save adjacent to the primary source document with `-distillate.md` suffix.
-   - **--validate** (flag) — Run round-trip reconstruction test after producing the distillate.
-
-2. **Route** — proceed to Stage 1.
-
-## Stages
-
-| # | Stage | Purpose |
-|---|-------|---------|
-| 1 | Analyze | Run analysis script, determine routing and splitting |
-| 2 | Compress | Spawn compressor agent(s) to produce the distillate |
-| 3 | Verify & Output | Completeness check, format check, save output |
-| 4 | Round-Trip Validate | (--validate only) Reconstruct and diff against originals |
-
-### Stage 1: Analyze
-
-Run `scripts/analyze_sources.py --help` then run it with the source paths. Use its routing recommendation and grouping output to drive Stage 2. Do NOT read the source documents yourself.
-
-### Stage 2: Compress
-
-**Single mode** (routing = `"single"`, ≤3 files, ≤15K estimated tokens):
-
-Spawn one subagent using `agents/distillate-compressor.md` with all source file paths.
-
-**Fan-out mode** (routing = `"fan-out"`):
-
-1. Spawn one compressor subagent per group from the analysis output. Each compressor receives only its group's file paths and produces an intermediate distillate.
-
-2. After all compressors return, spawn one final **merge compressor** subagent using `agents/distillate-compressor.md`. Pass it the intermediate distillate contents as its input (not the original files). Its job is cross-group deduplication, thematic regrouping, and final compression.
-
-3. Clean up intermediate distillate content (it exists only in memory, not saved to disk).
-
-**Graceful degradation:** If subagent spawning is unavailable, read the source documents and perform the compression work directly using the same instructions from `agents/distillate-compressor.md`. For fan-out, process groups sequentially then merge.
-
-The compressor returns a structured JSON result containing the distillate content, source headings, named entities, and token estimate.
-
-### Stage 3: Verify & Output
-
-After the compressor (or merge compressor) returns:
-
-1. **Completeness check.** Using the headings and named entities list returned by the compressor, verify each appears in the distillate content. If gaps are found, send them back to the compressor for a targeted fix pass — not a full recompression. Limit to 2 fix passes maximum.
-
-2. **Format check.** Verify the output follows distillate format rules:
-   - No prose paragraphs (only bullets)
-   - No decorative formatting
-   - No repeated information
-   - Each bullet is self-contained
-   - Themes are clearly delineated with `##` headings
-
-3. **Determine output format.** Using the split prediction from Stage 1 and actual distillate size:
-
-   **Single distillate** (≤~5,000 tokens or token_budget not exceeded):
-
-   Save as a single file with frontmatter:
-
-   ```yaml
-   ---
-   type: bmad-distillate
-   sources:
-     - "{relative path to source file 1}"
-     - "{relative path to source file 2}"
-   downstream_consumer: "{consumer or 'general'}"
-   created: "{date}"
-   token_estimate: {approximate token count}
-   parts: 1
-   ---
-   ```
-
-   **Split distillate** (>~5,000 tokens, or token_budget requires it):
-
-   Create a folder `{base-name}-distillate/` containing:
-
-   ```
-   {base-name}-distillate/
-   ├── _index.md           # Orientation, cross-cutting items, section manifest
-   ├── 01-{topic-slug}.md  # Self-contained section
-   ├── 02-{topic-slug}.md
-   └── 03-{topic-slug}.md
-   ```
-
-   The `_index.md` contains:
-   - Frontmatter with sources (relative paths from the distillate folder to the originals)
-   - 3-5 bullet orientation (what was distilled, from what)
-   - Section manifest: each section's filename + 1-line description
-   - Cross-cutting items that span multiple sections
-
-   Each section file is self-contained — loadable independently. Include a 1-line context header: "This section covers [topic]. Part N of M."
-
-   Source paths in frontmatter must be relative to the distillate's location.
-
-4. **Measure distillate.** Run `scripts/analyze_sources.py` on the final distillate file(s) to get accurate token counts for the output. Use the `total_estimated_tokens` from this analysis as `distillate_total_tokens`.
-
-5. **Report results.** Always return structured JSON output:
-
-   ```json
-   {
-     "status": "complete",
-     "distillate": "{path or folder path}",
-     "section_distillates": ["{path1}", "{path2}"] or null,
-     "source_total_tokens": N,
-     "distillate_total_tokens": N,
-     "compression_ratio": "X:1",
-     "source_documents": ["{path1}", "{path2}"],
-     "completeness_check": "pass" or "pass_with_additions"
-   }
-   ```
-
-   Where `source_total_tokens` is from the Stage 1 analysis and `distillate_total_tokens` is from step 4. The `compression_ratio` is `source_total_tokens / distillate_total_tokens` formatted as "X:1" (e.g., "3.2:1").
-
-6. If `--validate` flag was set, proceed to Stage 4. Otherwise, done.
-
-### Stage 4: Round-Trip Validation (--validate only)
-
-This stage proves the distillate is lossless by reconstructing source documents from the distillate alone. Use for critical documents where information loss is unacceptable, or as a quality gate for high-stakes downstream workflows. Not for routine use — it adds significant token cost.
-
-1. **Spawn the reconstructor agent** using `agents/round-trip-reconstructor.md`. Pass it ONLY the distillate file path (or `_index.md` path for split distillates) — it must NOT have access to the original source documents.
-
-   For split distillates, spawn one reconstructor per section in parallel. Each receives its section file plus the `_index.md` for cross-cutting context.
-
-   **Graceful degradation:** If subagent spawning is unavailable, this stage cannot be performed by the main agent (it has already seen the originals). Report that round-trip validation requires subagent support and skip.
-
-2. **Receive reconstructions.** The reconstructor returns reconstruction file paths saved adjacent to the distillate.
-
-3. **Perform semantic diff.** Read both the original source documents and the reconstructions. For each section of the original, assess:
-   - Is the core information present in the reconstruction?
-   - Are specific details preserved (numbers, names, decisions)?
-   - Are relationships and rationale intact?
-   - Did the reconstruction add anything not in the original? (indicates hallucination filling gaps)
-
-4. **Produce validation report** saved adjacent to the distillate as `-validation-report.md`:
-
-   ```markdown
-   ---
-   type: distillate-validation
-   distillate: "{distillate path}"
-   sources: ["{source paths}"]
-   created: "{date}"
-   ---
-
-   ## Validation Summary
-   - Status: PASS | PASS_WITH_WARNINGS | FAIL
-   - Information preserved: {percentage estimate}
-   - Gaps found: {count}
-   - Hallucinations detected: {count}
-
-   ## Gaps (information in originals but missing from reconstruction)
-   - {gap description} — Source: {which original}, Section: {where}
-
-   ## Hallucinations (information in reconstruction not traceable to originals)
-   - {hallucination description} — appears to fill gap in: {section}
-
-   ## Possible Gap Markers (flagged by reconstructor)
-   - {marker description}
-   ```
-
-5. **If gaps are found**, offer to run a targeted fix pass on the distillate — adding the missing information without full recompression. Limit to 2 fix passes maximum.
-
-6. **Clean up** — delete the temporary reconstruction files after the report is generated.

package/.opencode/skills/bmad-distillator/agents/distillate-compressor.md

@@ -1,116 +0,0 @@
-# Distillate Compressor Agent
-
-Act as an information extraction and compression specialist. Your sole purpose is to produce a lossless, token-efficient distillate from source documents.
-
-You receive: source document file paths, an optional downstream_consumer context, and a splitting decision.
-
-You must load and apply `../resources/compression-rules.md` before producing output. Reference `../resources/distillate-format-reference.md` for the expected output format.
-
-## Compression Process
-
-### Step 1: Read Sources
-
-Read all source document files. For each, note the document type (product brief, discovery notes, research report, architecture doc, PRD, etc.) based on content and naming.
-
-### Step 2: Extract
-
-Extract every discrete piece of information from all source documents:
-- Facts and data points (numbers, dates, versions, percentages)
-- Decisions made and their rationale
-- Rejected alternatives and why they were rejected
-- Requirements and constraints (explicit and implicit)
-- Relationships and dependencies between entities
-- Named entities (products, companies, people, technologies)
-- Open questions and unresolved items
-- Scope boundaries (in/out/deferred)
-- Success criteria and validation methods
-- Risks and opportunities
-- User segments and their success definitions
-
-Treat this as entity extraction — pull out every distinct piece of information regardless of where it appears in the source documents.
-
-### Step 3: Deduplicate
-
-Apply the deduplication rules from `../resources/compression-rules.md`.
-
-### Step 4: Filter (only if downstream_consumer is specified)
-
-For each extracted item, ask: "Would the downstream workflow need this?"
-- Drop items that are clearly irrelevant to the stated consumer
-- When uncertain, keep the item — err on the side of preservation
-- Never drop: decisions, rejected alternatives, open questions, constraints, scope boundaries
-
-### Step 5: Group Thematically
-
-Organize items into coherent themes derived from the source content — not from a fixed template. The themes should reflect what the documents are actually about.
-
-Common groupings (use what fits, omit what doesn't, add what's needed):
-- Core concept / problem / motivation
-- Solution / approach / architecture
-- Users / segments
-- Technical decisions / constraints
-- Scope boundaries (in/out/deferred)
-- Competitive context
-- Success criteria
-- Rejected alternatives
-- Open questions
-- Risks and opportunities
-
-### Step 6: Compress Language
-
-For each item, apply the compression rules from `../resources/compression-rules.md`:
-- Strip prose transitions and connective tissue
-- Remove hedging and rhetoric
-- Remove explanations of common knowledge
-- Preserve specific details (numbers, names, versions, dates)
-- Ensure the item is self-contained (understandable without reading the source)
-- Make relationships explicit ("X because Y", "X blocks Y", "X replaces Y")
-
-### Step 7: Format Output
-
-Produce the distillate as dense thematically-grouped bullets:
-- `##` headings for themes — no deeper heading levels needed
-- `- ` bullets for items — every token must carry signal
-- No decorative formatting (no bold for emphasis, no horizontal rules)
-- No prose paragraphs — only bullets
-- Semicolons to join closely related short items within a single bullet
-- Each bullet self-contained — understandable without reading other bullets
-
-Do NOT include frontmatter — the calling skill handles that.
-
-## Semantic Splitting
-
-If the splitting decision indicates splitting is needed, load `../resources/splitting-strategy.md` and follow it.
-
-When splitting:
-
-1. Identify natural semantic boundaries in the content — coherent topic clusters, not arbitrary size breaks.
-
-2. Produce a **root distillate** containing:
-   - 3-5 bullet orientation (what was distilled, for whom, how many parts)
-   - Cross-references to section distillates
-   - Items that span multiple sections
-
-3. Produce **section distillates**, each self-sufficient. Include a 1-line context header: "This section covers [topic]. Part N of M from [source document names]."
-
-## Return Format
-
-Return a structured result to the calling skill:
-
-```json
-{
-  "distillate_content": "{the complete distillate text without frontmatter}",
-  "source_headings": ["heading 1", "heading 2"],
-  "source_named_entities": ["entity 1", "entity 2"],
-  "token_estimate": N,
-  "sections": null or [{"topic": "...", "content": "..."}]
-}
-```
-
-- **distillate_content**: The full distillate text
-- **source_headings**: All Level 2+ headings found across source documents (for completeness verification)
-- **source_named_entities**: Key named entities (products, companies, people, technologies, decisions) found in sources
-- **token_estimate**: Approximate token count of the distillate
-- **sections**: null for single distillates; array of section objects if semantically split
-
-Do not include conversational text, status updates, or preamble — return only the structured result.

package/.opencode/skills/bmad-distillator/agents/round-trip-reconstructor.md

@@ -1,68 +0,0 @@
-# Round-Trip Reconstructor Agent
-
-Act as a document reconstruction specialist. Your purpose is to prove a distillate's completeness by reconstructing the original source documents from the distillate alone.
-
-**Critical constraint:** You receive ONLY the distillate file path. You must NOT have access to the original source documents. If you can see the originals, the test is meaningless.
-
-## Process
-
-### Step 1: Analyze the Distillate
-
-Read the distillate file. Parse the YAML frontmatter to identify:
-- The `sources` list — what documents were distilled
-- The `downstream_consumer` — what filtering may have been applied
-- The `parts` count — whether this is a single or split distillate
-
-### Step 2: Detect Document Types
-
-From the source file names and the distillate's content, infer what type of document each source was:
-- Product brief, discovery notes, research report, architecture doc, PRD, etc.
-- Use the naming conventions and content themes to determine appropriate document structure
-
-### Step 3: Reconstruct Each Source
-
-For each source listed in the frontmatter, produce a full human-readable document:
-
-- Use appropriate prose, structure, and formatting for the document type
-- Include all sections the original document would have had based on the document type
-- Expand compressed bullets back into natural language prose
-- Restore section transitions and contextual framing
-- Do NOT invent information — only use what is in the distillate
-- Flag any places where the distillate felt insufficient with `[POSSIBLE GAP]` markers — these are critical quality signals
-
-**Quality signals to watch for:**
-- Bullets that feel like they're missing context → `[POSSIBLE GAP: missing context for X]`
-- Themes that seem underrepresented given the document type → `[POSSIBLE GAP: expected more on X for a document of this type]`
-- Relationships that are mentioned but not fully explained → `[POSSIBLE GAP: relationship between X and Y unclear]`
-
-### Step 4: Save Reconstructions
-
-Save each reconstructed document as a temporary file adjacent to the distillate:
-- First source: `{distillate-basename}-reconstruction-1.md`
-- Second source: `{distillate-basename}-reconstruction-2.md`
-- And so on for each source
-
-Each reconstruction should include a header noting it was reconstructed:
-
-```markdown
----
-type: distillate-reconstruction
-source_distillate: "{distillate path}"
-reconstructed_from: "{original source name}"
-reconstruction_number: {N}
----
-```
-
-### Step 5: Return
-
-Return a structured result to the calling skill:
-
-```json
-{
-  "reconstruction_files": ["{path1}", "{path2}"],
-  "possible_gaps": ["gap description 1", "gap description 2"],
-  "source_count": N
-}
-```
-
-Do not include conversational text, status updates, or preamble — return only the structured result.

package/.opencode/skills/bmad-distillator/resources/compression-rules.md

@@ -1,51 +0,0 @@
-# Compression Rules
-
-These rules govern how source text is compressed into distillate format. Apply as a final pass over all output.
-
-## Strip — Remove entirely
-
-- Prose transitions: "As mentioned earlier", "It's worth noting", "In addition to this"
-- Rhetoric and persuasion: "This is a game-changer", "The exciting thing is"
-- Hedging: "We believe", "It's likely that", "Perhaps", "It seems"
-- Self-reference: "This document describes", "As outlined above"
-- Common knowledge explanations: "Vercel is a cloud platform company", "MIT is an open-source license", "JSON is a data interchange format"
-- Repeated introductions of the same concept
-- Section transition paragraphs
-- Formatting-only elements (decorative bold/italic for emphasis, horizontal rules for visual breaks)
-- Filler phrases: "In order to", "It should be noted that", "The fact that"
-
-## Preserve — Keep always
-
-- Specific numbers, dates, versions, percentages
-- Named entities (products, companies, people, technologies)
-- Decisions made and their rationale (compressed: "Decision: X. Reason: Y")
-- Rejected alternatives and why (compressed: "Rejected: X. Reason: Y")
-- Explicit constraints and non-negotiables
-- Dependencies and ordering relationships
-- Open questions and unresolved items
-- Scope boundaries (in/out/deferred)
-- Success criteria and how they're validated
-- User segments and what success means for each
-- Risks with their severity signals
-- Conflicts between source documents
-
-## Transform — Change form for efficiency
-
-- Long prose paragraphs → single dense bullet capturing the same information
-- "We decided to use X because Y and Z" → "X (rationale: Y, Z)"
-- Repeated category labels → group under a single heading, no per-item labels
-- "Risk: ... Severity: high" → "HIGH RISK: ..."
-- Conditional statements → "If X → Y" form
-- Multi-sentence explanations → semicolon-separated compressed form
-- Lists of related short items → single bullet with semicolons
-- "X is used for Y" → "X: Y" when context is clear
-- Verbose enumerations → parenthetical lists: "platforms (Cursor, Claude Code, Windsurf, Copilot)"
-
-## Deduplication Rules
-
-- Same fact in multiple documents → keep the version with most context
-- Same concept at different detail levels → keep the detailed version
-- Overlapping lists → merge into single list, no duplicates
-- When source documents disagree → note the conflict explicitly: "Brief says X; discovery notes say Y — unresolved"
-- Executive summary points that are expanded elsewhere → keep only the expanded version
-- Introductory framing repeated across sections → capture once under the most relevant theme