Contributing
Each Maestria plugin has its own contributing guide with project structure, source file locations, and build commands. Developer documentation is at the repository root.
Canonical Source Workflow
Section titled “Canonical Source Workflow”Agent prompts, specialist personas, and global rules are authored in a single canonical source at packages/core/agent-directives/ and synced to all plugin packages via the config-driven sync pipeline.
Never edit the generated files in plugin-specific directories (packages/opencode/agents/, packages/pi/agents/, packages/pi/skills/, packages/kimi-code/skills/, or any rules/ directory) - they are overwritten on every sync.
Editing the Canonical Source
Section titled “Editing the Canonical Source”To modify an agent prompt or global rule:
- Edit the corresponding file in
packages/core/agent-directives/specialists/(e.g.,builder.mdfor the Builder specialist) orpackages/core/agent-directives/rules.mdfor global rules - Run
scripts/sync-allfrom the repo root to regenerate all plugin-specific files - Verify with
scripts/check-sync(also run as part ofvp check)
The canonical source is plain Markdown without platform-specific syntax, YAML frontmatter, or role prefixes (@). Platform adaptations are handled by the sync pipeline’s transforms.
How the Sync Pipeline Works
Section titled “How the Sync Pipeline Works”Each plugin has a sync.config.ts that defines how canonical content is adapted:
| Plugin | Config | Transforms |
|---|---|---|
@maestria/opencode |
packages/opencode/sync.config.ts |
Adds YAML frontmatter with permissions per specialist |
@maestria/kimi-code |
packages/kimi-code/sync.config.ts |
Converts to SKILL.md format with 23 text replacements, persona prepends, and routing table |
@maestria/pi |
packages/pi/sync.config.ts |
10 text replacements (@adventurer → /adventurer, task() → maestria_subagent()) |
Running the Docs Site
Section titled “Running the Docs Site”vp run @maestria/docs#devThis starts the Astro dev server for the user-facing documentation at apps/docs/.