ma-agents 3.4.8 → 3.5.0

package/.opencode/skills/bmad-distillator/resources/distillate-format-reference.md

@@ -1,227 +0,0 @@
-# Distillate Format Reference
-
-Examples showing the transformation from human-readable source content to distillate format.
-
-## Frontmatter
-
-Every distillate includes YAML frontmatter. Source paths are relative to the distillate's location so the distillate remains portable:
-
-```yaml
----
-type: bmad-distillate
-sources:
-  - "product-brief-example.md"
-  - "product-brief-example-discovery-notes.md"
-downstream_consumer: "PRD creation"
-created: "2026-03-13"
-token_estimate: 1200
-parts: 1
----
-```
-
-## Before/After Examples
-
-### Prose Paragraph to Dense Bullet
-
-**Before** (human-readable brief excerpt):
-```
-## What Makes This Different
-
-**The anti-fragmentation layer.** The AI tooling space is fracturing across 40+
-platforms with no shared methodology layer. BMAD is uniquely positioned to be the
-cross-platform constant — the structured approach that works the same in Cursor,
-Claude Code, Windsurf, Copilot, and whatever launches next month. Every other
-methodology or skill framework maintains its own platform support matrix. By
-building on the open-source skills CLI ecosystem, BMAD offloads the highest-churn
-maintenance burden and focuses on what actually differentiates it: the methodology
-itself.
-```
-
-**After** (distillate):
-```
-## Differentiation
-- Anti-fragmentation positioning: BMAD = cross-platform constant across 40+ fragmenting AI tools; no competitor provides shared methodology layer
-- Platform complexity delegated to Vercel skills CLI ecosystem (MIT); BMAD maintains methodology, not platform configs
-```
-
-### Technical Details to Compressed Facts
-
-**Before** (discovery notes excerpt):
-```
-## Competitive Landscape
-
-- **Vercel Skills.sh**: 83K+ skills, 18 agents, largest curated leaderboard —
-  but dev-only, skills trigger unreliably (20% without explicit prompting)
-- **SkillsMP**: 400K+ skills directory, pure aggregator with no curation or CLI
-- **ClawHub/OpenClaw**: ~3.2K curated skills with versioning/rollback, small ecosystem
-- **Lindy**: No-code AI agent builder for business automation — closed platform,
-  no skill sharing
-- **Microsoft Copilot Studio**: Enterprise no-code agent builder — vendor-locked
-  to Microsoft
-- **MindStudio**: No-code AI agent platform — siloed, no interoperability
-- **Make/Zapier AI**: Workflow automation adding AI agents — workflow-centric,
-  not methodology-centric
-- **Key gap**: NO competitor combines structured methodology with plugin
-  marketplace — this is BMAD's whitespace
-```
-
-**After** (distillate):
-```
-## Competitive Landscape
-- No competitor combines structured methodology + plugin marketplace (whitespace)
-- Skills.sh (Vercel): 83K skills, 18 agents, dev-only, 20% trigger reliability
-- SkillsMP: 400K skills, aggregator only, no curation/CLI
-- ClawHub: 3.2K curated, versioning, small ecosystem
-- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only
-```
-
-### Deduplication Across Documents
-
-When the same fact appears in both a brief and discovery notes:
-
-**Brief says:**
-```
-bmad-init must always be included as a base skill in every bundle
-```
-
-**Discovery notes say:**
-```
-bmad-init must always be included as a base skill in every bundle/install
-(solves bootstrapping problem)
-```
-
-**Distillate keeps the more contextual version:**
-```
-- bmad-init: always included as base skill in every bundle (solves bootstrapping)
-```
-
-### Decision/Rationale Compression
-
-**Before:**
-```
-We decided not to build our own platform support matrix going forward, instead
-delegating to the Vercel skills CLI ecosystem. The rationale is that maintaining
-20+ platform configs is the biggest maintenance burden and it's unsustainable
-at 40+ platforms.
-```
-
-**After:**
-```
-- Rejected: own platform support matrix. Reason: unsustainable at 40+ platforms; delegate to Vercel CLI ecosystem
-```
-
-## Full Example
-
-A complete distillate produced from a product brief and its discovery notes, targeted at PRD creation:
-
-```markdown
----
-type: bmad-distillate
-sources:
-  - "product-brief-bmad-next-gen-installer.md"
-  - "product-brief-bmad-next-gen-installer-discovery-notes.md"
-downstream_consumer: "PRD creation"
-created: "2026-03-13"
-token_estimate: 1450
-parts: 1
----
-
-## Core Concept
-- BMAD Next-Gen Installer: replaces monolithic Node.js CLI with skill-based plugin architecture for distributing BMAD methodology across 40+ AI platforms
-- Three layers: self-describing plugins (bmad-manifest.json), cross-platform install via Vercel skills CLI (MIT), runtime registration via bmad-init skill
-- Transforms BMAD from dev-only methodology into open platform for any domain (creative, therapeutic, educational, personal)
-
-## Problem
-- Current installer maintains ~20 platform configs manually; each platform convention change requires installer update, test, release — largest maintenance burden on team
-- Node.js/npm required — blocks non-technical users on UI-based platforms (Claude Co-Work, etc.)
-- CSV manifests are static, generated once at install; no runtime scanning/registration
-- Unsustainable at 40+ platforms; new tools launching weekly
-
-## Solution Architecture
-- Plugins: skill bundles with Anthropic plugin standard as base format + bmad-manifest.json extending for BMAD-specific metadata (installer options, capabilities, help integration, phase ordering, dependencies)
-- Existing manifest example: `{"module-code":"bmm","replaces-skill":"bmad-create-product-brief","capabilities":[{"name":"create-brief","menu-code":"CB","supports-headless":true,"phase-name":"1-analysis","after":["brainstorming"],"before":["create-prd"],"is-required":true}]}`
-- Vercel skills CLI handles platform translation; integration pattern (wrap/fork/call) is PRD decision
-- bmad-init: global skill scanning installed bmad-manifest.json files, registering capabilities, configuring project settings; always included as base skill in every bundle (solves bootstrapping)
-- bmad-update: plugin update path without full reinstall; technical approach (diff/replace/preserve customizations) is PRD decision
-- Distribution tiers: (1) NPX installer wrapping skills CLI for technical users, (2) zip bundle + platform-specific README for non-technical users, (3) future marketplace
-- Non-technical path has honest friction: "copy to right folder" requires knowing where; per-platform README instructions; improves over time as low-code space matures
-
-## Differentiation
-- Anti-fragmentation: BMAD = cross-platform constant; no competitor provides shared methodology layer across AI tools
-- Curated quality: all submissions gated, human-reviewed by BMad + core team; 13.4% of community skills have critical vulnerabilities (Snyk 2026); quality gate value increases as ecosystem gets noisier
-- Domain-agnostic: no competitor builds beyond software dev workflows; same plugin system powers any domain via BMAD Builder (separate initiative)
-
-## Users (ordered by v1 priority)
-- Module authors (primary v1): package/test/distribute plugins independently without installer changes
-- Developers: single-command install on any of 40+ platforms via NPX
-- Non-technical users: install without Node/Git/terminal; emerging segment including PMs, designers, educators
-- Future plugin creators: non-dev authors using BMAD Builder; need distribution without building own installer
-
-## Success Criteria
-- Zero (or near-zero) custom platform directory code; delegated to skills CLI ecosystem
-- Installation verified on top platforms by volume; skills CLI handles long tail
-- Non-technical install path validated with non-developer users
-- bmad-init discovers/registers all plugins from manifests; clear errors for malformed manifests
-- At least one external module author successfully publishes plugin using manifest system
-- bmad-update works without full reinstall
-- Existing CLI users have documented migration path
-
-## Scope
-- In: manifest spec, bmad-init, bmad-update, Vercel CLI integration, NPX installer, zip bundles, migration path
-- Out: BMAD Builder, marketplace web platform, skill conversion (prerequisite, separate), one-click install for all platforms, monetization, quality certification process (gated-submission principle is architectural requirement; process defined separately)
-- Deferred: CI/CD integration, telemetry for module authors, air-gapped enterprise install, zip bundle integrity verification (checksums/signing), deeper non-technical platform integrations
-
-## Current Installer (migration context)
-- Entry: `tools/cli/bmad-cli.js` (Commander.js) → `tools/cli/installers/lib/core/installer.js`
-- Platforms: `platform-codes.yaml` (~20 platforms with target dirs, legacy dirs, template types, special flags)
-- Manifests: CSV files (skill/workflow/agent-manifest.csv) are current source of truth, not JSON
-- External modules: `external-official-modules.yaml` (CIS, GDS, TEA, WDS) from npm with semver
-- Dependencies: 4-pass resolver (collect → parse → resolve → transitive); YAML-declared only
-- Config: prompts for name, communication language, document output language, output folder
-- Skills already use directory-per-skill layout; bmad-manifest.json sidecars exist but are not source of truth
-- Key shift: CSV-based static manifests → JSON-based runtime scanning
-
-## Vercel Skills CLI
-- `npx skills add <source>` — GitHub, GitLab, local paths, git URLs
-- 40+ agents; per-agent path mappings; symlinks (recommended) or copies
-- Scopes: project-level or global
-- Discovery: `skills/`, `.agents/skills/`, agent-specific paths, `.claude-plugin/marketplace.json`
-- Commands: add, list, find, remove, check, update, init
-- Non-interactive: `-y`, `--all` flags for CI/CD
-
-## Competitive Landscape
-- No competitor combines structured methodology + plugin marketplace (whitespace)
-- Skills.sh (Vercel): 83K skills, dev-only, 20% trigger reliability without explicit prompting
-- SkillsMP: 400K skills, aggregator only, no curation
-- ClawHub: 3.2K curated, versioning, small
-- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only
-- Market: $7.84B (2025) → $52.62B (2030); Agent Skills spec ~4 months old, 351K+ skills; standards converging under Linux Foundation AAIF (MCP, AGENTS.md, A2A)
-
-## Rejected Alternatives
-- Building own platform support matrix: unsustainable at 40+; delegate to Vercel ecosystem
-- One-click install for non-technical v1: emerging space; guidance-based, improve over time
-- Prior roadmap/brainstorming: clean start, unconstrained by previous planning
-
-## Open Questions
-- Vercel CLI integration pattern: wrap/fork/call/peer dependency?
-- bmad-update mechanics: diff/replace? Preserve user customizations?
-- Migration story: command/manual reinstall/compatibility shim?
-- Cross-platform testing: CI matrix for top N? Community testing for rest?
-- bmad-manifest.json as open standard submission to Agent Skills governance?
-- Platforms NOT supported by Vercel skills CLI?
-- Manifest versioning strategy for backward compatibility?
-- Plugin author getting-started experience and tooling?
-
-## Opportunities
-- Module authors as acquisition channel: each published plugin distributes BMAD to creator's audience
-- CI/CD integration: bmad-init as pipeline one-liner increases stickiness
-- Educational institutions: structured methodology + non-technical install → university AI curriculum
-- Skill composability: mixing BMAD modules with third-party skills for custom methodology stacks
-
-## Risks
-- Manifest format evolution creates versioning/compatibility burden once third-party authors publish
-- Quality gate needs defined process, not just claim — gated review model addresses
-- 40+ platform testing environments even with Vercel handling translation
-- Scope creep pressure from marketplace vision (explicitly excluded but primary long-term value)
-- Vercel dependency: minor supply-chain risk; MIT license allows fork if deprioritized
-```

package/.opencode/skills/bmad-distillator/resources/splitting-strategy.md

@@ -1,78 +0,0 @@
-# Semantic Splitting Strategy
-
-When the source content is large (exceeds ~15,000 tokens) or a token_budget requires it, split the distillate into semantically coherent sections rather than arbitrary size breaks.
-
-## Why Semantic Over Size-Based
-
-Arbitrary splits (every N tokens) break coherence. A downstream workflow loading "part 2 of 4" gets context fragments. Semantic splits produce self-contained topic clusters that a workflow can load selectively — "give me just the technical decisions section" — which is more useful and more token-efficient for the consumer.
-
-## Splitting Process
-
-### 1. Identify Natural Boundaries
-
-After the initial extraction and deduplication (Steps 1-2 of the compression process), look for natural semantic boundaries:
-- Distinct problem domains or functional areas
-- Different stakeholder perspectives (users, technical, business)
-- Temporal boundaries (current state vs future vision)
-- Scope boundaries (in-scope vs out-of-scope vs deferred)
-- Phase boundaries (analysis, design, implementation)
-
-Choose boundaries that produce sections a downstream workflow might load independently.
-
-### 2. Assign Items to Sections
-
-For each extracted item, assign it to the most relevant section. Items that span multiple sections go in the root distillate.
-
-Cross-cutting items (items relevant to multiple sections):
-- Constraints that affect all areas → root distillate
-- Decisions with broad impact → root distillate
-- Section-specific decisions → section distillate
-
-### 3. Produce Root Distillate
-
-The root distillate contains:
-- **Orientation** (3-5 bullets): what was distilled, from what sources, for what consumer, how many sections
-- **Cross-references**: list of section distillates with 1-line descriptions
-- **Cross-cutting items**: facts, decisions, and constraints that span multiple sections
-- **Scope summary**: high-level in/out/deferred if applicable
-
-### 4. Produce Section Distillates
-
-Each section distillate must be self-sufficient — a reader loading only one section should understand it without the others.
-
-Each section includes:
-- **Context header** (1 line): "This section covers [topic]. Part N of M from [source document names]."
-- **Section content**: thematically-grouped bullets following the same compression rules as a single distillate
-- **Cross-references** (if needed): pointers to other sections for related content
-
-### 5. Output Structure
-
-Create a folder `{base-name}-distillate/` containing:
-
-```
-{base-name}-distillate/
-├── _index.md           # Root distillate: orientation, cross-cutting items, section manifest
-├── 01-{topic-slug}.md  # Self-contained section
-├── 02-{topic-slug}.md
-└── 03-{topic-slug}.md
-```
-
-Example:
-```
-product-brief-distillate/
-├── _index.md
-├── 01-problem-solution.md
-├── 02-technical-decisions.md
-└── 03-users-market.md
-```
-
-## Size Targets
-
-When a token_budget is specified:
-- Root distillate: ~20% of budget (orientation + cross-cutting items)
-- Remaining budget split proportionally across sections based on content density
-- If a section exceeds its proportional share, compress more aggressively or sub-split
-
-When no token_budget but splitting is needed:
-- Aim for sections of 3,000-5,000 tokens each
-- Root distillate as small as possible while remaining useful standalone

package/.opencode/skills/bmad-distillator/scripts/analyze_sources.py

@@ -1,300 +0,0 @@
-# /// script
-# /// requires-python = ">=3.10"
-# /// dependencies = []
-# ///
-"""Analyze source documents for the distillation generator.
-
-Enumerates files from paths/folders/globs, computes sizes and token estimates,
-detects document types from naming conventions, and suggests groupings for
-related documents (e.g., a brief paired with its discovery notes).
-
-Accepts: file paths, folder paths (scans recursively for .md/.txt/.yaml/.yml/.json),
-or glob patterns. Skips node_modules, .git, __pycache__, .venv, _bmad-output.
-
-Output JSON structure:
-  status: "ok" | "error"
-  files[]: path, filename, size_bytes, estimated_tokens, doc_type
-  summary: total_files, total_size_bytes, total_estimated_tokens
-  groups[]: group_key, files[] with role (primary/companion/standalone)
-    - Groups related docs by naming convention (e.g., brief + discovery-notes)
-  routing: recommendation ("single" | "fan-out"), reason
-    - single: ≤3 files AND ≤15K estimated tokens
-    - fan-out: >3 files OR >15K estimated tokens
-  split_prediction: prediction ("likely" | "unlikely"), reason, estimated_distillate_tokens
-    - Estimates distillate at ~1/3 source size; splits if >5K tokens
-"""
-
-from __future__ import annotations
-
-import argparse
-import glob
-import json
-import os
-import re
-import sys
-from pathlib import Path
-
-# Extensions to include when scanning folders
-INCLUDE_EXTENSIONS = {".md", ".txt", ".yaml", ".yml", ".json"}
-
-# Directories to skip when scanning folders
-SKIP_DIRS = {
-    "node_modules", ".git", "__pycache__", ".venv", "venv",
-    ".claude", "_bmad-output", ".cursor", ".vscode",
-}
-
-# Approximate chars per token for estimation
-CHARS_PER_TOKEN = 4
-
-# Thresholds
-SINGLE_COMPRESSOR_MAX_TOKENS = 15_000
-SINGLE_DISTILLATE_MAX_TOKENS = 5_000
-
-# Naming patterns for document type detection
-DOC_TYPE_PATTERNS = [
-    (r"discovery[_-]notes", "discovery-notes"),
-    (r"product[_-]brief", "product-brief"),
-    (r"research[_-]report", "research-report"),
-    (r"architecture", "architecture-doc"),
-    (r"prd", "prd"),
-    (r"distillate", "distillate"),
-    (r"changelog", "changelog"),
-    (r"readme", "readme"),
-    (r"spec", "specification"),
-    (r"requirements", "requirements"),
-    (r"design[_-]doc", "design-doc"),
-    (r"meeting[_-]notes", "meeting-notes"),
-    (r"brainstorm", "brainstorming"),
-    (r"interview", "interview-notes"),
-]
-
-# Patterns for grouping related documents
-GROUP_PATTERNS = [
-    # base document + discovery notes
-    (r"^(.+?)(?:-discovery-notes|-discovery_notes)\.(\w+)$", r"\1.\2"),
-    # base document + appendix
-    (r"^(.+?)(?:-appendix|-addendum)(?:-\w+)?\.(\w+)$", r"\1.\2"),
-    # base document + review/feedback
-    (r"^(.+?)(?:-review|-feedback)\.(\w+)$", r"\1.\2"),
-]
-
-
-def resolve_inputs(inputs: list[str]) -> list[Path]:
-    """Resolve input arguments to a flat list of file paths."""
-    files: list[Path] = []
-    for inp in inputs:
-        path = Path(inp)
-        if path.is_file():
-            files.append(path.resolve())
-        elif path.is_dir():
-            for root, dirs, filenames in os.walk(path):
-                dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
-                for fn in sorted(filenames):
-                    fp = Path(root) / fn
-                    if fp.suffix.lower() in INCLUDE_EXTENSIONS:
-                        files.append(fp.resolve())
-        else:
-            # Try as glob
-            matches = glob.glob(inp, recursive=True)
-            for m in sorted(matches):
-                mp = Path(m)
-                if mp.is_file() and mp.suffix.lower() in INCLUDE_EXTENSIONS:
-                    files.append(mp.resolve())
-    # Deduplicate while preserving order
-    seen: set[Path] = set()
-    deduped: list[Path] = []
-    for f in files:
-        if f not in seen:
-            seen.add(f)
-            deduped.append(f)
-    return deduped
-
-
-def detect_doc_type(filename: str) -> str:
-    """Detect document type from filename."""
-    name_lower = filename.lower()
-    for pattern, doc_type in DOC_TYPE_PATTERNS:
-        if re.search(pattern, name_lower):
-            return doc_type
-    return "unknown"
-
-
-def suggest_groups(files: list[Path]) -> list[dict]:
-    """Suggest document groupings based on naming conventions."""
-    groups: dict[str, list[dict]] = {}
-    ungrouped: list[dict] = []
-
-    file_map = {f.name: f for f in files}
-
-    assigned: set[str] = set()
-
-    for f in files:
-        if f.name in assigned:
-            continue
-
-        matched = False
-        for pattern, base_pattern in GROUP_PATTERNS:
-            m = re.match(pattern, f.name, re.IGNORECASE)
-            if m:
-                # This file is a companion — find its base
-                base_name = re.sub(pattern, base_pattern, f.name, flags=re.IGNORECASE)
-                group_key = base_name
-                if group_key not in groups:
-                    groups[group_key] = []
-                    # Add the base file if it exists
-                    if base_name in file_map and base_name not in assigned:
-                        groups[group_key].append({
-                            "path": str(file_map[base_name]),
-                            "filename": base_name,
-                            "role": "primary",
-                        })
-                        assigned.add(base_name)
-                groups[group_key].append({
-                    "path": str(f),
-                    "filename": f.name,
-                    "role": "companion",
-                })
-                assigned.add(f.name)
-                matched = True
-                break
-
-        if not matched:
-            # Check if this file is a base that already has companions
-            if f.name in groups:
-                continue  # Already added as primary
-            ungrouped.append({
-                "path": str(f),
-                "filename": f.name,
-            })
-
-    result = []
-    for group_key, members in groups.items():
-        result.append({
-            "group_key": group_key,
-            "files": members,
-        })
-    for ug in ungrouped:
-        if ug["filename"] not in assigned:
-            result.append({
-                "group_key": ug["filename"],
-                "files": [{"path": ug["path"], "filename": ug["filename"], "role": "standalone"}],
-            })
-
-    return result
-
-
-def analyze(inputs: list[str], output_path: str | None = None) -> None:
-    """Main analysis function."""
-    files = resolve_inputs(inputs)
-
-    if not files:
-        result = {
-            "status": "error",
-            "error": "No readable files found from provided inputs",
-            "inputs": inputs,
-        }
-        output_json(result, output_path)
-        return
-
-    # Analyze each file
-    file_details = []
-    total_chars = 0
-    for f in files:
-        size = f.stat().st_size
-        total_chars += size
-        file_details.append({
-            "path": str(f),
-            "filename": f.name,
-            "size_bytes": size,
-            "estimated_tokens": size // CHARS_PER_TOKEN,
-            "doc_type": detect_doc_type(f.name),
-        })
-
-    total_tokens = total_chars // CHARS_PER_TOKEN
-    groups = suggest_groups(files)
-
-    # Routing recommendation
-    if len(files) <= 3 and total_tokens <= SINGLE_COMPRESSOR_MAX_TOKENS:
-        routing = "single"
-        routing_reason = (
-            f"{len(files)} file(s), ~{total_tokens:,} estimated tokens — "
-            f"within single compressor threshold"
-        )
-    else:
-        routing = "fan-out"
-        routing_reason = (
-            f"{len(files)} file(s), ~{total_tokens:,} estimated tokens — "
-            f"exceeds single compressor threshold "
-            f"({'>' + str(SINGLE_COMPRESSOR_MAX_TOKENS) + ' tokens' if total_tokens > SINGLE_COMPRESSOR_MAX_TOKENS else '> 3 files'})"
-        )
-
-    # Split prediction
-    estimated_distillate_tokens = total_tokens // 3  # rough: distillate is ~1/3 of source
-    if estimated_distillate_tokens > SINGLE_DISTILLATE_MAX_TOKENS:
-        split_prediction = "likely"
-        split_reason = (
-            f"Estimated distillate ~{estimated_distillate_tokens:,} tokens "
-            f"exceeds {SINGLE_DISTILLATE_MAX_TOKENS:,} threshold"
-        )
-    else:
-        split_prediction = "unlikely"
-        split_reason = (
-            f"Estimated distillate ~{estimated_distillate_tokens:,} tokens "
-            f"within {SINGLE_DISTILLATE_MAX_TOKENS:,} threshold"
-        )
-
-    result = {
-        "status": "ok",
-        "files": file_details,
-        "summary": {
-            "total_files": len(files),
-            "total_size_bytes": total_chars,
-            "total_estimated_tokens": total_tokens,
-        },
-        "groups": groups,
-        "routing": {
-            "recommendation": routing,
-            "reason": routing_reason,
-        },
-        "split_prediction": {
-            "prediction": split_prediction,
-            "reason": split_reason,
-            "estimated_distillate_tokens": estimated_distillate_tokens,
-        },
-    }
-
-    output_json(result, output_path)
-
-
-def output_json(data: dict, output_path: str | None) -> None:
-    """Write JSON to file or stdout."""
-    json_str = json.dumps(data, indent=2)
-    if output_path:
-        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-        Path(output_path).write_text(json_str + "\n")
-        print(f"Results written to {output_path}", file=sys.stderr)
-    else:
-        print(json_str)
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(
-        description=__doc__,
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-    )
-    parser.add_argument(
-        "inputs",
-        nargs="+",
-        help="File paths, folder paths, or glob patterns to analyze",
-    )
-    parser.add_argument(
-        "-o", "--output",
-        help="Output JSON to file instead of stdout",
-    )
-    args = parser.parse_args()
-    analyze(args.inputs, args.output)
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()