# Contributing

# Contributing

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

## Project Structure

```
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 source code
        │   ├── extension.ts  # Extension entry point, wires lifecycle hooks
        │   ├── agents.ts     # Agent file deployment to ~/.pi/agent/agents/
        │   ├── rules.ts      # Mode prompt injection (before_agent_start handler)
        │   ├── modes.ts      # Agent mode definitions (/fein, /sonar, /blitz)
        │   ├── state.ts      # Session state management
        │   ├── compaction.ts # Context compaction preservation
        │   ├── subagent.ts   # maestria_subagent tool + cross-extension events
        │   ├── commands.ts   # Pi slash commands (/orchestrate, /review, etc.)
        │   └── tools.ts      # Tool call interceptors (review mode, dangerous patterns)
        ├── scripts/          # Validation and build scripts
        └── tests/            # Vitest test suite (10 test files, ~63 tests)
```

## Sync Pipeline

All behavioral content is derived from canonical sources in `packages/core/agent-directives/`. A single unified `sync.config.ts` generates all Pi artifacts in one pass:

- **Source:** `packages/core/agent-directives/specialists/` (7 specialist prompts) + `packages/core/agent-directives/rules.md` (global rules)
- **Output:** `packages/pi/agents/*.md` (7 specialist agent files for pi-subagents) + `packages/pi/skills/orchestrator/SKILL.md` + `packages/pi/skills/global-rules/SKILL.md`
- **Transforms:** Strips canonical frontmatter, applies Pi replacements (`@agent` -> `/agent`, `task()` -> `maestria_subagent()`), wraps in pi-subagents agent format or Pi skill `SKILL.md` frontmatter depending on output path
- **Usage:** Agent files are deployed to `~/.pi/agent/agents/` at extension startup for pi-subagents discovery; skill files are auto-injected by Pi's resource loader from the `pi.skills` manifest field into every session's system prompt

### Running the sync

```bash
# Regenerate all generated artifacts from canonical sources
pnpm --filter @maestria/pi sync
```

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

Generated artifacts are validated:

```bash
pnpm --filter @maestria/pi 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 all Pi artifacts in a single step:

```bash
pnpm --filter @maestria/pi sync
pnpm --filter @maestria/pi 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`.

**Pi-only methodology skills** (handoff, iteration-limits) - these live in `packages/pi/skills/` and have no canonical source. Each skill directory contains a `SKILL.md` file. To add a new Pi-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
```

### Modifying Extension Code

| File            | Purpose                                                      |
| --------------- | ------------------------------------------------------------ |
| `extension.ts`  | Extension entry point, registers all lifecycle hooks         |
| `agents.ts`     | Deploys specialist agent files to pi-subagents discovery dir |
| `rules.ts`      | Mode prompt injection via `before_agent_start`               |
| `modes.ts`      | Workflow mode definitions and commands                       |
| `state.ts`      | Session state tracking and persistence                       |
| `compaction.ts` | Context compaction for long sessions                         |
| `subagent.ts`   | `maestria_subagent` tool, cross-extension events             |
| `commands.ts`   | Pi slash commands                                            |
| `tools.ts`      | Tool call interceptors and dangerous pattern detection       |

## Building and Testing

```bash
# Build the Pi package
pnpm --filter @maestria/pi build

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

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

# Format, lint, and type-check
vp check
```

Tests are written with Vitest and live in `packages/pi/tests/`. You can run individual test files:

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

## See Also

- [Contributing Guide](/core/contributing/) - General setup, changesets, and PR process