✦
Pi team lead playbook
operations / playbooks/pi-team-lead-playbook.md
project-doc Live smoke test — 2026-04-08 project-doc Knowledge Hub session log project-doc Knowledge Hub simplification plan capture Knowledge Hub session — pi-teams prompt modes and cheap executor experiment lesson Pi-teams prompting and cheap executor lessons playbook Cheap executor decision checklist playbook Pi team lead playbook unknown Operations
Home / operations / playbooks / pi-team-lead-playbook.md

Pi team lead playbook

Properties
Type
playbook
Status
active
Curation state
canonical
Created
2026-04-08T02:30:48Z
Updated
2026-04-08T02:30:48Z
Tags
pi-teams playbook prompting knowledge-hub
ID
playbook-pi-team-lead-001
Source agents
pi
Summary
Pi team lead playbook
operations / playbooks/pi-team-lead-playbook.md

Knowledge Hub Team Lead Playbook

Use this playbook when running pi-teams on Knowledge Hub.

1. Start with the smallest meaningful slice

Prefer slices that are: - bounded to a few files - visible or contract-bearing - easy to review - unlikely to trigger broad redesign pressure

Good examples: - small route/UI contract completion - focused UI polish on an existing component - auth enforcement on a narrow set of routes

Avoid starting with: - broad refactors - vague roadmap buckets - slices that probably hide large unknowns unless you are intentionally using a frontier model

2. Audit the repo before assigning implementation

Roadmaps can lag the branch.

Before creating implementation tasks: 1. inspect current code and tests 2. confirm the slice is still genuinely open 3. note whether the gap is: - greenfield work - an integration gap - a polish/completion gap - already implemented

Minimum audit question: - "What in the current repo proves this slice is still open?"

3. Choose the lightest prompt mode likely to succeed

frontier-open

Use when: - the model is top-tier - the task needs judgment, design freedom, or ambiguity resolution - review cost from exploration is acceptable

mixed-guided

Use when: - the task crosses interfaces or teammate boundaries - you want predictable execution without over-scripting - the slice is small but contract-bearing

budget-scaffolded

Use when: - you are optimizing for cost with weaker executors - the task is repetitive or tightly bounded - review has shown guided mode is still too loose

Rule: - start as open as reality allows - tighten only when evidence says you must

4. Write outcome-first task prompts

Default prompt shape:

Objective
- what we want accomplished

Desired outcome
- what should be true when done

Why this matters
- why the slice matters / what it enables

Context to read
- code, docs, contracts

Necessary constraints
- only the constraints that matter, each with a reason

Definition of done
- how we will judge success

Do not prescribe implementation steps unless required by: - file ownership - interface contracts - required output shape - repeated failure from a weaker executor

5. Enforce file ownership clearly

For Knowledge Hub, the normal split is: - backend: server/**/*.py, server/tests/**/*.py - frontend: server/src/knowledge_hub/templates/**/*.html, server/src/knowledge_hub/static/app.css - docs/skills: .context/**/*.md, skills/**/*.md, project skill files

If a slice crosses boundaries, define the contract explicitly before parallel execution.

6. Keep constraints justified

Good constraint: - "Only modify template files, because backend ownership is separate and we want to avoid collisions."

Weak constraint: - "Implement it exactly this way" with no outcome reason

Lead standard: - if a constraint materially narrows the agent's freedom, explain why

7. Treat review as a learning loop

Review is not only for correctness. Use it to answer: - Was the prompt mode too open, too tight, or about right? - Did the task need more context, a stronger model, or a clearer boundary? - Did a cheap executor save real cost after review time is included?

Add only the smallest missing guidance. Do not jump straight to step-by-step prompts unless repeated evidence demands it.

8. Cheap-executor pattern

Recommended structure: - strong architect/planner - cheap executor on a bounded slice - strong reviewer

This works best when: - the task is visible and easy to judge - blast radius is low - fallback support exists - provider/model resolution is known-good

9. Always use explicit model IDs for experiments

When testing smaller or cheaper models, prefer fully qualified model IDs.

Example: - openai-codex/gpt-5.4-mini

Do not treat startup/provider failures as capability failures. Separate: - model quality problems - provider resolution/configuration problems

10. End every run with a short lessons note

Capture: - what worked - what failed - whether the failure was prompt, model, contract, or config related - what should change next time

Suggested location: - .context/PROMPT-POLICY-LESSONS-YYYY-MM-DD.md

Quick run sequence

  1. pick a bounded slice
  2. audit repo state
  3. choose prompt mode
  4. assign outcome-first tasks
  5. enforce file boundaries
  6. review both implementation and prompt fit
  7. record lessons
  8. update team defaults only if evidence justifies it