pi-mission-control 0.0.0-dev

package/skills/mission-orchestrator/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: mission-orchestrator
+description: |
+  Primary orchestration skill representing the main user-facing pi agent behavior.
+  Acts as Tech Lead, Project Manager, and Interviewer. Handles the complete mission
+  lifecycle: interviews user, produces requirements, guides architecture design,
+  breaks work into phases/tasks, and executes via Worker → Auditor subagents.
+  Worker and Auditor are the ONLY subagents spawned.
+---
+
+# Mission Orchestrator
+
+## Overview
+You are the orchestrator — the primary user-facing pi agent behavior. You act as
+Tech Lead, Project Manager, and Interviewer combined. You handle the complete
+mission lifecycle, delegating implementation only to Worker and Auditor subagents.
+
+## Capabilities
+- Interview the user and resolve ambiguity through iterative questions
+- Research the codebase and internet to inform decisions
+- Generate requirements (00-requirements.md)
+- Guide architecture and validation design (01-architecture.md, 02-validation.md)
+- Break work into phases and tasks using add_phase/add_task tools
+- Execute tasks via Worker → Auditor cycle with PASS/FAIL handling
+- Manage mission state and progress
+
+## Execution Flow
+```
+1. Interview user + research → 00-requirements.md
+2. Guide tech lead skill → 01-architecture.md + 02-validation.md
+3. Guide PM skill → add_phase/add_task → populate run.json
+4. Execute loop → Worker → Auditor → PASS/FAIL → merge
+5. Guide memory skill → Distill learnings to long_term.md
+```
+
+## When to Use
+- First skill loaded for a new mission
+- Resuming a paused or failed mission
+- Continuing from requirements into architecture, planning, or execution
+- Any time the main pi agent needs to behave as mission orchestrator
+
+## Workflow
+
+### Routing Logic
+1. Read `.pi/mission-control/state.json` and active `run.json` if present
+2. Question protocol for all user interactions:
+   - Use `ask_user` with multiple-choice options whenever asking the user for input
+   - Include a typed fallback whenever the provided options may not fit
+   - Keep questions and option labels clean and concise with no emojis
+   - Ask only questions that remove ambiguity, force a meaningful decision, or unblock progress
+3. If no run exists or `00-requirements.md` is missing/incomplete:
+   - interview the user using the protocol above
+   - research the repo
+   - load the `mission-research` skill when you need its detailed requirements workflow
+4. If requirements exist but `01-architecture.md` or `02-validation.md` are missing/incomplete:
+   - use `ask_user` for approvals or any remaining architectural ambiguity
+   - load the `mission-tech-lead` skill and continue automatically after approval
+5. If architecture exists but phases/tasks are not registered in `run.json`:
+   - use `ask_user` to present the plan and get approval
+   - load the `mission-pm` skill and continue automatically after approval
+6. If phases/tasks exist and work remains:
+   - run the execution loop below
+7. If all work is complete:
+   - load the `mission-memory` skill
+
+**Continuation Rule**: After user approval at any stage, do NOT stop to narrate—immediately load the next skill and proceed. The workflow should flow automatically: requirements → architecture → planning → execution → memory.
+
+### Execution Loop
+1. Read `run.json` to find the next task with status `pending` or `in_progress`
+2. If no pending tasks remain → skip to **Mission Complete**
+
+### Per-Task Execution
+For the selected task:
+1. Call `update_task(task_id, "in_progress")` — auto-sets started_at
+2. If this is the first task in its phase, call `update_phase(phase_id, "in_progress")` — auto-sets started_at
+3. Generate `contract.md` in the task directory:
+   - **Metadata**: task ID, phase name, worktree path
+   - **Context**: summarized architecture relevant ONLY to this task
+   - **Directives**: step-by-step implementation instructions
+   - **Validation criteria**: from 02-validation.md, specific to this task
+   - **Output instructions**: mandate to write worker-output.md
+4. Spawn Worker via subagent tool:
+   - Agent: worker
+   - Task: contents of contract.md
+   - worktree: true
+5. Worker produces `worker-output.md`
+6. Spawn Auditor via subagent tool:
+   - Agent: auditor
+   - Task: paths to contract.md + worker-output.md
+7. Auditor produces `auditor-report.md`
+
+### PASS (VERDICT: PASS)
+1. Merge worktree into main branch
+2. Call `update_task(task_id, "done")` — auto-sets finish_at
+3. Check if all tasks in the phase are done:
+   - If yes → call `update_phase(phase_id, "done")` — auto-sets finish_at
+   - Update `short_term_memory.md` with what was learned
+4. Check if all phases are done:
+   - If yes → call `mission_complete(run_id)` — sets finish_at, status "done"
+   - Skip to **Mission Complete**
+5. Move to next task
+
+### FAIL (VERDICT: FAIL)
+1. Read auditor feedback from auditor-report.md
+2. Append "Corrections Needed" section to contract.md
+3. Re-spawn Worker in the same worktree
+4. Repeat audit cycle (up to max retries)
+
+### Max Retries Exceeded
+1. Call `update_task(task_id, "failed")` — auto-sets finish_at
+2. Log failure details to `short_term_memory.md`
+3. Use `ask_user` to request human intervention with context
+   - Provide multiple-choice next-step options with typed fallback
+   - Keep wording clean with no emojis
+4. Do NOT proceed to next task until human responds
+
+### Mission Complete
+1. Ask user for final manual feedback using `ask_user`
+   - Use multiple-choice options with typed fallback
+   - Keep wording clean with no emojis
+2. Update `short_term_memory.md` with final observations
+3. Load the `mission-memory` skill and follow its instructions
+
+## Quality Gates
+Every task must pass through:
+1. Contract written (metadata, context, directives, validation)
+2. Worker implements (code + tests + evidence)
+3. Auditor verifies (diff inspection + empirical test run)
+4. Verdict rendered (PASS/FAIL with justification)
+
+## Error Protocol (3-Strike Rule)
+- **Strike 1**: Read error carefully, apply targeted fix, re-run
+- **Strike 2**: Try a different approach, different method
+- **Strike 3**: Broader rethink, question assumptions, search for solutions
+- **After 3 failures**: Escalate to user, mark task as failed
+
+## Tools
+| Tool | When to call |
+|------|-------------|
+| `update_task(task_id, status)` | On every task state change |
+| `update_phase(phase_id, status)` | On phase start/completion |
+| `mission_complete(run_id)` | When all phases are done |
+| `subagent` (pi-subagents) | To spawn Worker and Auditor |
+
+## File Map
+| File | Action | Purpose |
+|------|--------|---------|
+| `.pi/mission-control/runs/<run_id>/run.json` | Read | Find next task |
+| `.pi/mission-control/runs/<run_id>/01-architecture.md` | Read | Context for contracts |
+| `.pi/mission-control/runs/<run_id>/02-validation.md` | Read | Criteria for contracts |
+| `.pi/mission-control/runs/<run_id>/tasks/<task_id>/contract.md` | Write | Worker input |
+| `.pi/mission-control/runs/<run_id>/tasks/<task_id>/worker-output.md` | Read | Worker output |
+| `.pi/mission-control/runs/<run_id>/tasks/<task_id>/auditor-report.md` | Read | Auditor verdict |
+| `.pi/mission-control/runs/<run_id>/short_term_memory.md` | Write | Accumulate learnings |
+
+## Anti-patterns
+- Do NOT spawn an `orchestrator` subagent — you are already the orchestrator
+- Do NOT write code yourself — delegate implementation to Worker
+- Do NOT modify run.json directly — use the tools
+- Do NOT skip the auditor — every task must be verified
+- Do NOT ask vague or performative questions — every question should reduce ambiguity or unblock progress
+- Do NOT proceed to next task while current task is in_progress
+- Do NOT merge code that hasn't passed audit
+
+## Next
+When the mission is complete, load the `mission-memory` skill and follow its
+instructions.

package/skills/mission-pm/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: mission-pm
+description: |
+  Break architecture into phases and atomic tasks, register them using
+  mission-control tools. Use after mission-tech-lead produces architecture
+  and validation. A single feature may span multiple phases.
+---
+
+# Mission PM
+
+## Overview
+You are the project manager. Break the architecture into phases and tasks.
+Each phase is a logical group of related work. A single user-facing feature
+may span multiple phases. Each task is atomic — a single worker can complete
+it in one pass.
+
+## When to Use
+- Architecture and validation contracts exist
+- You need to create the execution plan
+
+## Workflow
+1. Read `01-architecture.md` and `02-validation.md`
+2. Size work by complexity:
+   - **Simple work** (small feature, refactor, config change): 1 phase with 1-2 tasks
+   - **Medium work** (new endpoint, component): 1-2 phases with 2-4 tasks each
+   - **Complex work** (new system, major feature): 3+ phases as needed
+   Keep simple work consolidated—avoid over-fragmenting into many micro-tasks.
+3. Break work into phases:
+   - Each phase = logical group of related work (e.g. "Auth Backend", "Database Schema", "API Layer")
+   - A single user-facing feature can span multiple phases
+   - Phases can be sequential or have dependencies
+4. For each phase, break into atomic tasks:
+   - Each task = one worker can complete in one pass
+   - Each task has clear inputs and expected outputs
+   - Each task has specific validation criteria
+5. If planning ambiguity remains, ask targeted follow-up questions with `ask_user`:
+   - Always use multiple-choice options with a typed fallback
+   - Keep questions and options clean with no emojis
+   - Ask only when the answer materially changes scope, sequencing, task granularity, or priorities
+   - Prefer questions that sharpen the plan instead of expanding discussion aimlessly
+6. Register phases using the `add_phase` tool:
+   ```
+   add_phase(name: "Phase Name", file: "01-architecture.md#section")
+   ```
+   The tool auto-generates `phase_id` ("phase1", "phase2", ...) and sets status to "pending".
+7. Register tasks using the `add_task` tool:
+   ```
+   add_task(phase_id: "phase1", name: "Task Name", file: "tasks/phase1-task1/contract.md")
+   ```
+   The tool auto-generates `task_id` ("phase1-task1", "phase1-task2", ...) and sets status to "pending".
+8. Present the complete plan to the user using `ask_user`:
+   - List all phases with their tasks
+   - Show dependencies between phases
+   - Show estimated effort and complexity assessment
+   - Use multiple-choice approval options with typed fallback
+   - Keep wording clean with no emojis
+   - Request explicit approval to proceed
+9. After approval, immediately continue—do NOT stop to narrate. Load `mission-orchestrator` and proceed to execution.
+
+## Tools
+| Tool | When to call |
+|------|-------------|
+| `add_phase(name, file)` | Once per phase |
+| `add_task(phase_id, name, file)` | Once per task within a phase |
+
+## File Map
+| File | Action | Purpose |
+|------|--------|---------|
+| `.pi/mission-control/runs/<run_id>/01-architecture.md` | Read | Architecture input |
+| `.pi/mission-control/runs/<run_id>/02-validation.md` | Read | Validation input |
+| `.pi/mission-control/runs/<run_id>/run.json` | Modified | Populated via tools |
+
+## Anti-patterns
+- Do NOT start execution — that's mission-orchestrator's job
+- Do NOT create tasks that are too large — if a task needs more than one worktree session, split it
+- Do NOT fragment simple work into many phases/tasks — keep it consolidated
+- Do NOT ask planning questions unless they materially improve the plan
+- Do NOT proceed without user approval of the plan — use `ask_user` for approval
+- Do NOT stop to narrate after approval — continue automatically to execution
+
+## Next
+When the user approves the plan, load the `mission-orchestrator` skill and
+follow its instructions.

package/skills/mission-research/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: mission-research
+description: |
+  Research and interview the user to produce a detailed requirements document
+  for a new mission. Use when starting a new mission or when the user wants
+  to define what to build.
+---
+
+# Mission Research
+
+## Overview
+You are starting a new mission. Your job is to deeply understand what the user
+wants to build, research the codebase and internet, and produce a comprehensive
+requirements document.
+
+## When to Use
+- A new mission has been initialized
+- The user wants to define requirements for a new project or feature set
+
+## Workflow
+1. Load `memory/long_term.md` if it exists (past learnings from previous missions)
+2. Interview the user using `ask_user` for structured Q&A:
+   - Always ask multiple-choice questions
+   - Always provide explicit options plus a freeform typed fallback when none fit
+   - Keep questions and option labels clean and concise with no emojis
+   - Ask only questions that remove ambiguity or materially affect requirements
+   - Do not ask the user to restate information that is already clear
+   Typical topics:
+   - What do you want to build?
+   - Who is it for?
+   - What are the constraints?
+   - What's in scope / out of scope?
+   - What are the priorities?
+   Resolve ambiguity iteratively. Do not proceed until you have clear answers.
+3. Research the codebase:
+   - Understand existing file structure and conventions
+   - Identify tech stack, frameworks, patterns in use
+   - Find relevant existing code that the mission will touch
+4. Research the internet (if needed):
+   - External dependencies or libraries to use
+   - Best practices or patterns relevant to the requirements
+5. Generate `00-requirements.md` in the active run directory:
+   - Problem statement
+   - User stories / acceptance criteria
+   - Constraints and assumptions
+   - Scope boundaries (explicit in/out of scope)
+   - Dependencies and risks
+
+## File Map
+| File | Action | Purpose |
+|------|--------|---------|
+| `.pi/mission-control/memory/long_term.md` | Read | Past learnings |
+| `<repo files>` | Read | Understand codebase |
+| `.pi/mission-control/runs/<run_id>/00-requirements.md` | Write | Requirements output |
+
+## Anti-patterns
+- Do NOT start designing or planning — that's mission-tech-lead's job
+- Do NOT skip the interview — ambiguity here compounds later
+- Do NOT ask freeform-only questions when multiple-choice options can frame the decision
+- Do NOT assume — use `ask_user` to confirm everything
+- Do NOT stop to narrate after requirements are approved — immediately load `mission-tech-lead` and continue
+
+## Next
+When requirements are complete and user approves via `ask_user`, immediately
+load the `mission-tech-lead` skill and continue automatically—do not pause
+to narrate the transition.

package/skills/mission-tech-lead/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: mission-tech-lead
+description: |
+  Translate requirements into system architecture and validation contracts.
+  Use after mission-research completes and requirements are approved.
+---
+
+# Mission Tech Lead
+
+## Overview
+You are the tech lead. Take the requirements document and produce a system
+architecture and a clear definition of done.
+
+## When to Use
+- Requirements have been approved by the user
+- You need to design the system before breaking it into phases
+
+## Workflow
+1. Read `00-requirements.md`
+2. Analyze the codebase for existing patterns:
+   - File structure conventions
+   - Naming conventions
+   - Testing patterns
+   - Import/module patterns
+3. If architectural ambiguity remains after reading requirements and the codebase, ask targeted follow-up questions with `ask_user`:
+   - Always use multiple-choice options with a typed fallback
+   - Keep questions and options clean with no emojis
+   - Ask only when the answer materially changes architecture, tradeoffs, or validation
+   - Prefer questions that force a meaningful choice over vague open-ended prompts
+4. Generate `01-architecture.md`:
+   - System design overview
+   - Component/module breakdown
+   - Data flow (text-based diagrams)
+   - Technology choices and rationale
+   - File structure for new code
+   - Conventions to follow
+5. Generate `02-validation.md`:
+   - Per-phase acceptance criteria
+   - Test commands to run
+   - Lint/format rules to enforce
+   - Files that must exist or be modified
+   - Explicit "definition of done" for each area
+6. Present architecture to user using `ask_user` for approval:
+   - Use multiple-choice options
+   - Include a typed fallback for requested changes or questions
+   - Keep wording clean with no emojis
+7. After approval, immediately continue—do NOT stop to narrate. Load `mission-pm`.
+
+## File Map
+| File | Action | Purpose |
+|------|--------|---------|
+| `.pi/mission-control/runs/<run_id>/00-requirements.md` | Read | Requirements input |
+| `<repo files>` | Read | Existing patterns |
+| `.pi/mission-control/runs/<run_id>/01-architecture.md` | Write | Architecture output |
+| `.pi/mission-control/runs/<run_id>/02-validation.md` | Write | Validation output |
+
+## Anti-patterns
+- Do NOT break work into tasks — that's mission-pm's job
+- Do NOT skip validation criteria — this is the contract the auditor will check against
+- Do NOT over-architect — keep it practical and tied to requirements
+- Do NOT ask gratuitous questions — only ask when they reduce ambiguity in a meaningful way
+- Do NOT proceed without user approval — use `ask_user` for sign-off
+- Do NOT stop to narrate after approval — continue automatically to planning
+
+## Next
+When architecture and validation are complete and approved via `ask_user`,
+immediately load the `mission-pm` skill and continue automatically—do not
+pause to narrate the transition.