Plan

---
name: plan
description: PM planning workflow that gathers requirements, decomposes them into prioritized tasks, defines API contracts, and produces both a machine-readable plan and a human-readable tracker in docs/plans/
disable-model-invocation: true
---

- **Response language follows `language` setting in `.agents/oma-config.yaml` if configured.**
- Follow `.agents/skills/_shared/core/execution-policy.md` for authorization, clarification, verification, and completion. Execute required steps on the selected path in dependency order; apply documented branch and skip conditions.
- Follow `.agents/skills/_shared/core/code-intelligence.md`: discover the configured provider’s tools; use native search only for paths outside this project or ignored paths when unavailable or timed out. Do not install a provider or track a repository automatically.
- Use native file tools and `.agents/skills/_shared/runtime/memory-protocol.md` for durable coordination state; code-intelligence memory tools are not required.

---

> **Vendor note:** This workflow executes inline (no subagent spawning). All vendors use their native code analysis tools. Plan artifacts (`.agents/results/plan-{sessionId}.json` and `docs/plans/work/{NNN}-{name}.md`) are consumed by `/orchestrate` or `/work`, which handle their own vendor detection.

---

## L1 Decision Events

Emit required L1 decisions by calling `oma state emit` directly, as documented in `.agents/skills/_shared/runtime/event-spec.md`.

---

## Core Philosophy

**Plans are first-class artifacts**: structured, templated, and consumed by other workflows. They are local working artifacts (not committed to the repo; `docs/plans/` is gitignored), but they follow strict conventions so any agent can read and update them.

> `docs/plans/` does not survive a fresh clone. When a specific artifact must be durable across machines (a design doc referenced from committed documentation, a promoted API contract), commit that file deliberately with `git add -f` — tracked files are unaffected by the ignore afterwards. Committed docs must never reference a plan file that has not been promoted this way.

For Medium/Complex plans, produce two artifacts (Simple routing is defined in Step 3):

1. **Machine-readable**: `.agents/results/plan-{sessionId}.json` consumed by `/orchestrate` and `/work`.
2. **Human-readable**: `docs/plans/work/{NNN}-{name}.md` with task table, decision log, and progress notes. Lifecycle is tracked via the `Status` field in the file header (`Active` → `Completed`); no folder moves required.

### Layout

```
docs/plans/
├── designs/                       ← permanent design references (Status: Approved/Draft/Superseded)
│   └── {NNN}-{name}.md            (referenced-from-committed-docs files are force-added)
├── contracts/                     ← promoted API contracts (deliberately committed via `git add -f`)
│   └── {contract-name}.md
└── work/                          ← execution plans (Status: Active/Completed)
    ├── {NNN}-{name}.md
    └── tech-debt-tracker.md
```

- Folder = type (designs vs work). Status field = lifecycle.
- Filename always uses 3-digit zero-padded sequential prefix (`001-`, `002-`, …) per folder.
- Numbering is **per folder**. Determine the next number for the target folder only: `ls docs/plans/work/ | grep -E '^[0-9]{3}-' | tail -1` (or `docs/plans/designs/` respectively). Never combine both folders in one listing — the trailing entry would come from whichever folder lists last.
- Plan content language follows the top-of-file rule (`oma-config.yaml` `language` setting). Mixed-language guidance lives in `.agents/rules/i18n-guide.md`.

---

## Step 1: Gather Requirements

Extract requirements already present in the request and project context. Clarify only missing information that changes the plan:
- Target users
- Core features (must-have vs nice-to-have)
- Constraints (tech stack, existing codebase)
- Deployment target (web, mobile, both)

---

## Step 2: Analyze Technical Feasibility

If an existing codebase exists, use MCP code analysis tools to scan:
- Configured structure tools or scoped directory/file inspection for project structure and architecture patterns.
- Configured symbol/pattern search or native search to identify reusable code and what needs to be built.

Also search `docs/plans/work/` for related past or in-progress plans, and `docs/plans/designs/` for prior design references. Reuse patterns from similar work.

---

## Step 3: Assess Complexity

Use `.agents/skills/_shared/core/difficulty-guide.md` when scope or dependencies need decomposition. Select plan artifacts for the caller and task:

- **Simple** → for a standalone planning request, report the direct approach and matching domain skill, then end this workflow without entering `/work`. If implementation is already authorized, continue directly with that skill. If the caller requires an executable plan (e.g. `/orchestrate`), continue through Steps 4-7 and produce a minimal JSON plan; no Markdown tracker is required.
- **Medium** → produce both JSON and a lightweight markdown tracker (skip Step 4 API contracts if not cross-boundary).
- **Complex** → produce both artifacts with applicable sections; include API contracts only when a changed boundary needs one.

Report scope assessment and apply `.agents/skills/_shared/core/execution-policy.md`; reuse existing authorization.

---

## Step 4: Define API Contracts

If the plan involves cross-boundary work (frontend ↔ backend, service ↔ service):

1. Reuse the authoritative project contract when it settles the boundary. If a new or updated contract is needed, use `.agents/skills/_shared/core/api-contracts/template.md` (definition/template only — SSOT). Per endpoint:
   - Method, path, request/response schemas
   - Auth requirements, error responses
2. When creating a separate artifact, save the generated contract to `.agents/results/api-contracts/{contract-name}.md` (run artifact; gitignored). If the contract must be versioned as a durable spec, promote it to `docs/plans/contracts/{contract-name}.md` when committing the feature.
3. Reference from the markdown tracker generated in Step 6.
4. Emit and verify the required API contract decision:
   ```bash
   oma state emit "decision.made" '{"subject":"plan.api-contract","decision":"Use the approved endpoint and contract shape for this plan.","rationale":"The cross-boundary API contract has been reviewed and accepted before task decomposition."}'
   oma state verify --workflow plan --checkpoint api-contract
   ```

---

## Step 5: Decompose into Tasks

Break down the project into actionable tasks. Each task must have:
- Assigned agent (backend/frontend/mobile/db/qa/debug/architecture/refactor/tf-infra/docs — see the agent mapping in `orchestrate.md`)
- Title, acceptance criteria
- Priority tier (1 = independent, ascending; lower runs first), dependencies

**Engineering-first decomposition:** prefer tasks that address root causes over tasks that patch individual symptoms. When a deliberate workaround or hotfix is included, record the reason in the Decision Log.

---

## Step 6: Review Plan with User

Present the full plan: task list, priority tiers, dependency graph, agent assignments, completion criteria.
Apply `.agents/skills/_shared/core/execution-policy.md`: proceed when the requested work or decision is already authorized; ask only for a material missing decision or new authorization.

---

## Step 7: Save Plan Artifacts

Generate the artifacts required by Step 3.

### 7a. Machine-readable plan

Save `.agents/results/plan-{sessionId}.json` and write a memory summary via the configured memory tool.

Use `.agents/skills/oma-pm/resources/task-template.json`. For executable acceptance gates:

- Declare `acceptance_criteria` as `{id, description}` objects and `required_checks` as `{id, criteria, command, cwd}` objects. Cover every criterion with a relevant check. `command` is exact executable/argv and `cwd` is project-relative. Never insert builds unless explicitly requested.
- Preserve the canonical `dependencies` task-ID array and a self-contained `task` prompt. `retry_policy` defaults to `manual`; choose `safe` only for repeatable work without duplicate external effects.
- Optional `inputs` lists concrete project-relative source, test, configuration and dependency files/directories that completely determine the task's behavior. Omit it for whole-tree verification. Do not guess a narrow input scope to make evidence reusable.
- Keep the JSON plan fixed after dispatch starts. Record progress in the Markdown tracker and run records. Contract changes require a new run.
- Set a stable `lineage_id` for the workflow goal and reuse it across resumed sessions. `goal_id` groups alternate task IDs for the same logical work; `max_attempts` defaults to 3 including the original attempt. The runtime pins the complete plan on first dispatch. A changed contract requires a new session and lineage, not another revision in the current run. Do not create recursive plan/review tasks or new remediation plans for `WORKFLOW_EVIDENCE_FAILURE`; follow `result-contract.md` for bounded metadata repair and a partial handoff.
- Use `oma agent verify RUN_ID --required` to execute pinned checks and `oma agent resume SESSION_ID --dry-run` to inspect recovery decisions.

### 7b. Human-readable tracker (Medium/Complex only)

Generate `docs/plans/work/{NNN}-{name}.md` using this template (replace `{NNN}` with the next zero-padded 3-digit number for the `work/` folder):

```markdown
# {Plan Title}

> {One-line goal}

**Status**: Active
**Created**: {date}
**Owner**: {agent or human}

## Goal
{What this plan achieves — clear, testable outcome}

## Context
{Relevant background, related code, prior decisions}

## Constraints
{Rules, dependencies, compatibility requirements}

## Tasks

| # | Task | Agent | Priority | Status | Dependencies |
|---|------|-------|----------|--------|--------------|
| 1 | {task} | {agent} | 1 | TODO | — |
| 2 | {task} | {agent} | 1 | TODO | 1 |
| 3 | {task} | {agent} | 2 | TODO | 1, 2 |

## Done When
{Testable completion criteria}
- [ ] {criterion 1}
- [ ] {criterion 2}

## Decision Log

| Date | Decision | Rationale |
|------|----------|-----------|
| {date} | {what was decided} | {why} |

## Progress Notes
{Append-only log of progress updates}

- [{date}] Plan created
```

### Naming Convention

- Format: `{NNN}-{kebab-name}.md` (e.g., `008-add-user-authentication.md`).
- `{NNN}` is the next zero-padded 3-digit sequential number for that folder. Determine it from the existing files: `ls docs/plans/work/ | grep -E '^[0-9]{3}-' | tail -1`.
- `{kebab-name}` describes the feature; do **not** append `-design` or `-plan` (the folder already encodes type).
- Lifecycle is tracked via the `Status` header in the file, not via folder moves.

The plan is now ready for `/work` or `/orchestrate` to execute.

---

## Lifecycle Updates (during execution)

`/orchestrate` and `/work` update the markdown tracker as work progresses:

- Task status: `TODO` → `WIP` → `DONE` or `BLOCKED`
- Append timestamped entries to **Progress Notes**
- Record cross-cutting decisions in the **Decision Log**

When all "Done When" criteria are met:

1. Set the header `Status` field: `Active` → `Completed`.
2. Append a completion summary to Progress Notes with the date.
3. The file stays in `docs/plans/work/`; no move required.
4. If any tech debt was introduced, update `docs/plans/work/tech-debt-tracker.md`.

To list in-progress plans: `grep -l "^\*\*Status\*\*: Active" docs/plans/work/*.md`.

---

## Tech Debt Tracker

`docs/plans/work/tech-debt-tracker.md` tracks known debt across all plans:

```markdown
# Tech Debt Tracker

| # | Debt | Source Plan | Priority | Proposed Resolution |
|---|------|-------------|----------|---------------------|
| 1 | {description} | {plan-name} | P1 | {how to fix} |
```

- Add entries when shortcuts are taken during plan execution.
- Remove entries when debt is resolved.
- Review periodically; debt items can become plans themselves.