# Contributing

# Contributing

> For general development setup, changesets, and pull request workflow, see the [Contributing Guide](/core/contributing/).

## 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

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

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

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

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

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

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

## See Also

- [Contributing Guide](/core/contributing/) - General setup, changesets, and PR process
- [Reference](/pi-omp/reference/) - Commands, dispatch, and session management