Agent Skills: MANDATORY RULES: VIOLATION IS FORBIDDEN

MANDATORY RULES: VIOLATION IS FORBIDDEN

• Response language follows language setting in .agents/oma-config.yaml if configured.
• NEVER skip steps. Execute from Step 1 in order.
• You MUST use MCP tools throughout the workflow.
  • Use code analysis tools (get_symbols_overview, find_symbol, search_for_pattern) to analyze the existing codebase.
  • Use memory tools (write/edit) to record planning results.
  • Memory path: configurable via memoryConfig.basePath (default: .serena/memories)
  • Tool names: configurable via memoryConfig.tools in .agents/mcp.json
  • Do NOT use raw file reads or grep as substitutes.

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

Use the oma_emit helper documented in .agents/skills/_shared/runtime/event-spec.md before required L1 decision checkpoints. The helper wraps oma state:emit.

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.

Two artifacts per plan:

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
└── 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.
• Determine the next number with ls docs/plans/{designs,work}/ | grep -E '^[0-9]{3}-' | tail -1.
• 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

Ask the user to describe what they want to build. Clarify:

• 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

// turbo If an existing codebase exists, use MCP code analysis tools to scan:

• get_symbols_overview for project structure and architecture patterns.
• find_symbol and search_for_pattern 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 to classify:

• Simple → no plan artifact needed; execute directly via /work.
• Medium → produce both JSON and a lightweight markdown tracker (skip Step 4 API contracts if not cross-boundary).
• Complex → produce both artifacts with all sections plus API contracts.

Report scope assessment to the user. Get confirmation before proceeding.

Step 4: Define API Contracts

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

1. Design API contracts using .agents/skills/_shared/core/api-contracts/template.md. Per endpoint:
   • Method, path, request/response schemas
   • Auth requirements, error responses
2. Save to .agents/skills/_shared/core/api-contracts/{contract-name}.md.
3. Reference from the markdown tracker generated in Step 6.
4. Emit and verify the required API contract decision:

   oma_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

// turbo Break down the project into actionable tasks. Each task must have:

• Assigned agent (frontend/backend/mobile/qa/debug)
• Title, acceptance criteria
• Priority (P0–P3), 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. You MUST get user confirmation before proceeding to Step 7.

Step 7: Save Plan Artifacts

// turbo Generate both artifacts.

7a. Machine-readable plan

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

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} | P0 | TODO | — |
| 2 | {task} | {agent} | P0 | TODO | 1 |
| 3 | {task} | {agent} | P1 | 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.