# 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

```text
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.

```bash
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

```bash
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.