Contributing

@maestria/prime-agent delivers the canonical Maestria directives to Prime Agent as standard Agent Skills, plus a small hand-authored Prime/Pi extension. The skills are generated by the core sync pipeline; the extension is source code.

Package structure

packages/prime-agent/
├── skills/                    # Generated Agent Skills (SKILL.md, 14 skills)
├── src/                       # Hand-authored Prime/Pi extension (TypeScript)
├── scripts/validate-skills.ts # Skill frontmatter/layout validator
├── sync.config.ts             # Prime-specific transforms and frontmatter
├── tests/                     # Generated-skill, extension, manifest, tarball tests
├── INSTALL.md
├── README.md
└── CHANGELOG.md

Canonical source workflow

The skills are generated from the canonical directives in packages/core/agent-directives/. Platform-specific derivation - skill names, descriptions, and Prime-specific notes - lives in sync.config.ts.

1. Edit packages/core/agent-directives/, never generated files under packages/prime-agent/skills/.
2. Run scripts/sync-all from the repository root.
3. Run scripts/check-sync to verify every platform projection.
4. Run the package tests and workspace checks.

scripts/sync-all
scripts/check-sync
pnpm --filter @maestria/prime-agent test

Projection rules

The Prime Agent sync config:

• maps the 7 specialist directives, orchestrator, global rules, handoff, iteration-limits, and the three workflow modes to skills/<name>/SKILL.md;
• uses the directory layout (skills/<name>/SKILL.md) because that is the layout Prime discovers in all documented skill locations (root .md files are ignored under .agents/skills/);
• emits only the required Agent Skills frontmatter (name matching the directory, and description);
• states read-only roles as advisory rather than claiming a runtime boundary;
• keeps the rlm recursive-subagent dispatch and JSON/RPC headless mode out of scope.

The extension

The extension (src/, compiled to dist/extension.mjs) is hand-authored and self-contained: it does not import @maestria/pi or @maestria/shared-pi, uses only the public Prime/Pi extension API (type-only local declarations in src/pi-api.ts mirroring the pinned fork), and loads its mode content from the generated skills/ so there is a single source of truth for mode text.

Validation

pnpm --filter @maestria/prime-agent validate   # frontmatter + layout
pnpm --filter @maestria/prime-agent build      # compile dist/extension.mjs
pnpm --filter @maestria/prime-agent test       # skills + extension + manifest + tarball tests

Support remains a Native candidate until runtime behavior in a live Prime session has been verified end to end.