Contributing

Contributing

For general development setup, changesets, and pull request workflow, see the Contributing Guide.

Project Structure

The Pi and OMP packages follow the same structure, differing only in package name and platform-specific directories:

maestria/
├── apps/
│   └── docs/                   # Documentation site
└── packages/
    ├── pi/                     # @maestria/pi extension
    │   ├── agents/             # 7 specialist agent .md files for pi-subagents
    │   ├── skills/             # 4 Pi skills (orchestrator, global-rules, handoff, iteration-limits)
    │   ├── src/
    │   │   ├── extension.ts    # Extension entry point, wires lifecycle hooks
    │   │   ├── agents.ts       # Agent file deployment to ~/.pi/agent/agents/
    │   │   ├── rules.ts        # Mode prompt injection
    │   │   ├── modes.ts        # Agent mode definitions (/fein, /sonar, /blitz)
    │   │   ├── state.ts        # Session state management
    │   │   ├── compaction.ts   # Context compaction preservation
    │   │   ├── subagent.ts     # Subagent dispatch via maestria_subagent
    │   │   ├── commands.ts     # Slash commands (/review, /handoff, etc.)
    │   │   └── tools.ts        # Tool call interceptors (review mode, dangerous patterns)
    │   ├── scripts/            # Validation and build scripts
    │   └── tests/              # Vitest test suite
    │
    └── omp/                    # @maestria/omp extension
        ├── agents/             # 7 specialist agent .md files for OMP dispatch
        ├── skills/             # 4 OMP skills (orchestrator, global-rules, handoff, iteration-limits)
        ├── src/
        │   ├── extension.ts    # Extension entry point
        │   ├── agents.ts       # Agent file deployment to ~/.omp/agent/agents/
        │   ├── rules.ts        # Mode prompt injection
        │   ├── modes.ts        # Workflow mode definitions
        │   ├── state.ts        # Session state management
        │   ├── compaction.ts   # Context compaction preservation
        │   ├── subagent.ts     # Subagent dispatch via native task()
        │   ├── commands.ts     # Slash commands
        │   └── tools.ts        # Tool call interceptors
        ├── scripts/            # Validation scripts
        └── tests/              # Vitest test suite

Sync Pipeline

All behavioral content is derived from canonical sources in packages/core/agent-directives/. A unified sync.config.ts per package generates artifacts from the same canonical sources:

• Source: packages/core/agent-directives/specialists/ (7 specialist prompts) + packages/core/agent-directives/rules.md (global rules)
• Output: agents/*.md (7 specialist agent files) + skills/orchestrator/SKILL.md + skills/global-rules/SKILL.md
• Transforms: Strips canonical frontmatter, applies platform-specific replacements
• Usage: Agent files are deployed to the platform’s agent discovery directory at startup; skill files are auto-injected by the platform’s resource loader from the manifest field into every session’s system prompt

Platform-specific transforms

Transform	Pi	OMP
Agent references	@agent → /agent	@agent → bare name (e.g. adventurer)
Dispatch rewrite	task() → maestria_subagent()	task() kept as-is (native task() tool)

Running the sync

# Regenerate all Pi artifacts from canonical sources
pnpm --filter @maestria/pi sync

# Regenerate all OMP artifacts from canonical sources
pnpm --filter @maestria/omp sync

The orchestrator, global rules, and all 7 specialist agent files are generated in a single pass per package. The sync is auto-checked by CI via scripts/check-sync.

Generated artifacts are validated:

pnpm --filter @maestria/pi validate
pnpm --filter @maestria/omp validate

Making Changes

Modifying Specialist Prompts, Global Rules, or Orchestrator Prompt

All specialist prompts, global rules, and the orchestrator prompt are authored in canonical sources under packages/core/agent-directives/. After editing, regenerate artifacts for both platforms:

pnpm --filter @maestria/pi sync && pnpm --filter @maestria/pi validate
pnpm --filter @maestria/omp sync && pnpm --filter @maestria/omp validate

Adding or Modifying Skills

Skills fall into two categories:

Canonical skills (orchestrator, global-rules) - these are synced from core via sync.config.ts. Edit the canonical source, then run pnpm sync for each platform.

Platform-only methodology skills (handoff, iteration-limits) - these live in each package’s skills/ directory and have no canonical source. Each skill directory contains a SKILL.md file. To add a new platform-only skill, create a directory under skills/ with a valid SKILL.md (frontmatter with name and description). Validate with:

pnpm --filter @maestria/pi validate-skills
pnpm --filter @maestria/omp validate-skills

Modifying Extension Code

Both packages share the same file structure:

File	Purpose
extension.ts	Extension entry point, registers all lifecycle hooks
agents.ts	Deploys specialist agent files to platform’s agent discovery directory
rules.ts	Mode prompt injection
modes.ts	Workflow mode definitions and commands
state.ts	Session state tracking and persistence
compaction.ts	Context compaction for long sessions
subagent.ts	Subagent dispatch (maestria_subagent for Pi, native task() for OMP)
commands.ts	Slash commands
tools.ts	Tool call interceptors and dangerous pattern detection

Building and Testing

# Build the packages
pnpm --filter @maestria/pi build
pnpm --filter @maestria/omp build

# Run tests (Vitest)
pnpm --filter @maestria/pi test
pnpm --filter @maestria/omp test

# Validate generated artifacts
pnpm --filter @maestria/pi validate
pnpm --filter @maestria/omp validate

# Format, lint, and type-check
vp check

Test suites are written with Vitest and live in each package’s tests/ directory. You can run individual test files:

pnpm --filter @maestria/pi test -- tests/commands.test.ts
pnpm --filter @maestria/omp test -- tests/commands.test.ts

See Also

• Contributing Guide - General setup, changesets, and PR process
• Reference - Commands, dispatch, and session management