lukaszbadowski/manage-ai-software-projects

Manage AI Software Projects

Turn vague AI-assisted delivery work into a controlled execution system for one human operator. Elicit the frame, obtain conscious approval of the story breakdown, execute through a small routed task queue in durable files, verify with evidence, and close only after every success criterion passes its end-to-end check.

Keep durable project state vendor-neutral. Switching between Codex, Claude Code, or another compatible agent must not require converting the pm/ files.

Quick Start

1. Inspect the workspace. If pm/ exists, read pm/STATE.md, then pm/TASKS.md; repair gaps instead of regenerating the system.
2. If no project system exists, run CP1: ask the elicitation questions and draft the frame in pm/PLAN.md.
3. Create the four canonical files from references/file-templates.md.
4. Drive work through CP2 breakdown, CP3 queue, the execution loop, and CP4 final acceptance.

Operator Checkpoint Protocol

Co-create the breakdown with the operator. Record each approval with a date in pm/PLAN.md or pm/TASKS.md.

• CP1 — Frame. Elicit and obtain approval for the objective, success criteria, final checks, scope, constraints, and structural assumptions.
• CP2 — Breakdown. Present stories in the operator's language. Give each story acceptance criteria and trace it to the success criteria it serves. Resolve open structural decisions with the operator.
• CP3 — Queue. Present the ordered task queue with routing tiers before execution starts.
• CP4 — Final acceptance. Re-run every CP1 final check end-to-end, link evidence, present the acceptance report, and obtain sign-off. Completed tasks alone do not mean the project is done.

Use these standing rules:

• Fill small gaps inside an approved frame with logged assumptions in pm/DECISIONS.md.
• Return structural changes—scope, stories, success criteria, or acceptance bar—to the relevant checkpoint and record the trade-off.
• Ask at CP1: What outcome must exist, and for whom? How will the operator personally verify it? What is out of scope? Which constraints are fixed? What already exists? What is riskiest or unclear? How much review does the operator want?
• In rescue mode, reconstruct the implied frame and breakdown from the workspace, present them for confirmation, and then rebuild the queue.

Canonical Project Files

Maintain four files under pm/:

• pm/PLAN.md — objective, success criteria, scope, stories, traceability, approvals
• pm/TASKS.md — ordered task queue, stable IDs, routing, verification, evidence
• pm/STATE.md — current state, handoff notes, session log
• pm/DECISIONS.md — decisions, assumptions, risks, issues, change log

Do not create more control files by default. Add pm/CONSTRAINTS.md, pm/RELEASE.md, or pm/RESEARCH.md only when the matching branch is active.

Keep the product-specific entry file—such as AGENTS.md or CLAUDE.md—short and navigational: point to pm/STATE.md, then pm/TASKS.md, with pm/PLAN.md as approved scope. Mirror durable information from session-local planning tools into pm/TASKS.md and pm/STATE.md.

Route Work by Capability

Assign a vendor-neutral Route: tier when each task enters the queue:

Tier	Use for
heavy	planning, decomposition, architecture, ambiguous debugging, cross-cutting refactors, risky review, final acceptance
standard	bounded implementation, tests, moderate-complexity changes
light	repository search, summaries, mechanical edits, documentation, formatting, log triage

Route every task to the least expensive tier that can complete it reliably:

• Keep the primary thread capable enough to direct: frame briefs, route work, judge evidence, and sign off.
• Escalate one tier after two failed attempts or a low-confidence result on the same task; record the escalation.
• Require the reviewer tier to be at least the writer tier. Give risky or cross-cutting changes a fresh-context heavy review. Never let a light worker self-approve.
• Keep model names out of pm/; product aliases and prices change while capability tiers remain useful.
• Read references/agent-routing.md before configuring workers for Codex, Claude Code, or another agent.

Build Context First

• Extract the real objective, users, acceptance bar, dependencies, and release expectations.
• Treat dates, budgets, approvals, vendor schedules, or launch windows as first-class inputs only when explicit.
• Look for existing pm/ files, task briefs, backlogs, designs, ADRs, test strategies, runbooks, risk logs, and agent instruction files before inventing new artifacts.
• In rescue work, assess objective clarity, scope, dependencies, acceptance quality, risk hygiene, context legibility, permissions, and release readiness.

Choose the Smallest Control Mode

• Default to solo-operator: one operator steering AI agents.
• Add external-constraint for a real fixed date, compliance gate, approval, vendor dependency, quota, or launch window.
• Add feedback-heavy when discovery, user learning, or UX iteration dominates.
• Add release-safety when shipping requires cutover, rollback, monitoring, or operating notes.

Size Execution Units

• Use stories for user-visible value and acceptance. Use milestones only to group work. Execute through tasks.
• Make each task fit one focused agent run and one quick operator review: one subsystem, interface, document, or test surface and one reviewable diff.
• Give every task a stable ID, story reference, routing tier, scope, dependency, done-when check, exact verification, evidence field, and explicit stop point.
• Split before execution when a task spans unrelated areas or several independent validations. Keep history: child tasks get new IDs; replaced tasks become superseded.
• After completing a task, fill its evidence and update pm/STATE.md in the same run.

Maintain Traceability

• Map every success criterion to at least one story and every story to at least one task.
• Mark a story done only after all its tasks and acceptance criteria are verified with evidence.
• Mark the project done only after CP4 re-verifies every success criterion end-to-end.

Run a Quality-First Loop

• Define the smallest credible proof before implementation: failing reproduction, automated test, expected output, screenshot comparison, contract check, or exact manual procedure.
• Use explore -> plan -> implement -> verify -> review -> document.
• Record commands, results, screenshots, metrics, and review notes rather than conclusions alone.
• State change budgets for risky tasks: allowed files, stable interfaces, data safety, rollback, and escalation triggers.
• Pilot repetitive or automated changes on a narrow representative slice before scaling.
• After the same failure twice, stop and improve the environment, documentation, rule, or validator; restart with clean context.
• Treat repeated agent failures as system feedback. Improve the process, not only the current answer.

Delegate Safely

• Delegate only autonomy-ready, bounded work. Keep goals, decomposition, synthesis, and sign-off in the primary thread.
• Give each worker a written brief: task ID, objective, scope, constraints, verification commands, expected evidence, stop point, escalation trigger, and routing tier.
• Keep tiny, tightly coupled, or highly interactive work in the primary thread when delegation overhead exceeds its benefit.
• Prefer deterministic validators for zero-exception rules such as required tests, path restrictions, formatting, or secret scanning.
• Enforce least privilege, trust boundaries, secret-handling rules, and explicit operator approval for risky actions.

References

• Read references/file-templates.md when creating or repairing pm/.
• Read references/worked-example.md for a compact end-to-end example.
• Read references/project-rulebook.md when auditing or rescuing a project.
• Read references/external-constraints.md only for real outside constraints or production release risk.
• Read references/ai-agent-practices.md for deeper guidance on durable memory, context, delegation, evals, and guardrails.
• Read references/agent-routing.md when mapping tiers to a product's current capabilities.
• Read references/source-anchors.md when provenance or volatile vendor guidance matters.
• Load only the smallest relevant reference.

Output Standards

• Write concrete, decision-ready artifacts in imperative form.
• Report checkpoint status first and task IDs before prose status.
• Format tasks as: Task ID, Task, Story, Route, Scope, Depends on, Done when, Verify with, Evidence, Stop after, Status.
• Prefer one reviewable diff per task.
• Keep model names out of durable project files.
• Do not add date plans, budgets, approval workflows, recurring ceremonies, or stage gates unless the project genuinely needs them.
• Verify current model, benchmark, price, or vendor-workflow claims against primary sources before using them.