← Agent Project Management → Agent Platform Phase 2 · Prompt Deck

How does an agent know whether to fix, file, or build?

Success​

Right mindset, skills + tools always load at the right time, no bloat, no hallucination, minimum token cost, maximum effectiveness.

Intent​

Projects contain plans. Plans contain tasks. Each layer carries different context.

Tools + skills = capabilities. Tasks also carry a best-practice pattern (nx generator, MCP tool, or CLI) that the prompt should activate.

Three problems to solve:

1. Context budget — Monitor fill. Each project/plan/task must carry enough guidance to save useful asides (failing tests, type errors, tech debt) to memory, then /clear before the next task to keep peak performance.
2. Capability loading — Each plan should activate only the agents, skills, and MCP tools it needs. Loading everything wastes tokens and confuses routing.
3. Structured persistence — Issues and decisions go to the DB (queryable). Unstructured notes go to markdown in working memory. Both survive /clear.

This is a dedicated PRD — not an expansion of Agent Platform.

Intent Contract​

Story Contract​

Build Contract​

Job: Issue CRUD via CLI​

Job: Decision Routing​

Job: HITL Plans Dashboard​

Dogfood evidence (2026-03-10): /plans renders empty shell — 0 plans, no create action. /plans/analytics shows zero metrics. /calendar (Team Calendar) shows "No Plans Scheduled." Plans exist in DB via plan-cli.ts but the UI reads nothing. The HITL has no way to create, view, or manage plans through the web interface.

Job: Migration​

Principles​

The Job​

Why Now​

6 active issues in markdown. Volume growing. Engineering already built priority_problems + planning_issue_links but schema doesn't match commissioning workflow. The gap between what exists and what's needed is small but structural.

Design Constraints​

Decision Routing Logic​

Issue discovered
    |
    +-- Can fix in < 30 min, no new schema?
    |       YES --> FIX (log via issue-cli, engineering picks from queue)
    |
    +-- Needs new schema/API/UI?
    |       +-- <= 5 feature IDs? --> NEW PRD (create-prd skill)
    |       +-- > 5 feature IDs? --> SPLIT into multiple PRDs
    |
    +-- Existing PRD covers this?
            +-- Within frozen scope? --> ADD STORY to spec
            +-- Outside frozen scope? --> NEW PRD

Performance​

Priority Score​

PRIORITY = Pain x Demand x Edge x Trend x Conversion

Quality Targets​

• Issue creation: <30s via CLI
• Query response: <500ms
• Migration: 0 data loss (row count match)

Failure Budget​

Kill signal: If engineering still edits issues-log.md manually after Phase 2 ships, migration failed.

Platform​

Current State​

Build Ratio​

~60% composition (extend existing table + follow CLI pattern), ~40% new code (routing logic, migration).

Protocols​

Build Order​

Commissioning​

Agent-Facing Spec​

Commands:

npx tsx tools/scripts/issues/issue-cli.ts create --prd=SLUG --severity=HIGH|MEDIUM|LOW --page=ROUTE --summary="TEXT"
npx tsx tools/scripts/issues/issue-cli.ts list [--prd=SLUG] [--severity=X] [--status=open|resolved|wont-fix]
npx tsx tools/scripts/issues/issue-cli.ts resolve --id=N --evidence="TEXT"
npx tsx tools/scripts/issues/issue-cli.ts summary
npx tsx tools/scripts/issues/issue-cli.ts route --id=N
npx tsx tools/scripts/issues/issue-cli.ts migrate
npx tsx tools/scripts/issues/issue-cli.ts export

Boundaries:

• Always: Create, list, summary, export
• Ask first: Resolve (requires evidence), route (outputs recommendation, human confirms)
• Never: Delete issues, modify resolved records, change severity after resolution

Test Contract:

Players​

Demand-Side Jobs​

Job 1: Commissioner Logs Issue​

Situation: During dogfood session, commissioner finds a bug or UX issue.

Features that serve this job: #1, #2, #3

Job 2: HITL Manages Plans​

Situation: Commissioner (wik) opens /plans to see what work streams exist and create new ones.

Features that serve this job: #8, #9, #10, #11, #12, #13

Job 3: Agent Routes Work​

Situation: Agent discovers friction that could be a bug, a missing feature, or a process gap.

Features that serve this job: #5, #13

Role Definitions​

Relationship to Other PRDs​

Context​

• PRD Index — Agent Project Management → Agent Platform Phase 2
• Prompt Deck — 5-card pitch