67 lines
3.0 KiB
Markdown
67 lines
3.0 KiB
Markdown
# Phase 1: Schema and Format Review (PR #821)
|
|
|
|
Date: 2025-10-28
|
|
Branch: pr-821-review
|
|
|
|
## What we inspected
|
|
|
|
- BMAD agent schema implementation: `tools/schema/agent.js`
|
|
- Example BMAD agent: `src/modules/bmb/agents/bmad-builder.agent.yaml`
|
|
- Example PR agent (Claude): `subagentic/claude-subagents/agents/master.md`
|
|
|
|
## Findings
|
|
|
|
### BMAD Agent Schema (YAML)
|
|
|
|
- File extension: `*.agent.yaml`
|
|
- Validated via Zod schema (`tools/schema/agent.js`)
|
|
- Required structure:
|
|
- `agent.metadata` (id, name, title, icon, optional module)
|
|
- `agent.persona` (role, identity, communication_style, principles[])
|
|
- `agent.menu[]` (entries with `trigger`, `description`, and one command target: `workflow` | `validate-workflow` | `exec` | `action` | `tmpl` | `data` | `run-workflow`)
|
|
- Optional: `agent.critical_actions[]`, `agent.prompts[]`
|
|
- Module scoping derived from path: `src/modules/<module>/agents/`
|
|
|
|
### PR Subagent Format (Markdown)
|
|
|
|
- File extension: `.md` with YAML frontmatter
|
|
- Frontmatter keys observed: `name`, `description`, `model`, `color`
|
|
- Body contains prose defining behavior, commands (e.g., `*help`, `*task`), and resource lists
|
|
- Designed for editor-level runtime loading (e.g., `~/.claude/tasks`)
|
|
|
|
### Compatibility Assessment
|
|
|
|
- Schema: Incompatible (Markdown vs YAML schema)
|
|
- Data shape: Different core concepts (persona/menu vs freeform behavior & commands)
|
|
- Invocation model: Different (BMAD menus/workflows vs `*` commands and `@agent` entries)
|
|
|
|
## Implications
|
|
|
|
- BMAD validators (`validate:schemas`, tests) do not apply to `subagentic/` content
|
|
- Direct migration requires either:
|
|
1. An adapter to convert subagent MD to BMAD `*.agent.yaml` definitions, or
|
|
2. A generator to produce subagentic MD from BMAD YAML agents (reverse direction), or
|
|
3. Keep subagentic content external and reference it in docs
|
|
|
|
## Minimal Adapter Proposal (Option 1)
|
|
|
|
- Parser: Read Markdown, extract frontmatter (name/description) and derive persona/menu
|
|
- Mapping sketch:
|
|
- `agent.metadata`: id `<module or external>/subagentic/<name>`, name `<frontmatter.name>`, title from description, icon default
|
|
- `agent.persona`: role from name, identity from description; principles use subagent "Core Operating Principles"
|
|
- `agent.menu`: map `*` commands to menu `trigger` + `action` (`exec`), with descriptions from Commands section
|
|
- Output: Write to `src/modules/subagentic/agents/<agent>.agent.yaml` (new module)
|
|
- Caveat: Requires curation; not all commands map cleanly to BMAD command targets
|
|
|
|
## Current Repo Validation Status (context)
|
|
|
|
- `npm test` (fixtures) => 48 passed, 2 failed (fixture expectations)
|
|
- `npm run validate:schemas` (real agents) => 14 valid, 3 invalid (existing BMM agents with extra keys)
|
|
- These failures are unrelated to PR #821 content and pre-exist under `src/modules/bmm/agents/`
|
|
|
|
## Recommendation for Phase 2
|
|
|
|
- Do not attempt to validate `subagentic/` with BMAD schema (non-applicable)
|
|
- If integration is desired, spike an adapter script to convert 1-2 agents as proof of concept
|
|
- Otherwise, proceed with decision on documenting subagentic as an external alternative
|