# Contributing

`@maestria/codex` is generated from the canonical directives in
`packages/core/agent-directives/`. The package adapts those directives to Codex's namespaced skill
format; it does not duplicate methodology content by hand.

## Package structure

```text
packages/codex/
├── .codex-plugin/plugin.json  # Hand-authored plugin manifest
├── skills/                    # Generated SKILL.md projections
├── sync.config.ts             # Codex-specific transforms and frontmatter
├── tests/plugin.test.ts       # Manifest and generated-file contracts
├── INSTALL.md
├── README.md
└── CHANGELOG.md
```

The repository's Codex marketplace is generated by the Maestria CLI at install time because Codex
marketplaces use local plugin source paths. The staging directory contains the published npm
package and is not a second canonical source.

## Canonical source workflow

1. Edit `packages/core/agent-directives/`, never generated files under `packages/codex/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 the workspace checks.

```bash
scripts/sync-all
scripts/check-sync
pnpm --filter @maestria/codex test
```

## Projection rules

The Codex sync config:

- maps the 7 specialist directives to `skills/<name>/SKILL.md`;
- namespaces specialist references as `$maestria:<name>`;
- packages workflow modes as skills because the verified Codex projection surface is `skills/`;
- states read-only roles as advisory rather than claiming tool enforcement;
- keeps hooks, MCP, model configuration, and `AGENTS.md` writing out of scope.

## Validation

Run the Codex plugin-creator validator against the package and inspect the generated skill files:

```bash
python3 /path/to/plugin-creator/scripts/validate_plugin.py packages/codex
pnpm --filter @maestria/codex test
```

Support remains provisional until the pinned Codex CLI behavior and the marketplace/plugin install
flow have been reverified.