pi-mission-control 0.0.0-dev

package/README.md

@@ -0,0 +1,205 @@
+# pi-mission-control
+
+Visual mission orchestration extension for pi with agent hierarchy and durable state.
+
+## Overview
+
+Mission Control provides a structured, visual approach to complex software development tasks. It orchestrates a hierarchy via the `mission-orchestrator` skill loaded into the main pi agent — the Orchestrator (Tech Lead/PM) delegates to Workers (Implementers) and Auditors (QA Reviewers) — to break down, execute, and verify work through durable file-based state.
+
+**Architecture Note**: The Orchestrator is a skill representing the main user-facing pi agent behavior, not a standalone subagent. Only Worker and Auditor are spawned as subagents.
+
+## Features
+
+- **Agent Hierarchy**: Heavy-model Orchestrator delegates to light-model Workers and Auditors
+- **Durable State**: File-based state survives restarts and enables resume
+- **Visual TUI**: Real-time progress tracking with phases, tasks, and status
+- **Quality Gates**: Every task verified through Worker → Auditor PASS/FAIL cycle
+- **Memory**: Short-term per-run learnings distilled into long-term cross-run knowledge
+
+## Installation
+
+### Prerequisites
+
+1. Install `pi-subagents` (required):
+   ```bash
+   pi install npm:pi-subagents
+   ```
+
+2. Install `pi-ask-user` (required for structured approvals and guided interviews):
+   ```bash
+   pi install npm:pi-ask-user
+   ```
+
+### From npm (when published)
+
+```bash
+pi install npm:pi-mission-control
+```
+
+
+## Usage
+
+### Starting a Mission
+
+Once the extension is loaded, use the `/mission` command:
+
+```
+/mission
+```
+
+This will:
+1. Scaffold worker/auditor agents and skills into `.pi/` if first use
+2. Show the Mission Control TUI (idle state with "Init new mission" button)
+3. When initiated, the Orchestrator interviews you and produces requirements
+
+### Mission Lifecycle
+
+```
+/mission
+  ├─ Scaffolds worker/auditor agents + skills (first run)
+  ├─ Shows idle TUI with "Init new mission" button
+  └─ When initiated:
+       1. mission-orchestrator → Interview user, produce 00-requirements.md
+       2. mission-tech-lead → Design system → 01-architecture.md + 02-validation.md
+       3. mission-pm → Break work into phases/tasks via add_phase/add_task tools
+       4. mission-orchestrator → Execute via Worker → Auditor cycle
+       5. mission-memory → Distill learnings to long_term.md
+```
+
+### Resuming a Mission
+
+To resume a previous mission:
+
+```
+resume mission run-20260411-143022
+```
+
+The Orchestrator will load the previous state from `run.json` and continue.
+
+## Architecture
+
+### Agents
+
+| Agent | Model | Role |
+|-------|-------|------|
+| **orchestrator** | heavy (skill) | Tech Lead, PM, Interviewer. Main pi agent behavior via `mission-orchestrator` skill. Manages workflow and spawns subagents. |
+| **worker** | light (subagent) | Implementer. Executes tasks in isolated git worktrees. Spawned by orchestrator. |
+| **auditor** | light (subagent) | QA Reviewer. Verifies work against contracts with PASS/FAIL. Spawned by orchestrator. |
+
+### Skills
+
+| Skill | Purpose |
+|-------|---------|
+| **mission-orchestrator** | Primary orchestration skill representing the main pi agent behavior. Loaded first, routes between requirements, architecture, planning, execution, and closeout. |
+| **mission-research** | Detailed requirements/interview workflow used by the orchestrator when requirements are missing or unclear. |
+| **mission-tech-lead** | Detailed architecture and validation workflow used by the orchestrator after requirements are approved. |
+| **mission-pm** | Detailed planning workflow used by the orchestrator to register phases/tasks. |
+| **mission-memory** | Closeout and long-term memory distillation workflow. |
+
+### Runtime Files
+
+```
+.pi/
+├── agents/                      # Scaffolded subagent definitions
+│   ├── worker.md
+│   └── auditor.md
+├── skills/                      # Scaffolded skill definitions
+│   ├── mission-research/
+│   ├── mission-tech-lead/
+│   ├── mission-pm/
+│   ├── mission-orchestrator/
+│   └── mission-memory/
+└── mission-control/
+    ├── state.json               # Volatile: active_run_id, phase, status
+    ├── memory/
+    │   └── long_term.md         # Cross-run distilled knowledge
+    └── runs/
+        └── run-<timestamp>/
+            ├── run.json         # Source of truth: phases, tasks, timestamps
+            ├── 00-requirements.md
+            ├── 01-architecture.md
+            ├── 02-validation.md
+            ├── short_term_memory.md
+            └── tasks/
+                └── <task-id>/
+                    ├── contract.md
+                    ├── worker-output.md
+                    └── auditor-report.md
+```
+
+## Development
+
+### Project Structure
+
+```
+pi-mission-control/
+├── package.json              # Package manifest with pi configuration
+├── tsconfig.json             # TypeScript configuration
+├── src/
+│   ├── index.ts              # Extension entry point
+│   ├── state.ts              # State types and file helpers
+│   ├── tools/                # Mission control tools
+│   │   ├── scaffold.ts       # mission_scaffold (command-only)
+│   │   ├── init.ts           # mission_init (command-only)
+│   │   ├── add-phase.ts      # add_phase (agent tool)
+│   │   ├── add-task.ts       # add_task (agent tool)
+│   │   ├── update-phase.ts   # update_phase (agent tool)
+│   │   ├── update-task.ts    # update_task (agent tool)
+│   │   ├── mission-complete.ts
+│   │   └── mission-resume.ts
+│   └── tui/                  # TUI components (read-only observer)
+│       ├── dashboard.ts
+│       ├── header.ts
+│       ├── phases-panel.ts
+│       ├── tasks-panel.ts
+│       ├── progress-bar.ts
+│       ├── past-runs.ts
+│       └── idle-view.ts
+├── agents/                   # Worker/auditor templates (copied on scaffold)
+├── skills/                   # Skill templates (copied on scaffold)
+└── templates/
+    └── state.json            # Initial state template
+```
+
+### Scripts
+
+```bash
+npm run build      # Compile TypeScript to dist/
+npm run dev        # Watch mode compilation
+npm run typecheck  # Type-check without emitting
+```
+
+### Testing Workflow
+
+1. Make changes to source files in `src/`
+2. Run `npm run typecheck` to validate TypeScript
+3. Test with `pi -e ./src/index.ts`
+4. Build with `npm run build` for production testing
+
+## Dependencies
+
+### Required Extensions
+
+| Extension | Required | Purpose |
+|-----------|----------|---------|
+| `pi-subagents` | **Required** | Spawns Worker and Auditor subagents in isolated git worktrees |
+| `pi-ask-user` | **Required** | Structured Q&A for user approvals, interviews, and ambiguity resolution |
+
+### Peer Dependencies
+
+These are provided by pi and should not be bundled:
+
+- `@mariozechner/pi-agent-core`
+- `@mariozechner/pi-ai`
+- `@mariozechner/pi-coding-agent`
+- `@mariozechner/pi-tui`
+- `@sinclair/typebox`
+
+### Dev Dependencies
+
+- `typescript` — TypeScript compiler
+- `@types/node` — Node.js type definitions
+
+## License
+
+MIT

package/agents/auditor.md

@@ -0,0 +1,45 @@
+---
+name: auditor
+model: light
+description: |
+  QA / Reviewer. Starts with a clean context. Reads the task contract,
+  reads the worker's output, inspects the git diff, and empirically runs tests
+  to verify the Validation Contract. Outputs a PASS or FAIL verdict.
+---
+
+# Auditor Agent
+
+You are an Auditor — a QA Reviewer with a clean, objective context.
+
+## Responsibilities
+- Read the task contract from `tasks/<task_id>/contract.md`
+- Read the worker's output from `tasks/<task_id>/worker-output.md`
+- Inspect the git diff to verify actual code changes
+- Empirically run tests to verify the Validation Contract
+- Output a PASS or FAIL verdict to `tasks/<task_id>/auditor-report.md`
+
+## Context
+Narrow and objective. Your only goal is to verify against the contract and
+output a verdict. You do not fix code — you only verify it.
+
+## Inputs
+- `contract.md` — original task contract with validation criteria
+- `worker-output.md` — worker's implementation summary and evidence
+- Worktree path — location of code to audit (from contract metadata)
+
+## Outputs
+- `auditor-report.md` — audit report containing:
+  - **Verification Steps Taken**: what you checked (diffs, tests run)
+  - **Findings**: any discrepancies between contract and implementation
+  - **Verdict**: exactly `VERDICT: PASS` or `VERDICT: FAIL`
+  - **Feedback**: actionable instructions if FAIL
+
+## Verdict Rules
+- **PASS**: Contract is fully satisfied, all tests pass, code quality acceptable
+- **FAIL**: Any deviation from contract, test failures, or quality issues
+
+## Rules
+- Be strict — if the contract says X and the worker did Y, that's a FAIL
+- Run tests empirically — don't trust the worker's word
+- Provide specific, actionable feedback on failure
+- Do not fix code — report only

package/agents/worker.md

@@ -0,0 +1,44 @@
+---
+name: worker
+model: light
+description: |
+  Implementer. Reads a specific task contract, navigates to an isolated git
+  worktree, writes code, writes tests, runs linters/tests, and outputs an
+  evidence report to worker-output.md.
+---
+
+# Worker Agent
+
+You are a Worker — a focused Implementer with narrow context.
+
+## Responsibilities
+- Read the specific task contract from `tasks/<task_id>/contract.md`
+- Work in an isolated git worktree (already prepared by the orchestrator)
+- Write code and tests according to the contract directives
+- Run linters and tests to verify your work
+- Output an evidence report to `tasks/<task_id>/worker-output.md`
+
+## Context
+Extremely narrow. Only know about the specific task assigned and the provided
+architectural context. Do not deviate from the contract. Do not communicate
+directly with the user or orchestrator — only through the output file.
+
+## Inputs
+- `contract.md` — task contract with:
+  - **Metadata**: task ID, phase name, worktree path
+  - **Context**: summarized architecture relevant to this task
+  - **Directives**: step-by-step implementation instructions
+  - **Validation criteria**: explicit conditions to meet
+  - **Output instructions**: mandate to write worker-output.md
+
+## Outputs
+- `worker-output.md` — implementation summary containing:
+  - **Summary of Changes**: what files were created or modified
+  - **Execution Log**: exact commands run and their raw output
+  - **Deviations**: notes if you had to deviate from the contract and why
+
+## Rules
+- Follow the contract exactly — do not add unrequested features
+- Run all validation commands specified in the contract
+- Document any deviations transparently
+- Do not communicate with the user — the orchestrator handles that

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * pi-mission-control Extension Entry Point
+ *
+ * Visual mission orchestration with agent hierarchy and durable state.
+ * Provides /mission command and tools for mission management.
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export default function missionControlExtension(pi: ExtensionAPI): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,+BAA+B,CAAC;AAuZvC,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAAC,EAAE,EAAE,YAAY,QA2O/D"}