pi-director

Autonomous project director for pi. Three operations, three artifacts:

| Command | Operation | Artifact | Question | |---------|-----------|----------|----------| | /next | Analyze & Recommend | NEXT.md | What's outside scope? | | /choose | Clarify Intent | CHOICES.md | Why and what? | | /build | TDD Development | PLAN.md | How to implement? |

Autonomy Model

• CHOICES.md — user-steered intent. Only the user modifies it (via interviews and feedback).
• Within CHOICES.md scope — director acts autonomously. Bugs, gaps, refactors aligned with existing choices need no approval.
• Outside CHOICES.md scope — surfaces in NEXT.md for user review. Scope changes, contradictions, and new concerns require user acceptance before action.

Priority Ladder

All work follows: UX Quality > Security > Scale > Efficiency. Each level is a release gate. Higher priorities never regress when pursuing lower ones.

Install

npm install @a-canary/pi-director @a-canary/pi-choose-wisely @a-canary/pi-upskill

Architecture

┌──────────────────────────────────────────┐
│              pi-director                 │
│  ┌───────┐  ┌────────┐  ┌──────┐        │
│  │ /next │  │/choose │  │/build│        │
│  └───┬───┘  └───┬────┘  └──┬───┘        │
│      │          │          │             │
│  ┌───▼──────────▼──────────▼──────┐      │
│  │      Subagent Orchestration    │      │
│  │  scout  planner  builder       │      │
│  │  reviewer  writer              │      │
│  └────────────────────────────────┘      │
│                                          │
│  ┌─────────────────────────────────┐     │
│  │  Nightly Extension (cron)       │     │
│  │  /nightly-status /nightly-run   │     │
│  └─────────────────────────────────┘     │
├──────────────────────────────────────────┤
│  pi-choose-wisely   │   pi-upskill      │
│  CHOICES.md mgmt    │   corrections     │
└──────────────────────────────────────────┘

Package Structure

pi-director/
├── agents/                 # Subagent definitions
│   ├── director.md         # strategic — orchestration
│   ├── planner.md          # strategic — architecture
│   ├── reviewer.md         # tactical — code review
│   ├── builder.md          # operational — implementation
│   ├── scout.md            # scout — fast recon
│   └── writer.md           # operational — documentation
├── skills/
│   ├── next/               # /next — analysis engine
│   │   ├── SKILL.md
│   │   └── lib/            # scanner modules + ranker
│   ├── build/              # /build — TDD phase loop
│   │   ├── SKILL.md
│   │   └── lib/            # phase-loop, hard-stops, regression-check
│   └── choose/             # /choose — wraps pi-choose-wisely
│       ├── SKILL.md
│       └── lib/            # pipeline documentation
├── extensions/
│   └── nightly-analysis.ts # scheduled /next execution
├── templates/
│   └── NEXT.md             # recommendation output format
├── CHOICES.md              # project intent
├── PLAN.md                 # implementation phases
└── package.json

Commands

| Command | Description | |---------|-------------| | /next | Analyze project data, generate recommendations | | /choose | Clarify project intent (wraps pi-choose-wisely) | | /build | Execute PLAN.md phases via TDD loop | | /nightly-status | Show analysis schedule and last run | | /nightly-run | Trigger analysis immediately | | /nightly-set <hour> | Set daily analysis hour (0-23) |

Dependencies

• @a-canary/pi-choose-wisely — CHOICES.md management, replan
• @a-canary/pi-upskill — Correction analysis, session learning
• @mariozechner/pi-coding-agent — Pi runtime