Agent Skills: {Plan Title}

• 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 and scoped reads 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:

   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.
• 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):

# {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:

# 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.