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

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.

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:

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.