Contributing

Contributing

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

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

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

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:

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:

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

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

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

See Also

• Contributing Guide - General setup, changesets, and PR process