Agent Skills: work

• 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.
• Read the oma-coordination skill BEFORE starting. Read .agents/skills/oma-coordination/SKILL.md and follow its Core Rules.
• Follow the context-loading guide. Read .agents/skills/_shared/core/context-loading.md and load only task-relevant resources.

Agent execution evidence

Follow .agents/skills/_shared/core/execution-policy.md and .agents/skills/_shared/runtime/result-contract.md. Include QA and REFINE task IDs in the plan. For each native agent, begin a run, record checks, and finalize its structured result. For CLI dispatch, pass --task-id and use the injected run identity. Complete phase logs before finalizing the QA/REFINE artifacts; code changes after verification require fresh checks.

Vendor Detection

Before starting, determine your runtime environment by following .agents/skills/_shared/core/vendor-detection.md. The detected runtime vendor and each agent's target vendor determine how agents are spawned (Step 4) and monitored (Step 5).

Step 0: Preparation (DO NOT SKIP)

1. Read .agents/skills/oma-coordination/SKILL.md and confirm Core Rules.
2. Read .agents/skills/_shared/core/context-loading.md for resource loading strategy.
3. Read .agents/skills/_shared/runtime/memory-protocol.md for memory protocol.
4. Read .agents/skills/_shared/runtime/event-spec.md for L1 event protocol.
5. Emit required L1 decisions by calling oma state emit directly, as documented in .agents/skills/_shared/runtime/event-spec.md.
6. Generate a session ID (format: YYYYMMDD-HHmmss). It keys plan-{sessionId}.json and all session-scoped memory artifacts (progress-*-{sessionId}.md, result-*-{sessionId}.md).
7. Record session start using memory write tool:
   • Create session-work.md in the memory base path
   • Include: session start time, session ID, user request summary.

Step 1: Analyze Requirements

Analyze the user's request and identify involved domains (frontend, backend, mobile, QA).

• Single domain: suggest using the specific agent directly.
• Multiple domains: proceed to Step 2.
• Use configured code-intelligence tools or native search and scoped reads to understand the existing codebase structure relevant to the request.
• Report analysis results to the user.

Step 2: Run PM Agent for Task Decomposition

Activate PM Agent to:

1. Analyze requirements.
2. Define API contracts.
3. Create a prioritized task breakdown.
4. Save plan to .agents/results/plan-{sessionId}.json.
5. Use memory write tool to record plan completion.

Step 3: Review Plan with User

Present the PM Agent's task breakdown to the user:

• Priority tiers (1, 2, 3 — lower runs first)
• Agent assignments
• Dependencies
• 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 4: Spawn Agents by Priority Tier

Spawn agents for each task by priority tier (lowest first: tier 1, then tier 2, etc.). Spawn all same-priority tasks in parallel. Assign separate workspaces to avoid file conflicts.

Per-Agent Dispatch

Resolve the target vendor for each agent from .agents/oma-config.yaml. Use native subagents only when target_vendor === current_runtime_vendor and that runtime supports the vendor's role-subagent path. Otherwise use oma agent spawn for that agent.

If Claude Code and target vendor is Claude

Use the Agent tool to spawn subagents:

• Agent(subagent_type="backend-engineer", prompt="Implement backend tasks per plan.", run_in_background=true)
• Agent(subagent_type="frontend-engineer", prompt="Implement frontend tasks per plan.", run_in_background=true)
• Multiple Agent tool calls in the same message = true parallel execution
• Agent definitions: .claude/agents/{agent}.md

If Codex CLI and target vendor is Codex

Spawn native Codex custom agents using .codex/agents/{agent}.toml when available. Native CLI executor path: codex exec "@{agent} ..." using the generated agent file. Pass each agent its task description, API contracts, and relevant context. If native dispatch is not verified in the current runtime, fall back to oma agent spawn.

If Gemini CLI and target vendor is Gemini

Use native Gemini subagents when available, otherwise fall back to oma agent spawn. Native CLI executor path: gemini -p "@{agent} ..." using .gemini/agents/{agent}.md.

If target vendor differs from current runtime, or native dispatch is unavailable

oma agent spawn backend "task description" session-id --task-id {backend_task.id} -w ./backend &
oma agent spawn frontend "task description" session-id --task-id {frontend_task.id} -w ./frontend &
wait

Step 5: Monitor Agent Progress

• Use memory read tool to poll progress-{agent}[-{sessionId}].md files
• Use configured symbol/pattern tools or native search to verify API contract alignment between agents
• Use memory edit tool to record monitoring results

Claude Code note: the Agent tool returns results synchronously (or notifies on background completion), so no file polling is needed. Check status, files changed, and issues directly in each agent's return value.

Step 6: Run QA Agent Review

After all implementation agents complete, spawn QA Agent to review all deliverables:

• Security (OWASP Top 10)
• Performance
• Accessibility (WCAG 2.2 AA)
• Code quality

Step 6.1: Measure Relevant Baseline (Conditional)

If the task needs a baseline or experiment comparison with defined metrics:

1. Load .agents/skills/_shared/conditional/quality-score.md.
2. Reuse current evidence or measure the relevant behavior with project commands. Preserve independent acceptance checks.
3. For an actual experiment, record comparable evidence in the ledger; ordinary QA does not require scoring.

Step 7: Address Issues and Iterate

If QA finds CRITICAL or HIGH issues:

Apply the shared per-task attempt and cost budget in .agents/skills/oma-orchestration/SKILL.md. Count the original attempt, each retry, and every exploration hypothesis; the workflow cycle limit never grants additional attempts.

1. Re-spawn the responsible agent with QA findings. The fix prompt MUST instruct root-cause remediation, not symptom suppression. Forbid tactical patches (try/catch swallowing, validation bypass, hardcoded values, feature flags hiding the bug, silencing the failing test) unless the agent can explicitly justify why a structural fix is out of scope for this iteration (e.g., upstream library bug, deprecated path, hotfix window). Bias toward the orthodox engineering fix even when it costs more lines or touches more files.

2. Emit and verify the remediation decision before accepting any fix/ignore choice:

   oma state emit "decision.made" '{"subject":"work.remediation-choice","decision":"Fix the responsible QA finding with root-cause remediation or explicitly defer it.","rationale":"QA identified a CRITICAL/HIGH issue requiring a recorded remediation choice."}'
   oma state verify --workflow work --checkpoint remediation-choice
   

3. If a defined comparison is active, refresh affected measurements after the fix and verify required checks. Record actual experiment decisions with evidence.

4. Before each new fix cycle, apply the loop termination check:

   Fix Loop termination conditions (OR, whichever fires first wins):

   1. Total fix cycles have reached the configured maximum (default: 5). Do not start another cycle; report the remaining CRITICAL/HIGH findings and stop.
   2. Session cost cap exceeded: if loadQuotaCap() from cli/io/session-cost.ts returns non-null, call checkCap(sessionId, cap) (no cap configured → skip this condition). If exceeded === true, print formatPromptMessage(result) to the user and stop the loop immediately. Save current results before stopping, then report early termination due to quota.

   If neither condition is met, repeat Steps 5-7.

5. If reactive recovery has failed and budget remains: choose an exploration round using exploration-loop.md; reserve all 2–3 hypothesis attempts before dispatch. If there is insufficient budget, preserve the remaining issues and report partial or failed.

   • Generate the reserved alternative approaches via Exploration Decision template
   • Re-spawn the same agent type with different hypothesis prompts, the same plan task ID, unique run IDs, and separate workspaces
   • QA checks each result against required behavior and comparable measurements
   • Best result adopted, others discarded
   • All experiments recorded in Experiment Ledger

6. Continue until all critical issues are resolved or a termination condition fires.

7. Use memory write tool to record final results.

8. If experiments were run, summarize their evidence and decisions. Record a lesson only when a reusable cause and prevention method are supported; do not edit installed skill definitions.

Step 8: Optional Doc Verify Hook

If oma-config.yaml has docs.auto_verify: true:

1. Run oma docs verify --json from the repo root.
2. Capture the JSON output.
3. If broken.length === 0: print docs verified clean (N docs) summary to stdout and continue with workflow completion.
4. If broken.length > 0: print a 1-3 line summary identifying which docs have drift, and a hint Run /oma-docs verify for the full report. Continue with workflow completion (warn-only, never block).
5. If oma-docs is not available (CLI command missing): skip silently.

This hook is opt-in; the default auto_verify: false skips this step entirely.