oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-orchestration/config/cli-config.yaml

@@ -0,0 +1,92 @@
+# Subagent vendor transport registry.
+# Select routing with model_preset/agents/default_cli in .agents/oma-config.yaml.
+# Legacy active_vendor and execution settings are not consumed by the parser.
+
+# Vendor configurations
+vendors:
+  claude:
+    command: claude
+    prompt_flag: "-p"
+    output_format_flag: "--output-format"
+    output_format: "json"
+    auto_approve_flag: "--dangerously-skip-permissions"
+    model_flag: "--model"
+    default_model: "sonnet"
+    # JSON output parsing
+    response_jq: ".result"
+    isolation_method: "flags"
+
+  # Codex runs in its workspace-write sandbox. oma also enables network and
+  # grants the project root, the OMA state home (~/.oma), and existing
+  # package-manager caches. This file is replaced by `oma update`; choose
+  # another mode durably with OMA_CODEX_SANDBOX=read-only|workspace-write|
+  # danger-full-access (danger-full-access = no sandbox, no approvals).
+  codex:
+    command: codex
+    subcommand: "exec"
+    prompt_flag: "none"
+    output_format_flag: "--json"
+    auto_approve_flag: "--sandbox workspace-write"
+    model_flag: "-m"
+    default_model: "gpt-6.1-terra"
+    response_jq: ".response"
+    isolation_method: "directory"
+
+  qwen:
+    command: qwen
+    prompt_flag: "-p"
+    output_format_flag: "--output-format"
+    output_format: "json"
+    auto_approve_flag: "--yolo"
+    model_flag: "-m"
+    default_model: "qwen3.7-plus"
+    response_jq: ".output"
+    isolation_method: "directory"
+
+  # Antigravity (agy) headless print mode: `agy -p "<prompt>"`.
+  # Models: run `agy models`. `--model` accepts ONLY those display names —
+  # a slug like `gemini-4-argon` makes agy exit with `Error: invalid --model`
+  # before running the prompt. The parenthesised tier is agy's effort dial.
+  # agy 1.0 had no --model / --add-dir / --print-timeout; oma probes
+  # `agy --help` once and drops whichever flags the installed binary lacks.
+  antigravity:
+    command: agy
+    prompt_flag: "-p"
+    auto_approve_flag: "--dangerously-skip-permissions"
+    model_flag: "--model"
+    default_model: "Gemini 4 Argon (High)"
+    isolation_method: "directory"
+
+  # Cursor Agent headless CLI: `cursor agent -p …` (--print). Prompt is positional.
+  # Models: run `cursor agent models` (legacy fallback: `cursor agent --list-models`).
+  # `auto` lets Cursor route to an available model (quota-friendly); pin to a specific
+  # id (e.g. composer-2.5, composer-2.5-fast) for reproducibility.
+  cursor:
+    command: cursor
+    prompt_flag: none
+    output_format_flag: "--output-format"
+    output_format: "json"
+    auto_approve_flag: "--yolo"
+    model_flag: "--model"
+    default_model: "auto"
+    isolation_method: "directory"
+
+  # Kiro CLI headless: `kiro-cli chat --no-interactive --trust-all-tools [--model …] "<prompt>"`.
+  # Models: AWS Bedrock IDs (e.g. anthropic.claude-sonnet-4-5-20251001-v1:0).
+  # Use "auto" to let Kiro select the model based on its own configuration.
+  kiro:
+    command: kiro-cli
+    prompt_flag: none
+    auto_approve_flag: "--trust-all-tools"
+    model_flag: "--model"
+    default_model: "auto"
+    isolation_method: "directory"
+
+  # pi headless print mode: `pi [--model …] -p "<prompt>"`.
+  # Model accepts any pi model pattern/alias, including thinking suffixes.
+  pi:
+    command: pi
+    prompt_flag: "-p"
+    model_flag: "--model"
+    default_model: "sonnet:high"
+    isolation_method: "directory"

package/skills/oma-orchestration/resources/memory-schema.md

@@ -0,0 +1,232 @@
+# MCP Memory Schema for Multi-Agent Orchestration
+
+## Overview
+
+Each subagent writes only to its own dedicated files. The orchestrator manages session-level files. This ownership model prevents write conflicts between concurrent agents.
+
+## Configuration
+
+Memory base path and tool names are configurable via `.agents/mcp.json` (not the repo-root `.mcp.json`, which is the Claude Code MCP server config):
+```json
+{
+  "memoryConfig": {
+    "basePath": ".agents/state/memories",
+    "tools": {
+      "read": "Read",
+      "write": "Write",
+      "edit": "Edit"
+    }
+  }
+}
+```
+
+Default base path: `.agents/state/memories`
+
+## File Structure
+
+```
+{memoryConfig.basePath}/
+  orchestrator-session-{sessionId}.md                 # Session metadata
+  task-board-{sessionId}.md                            # Master task list
+  progress-{agentId}-{taskId}-{runId}-{sessionId}.md   # Per-run progress log
+
+.agents/results/
+  result-{agentId}-{taskId}-{runId}-{sessionId}.md     # Per-run final report
+```
+
+> **Path rule**: Resolve coordination notes from the project-root memory base and
+> final reports from the project-root `.agents/results/`, then isolate every
+> artifact by session, task, and run. In monorepos, never choose a
+> subproject memory root. The injected claim path and agent-run receipt keep
+> their structured contract and are not replaced by this report layout.
+
+## orchestrator-session.md
+
+Created by the orchestrator at session start. Updated throughout execution.
+
+```markdown
+# Orchestrator Session
+## ID: session-{YYYYMMDD}-{HHMMSS}
+## Started: {ISO timestamp}
+## Status: running | completed | failed | aborted
+
+## Agents
+| Agent ID | CLI | PID | Status | Task |
+|----------|-----|-----|--------|------|
+| backend  | gemini | 12345 | running | task-1 |
+| frontend | gemini | 12346 | completed | task-2 |
+| mobile   | claude | 12347 | running | task-3 |
+
+## Configuration
+- MAX_PARALLEL: 3
+- MAX_RETRIES: 2
+- POLL_INTERVAL: 30s
+
+## Summary (filled on completion)
+- Total Tasks: X
+- Completed: X
+- Failed: X
+- Files Created: [list]
+- Issues: [list]
+```
+
+## task-board.md
+
+Master task list created by the orchestrator. Subagents read this to understand their assignment but never write to it.
+
+`Selected References` and `Selection Reason` are coordinator notes from PHASE
+1.5 in `SKILL.md`. They explain the task's relevant domain resources and any
+uncertainty. The launcher does not enforce these Markdown fields; supply
+references through the dispatch path's supported context mechanism. A single
+confidently matched skill is sufficient.
+
+```markdown
+# Task Board
+## Session: session-{YYYYMMDD}-{HHMMSS}
+
+### task-1
+- **Agent**: backend
+- **CLI**: gemini
+- **Title**: JWT authentication API
+- **Status**: pending | in_progress | completed | failed | blocked
+- **Priority**: 1
+- **Dependencies**: none
+- **Selected References**: oma-backend, oma-db
+- **Selection Reason**: API implementation changes the existing data-access boundary
+- **Description**: Implement user registration and login with JWT tokens
+- **Acceptance Criteria**:
+  - POST /api/auth/register with email + password
+  - POST /api/auth/login returns access + refresh tokens
+  - Password hashing with bcrypt
+  - Rate limiting on auth endpoints
+
+### task-2
+- **Agent**: frontend
+- **CLI**: gemini
+- **Title**: Login and registration UI
+- **Status**: pending
+- **Priority**: 1
+- **Dependencies**: none
+- **Selected References**: oma-frontend, oma-design
+- **Selection Reason**: Form implementation also requires the project's visual system
+- **Description**: Build login and registration forms with validation
+- **Acceptance Criteria**:
+  - Login form with email + password
+  - Registration form with validation
+  - Error handling for failed auth
+  - JWT token storage and auto-refresh
+
+### task-3
+- **Agent**: qa
+- **CLI**: gemini
+- **Title**: Security and performance review
+- **Status**: blocked
+- **Priority**: 2
+- **Dependencies**: task-1, task-2
+- **Selected References**: oma-qa
+- **Selection Reason**: Quality review matches one domain; load implementation references only when needed
+- **Description**: Review all deliverables for security and performance
+- **Acceptance Criteria**:
+  - OWASP Top 10 security check
+  - Performance benchmarks pass
+  - No critical or high severity issues
+```
+
+## progress-{agentId}-{taskId}-{runId}-{sessionId}.md
+
+Each agent creates this file at start and appends entries every 3-5 turns. Only the owning agent writes to this file.
+
+```markdown
+# Progress: backend
+## Task: task-1
+## Agent ID: backend
+## Started: {ISO timestamp}
+
+### Turn 1 - {ISO timestamp}
+- **Action**: Reading task-board.md and understanding requirements
+- **Status**: in_progress
+- **Details**: Identified 4 acceptance criteria for JWT auth API
+
+### Turn 5 - {ISO timestamp}
+- **Action**: Created user model and auth endpoints
+- **Status**: in_progress
+- **Details**: Implemented POST /api/auth/register and /api/auth/login
+- **Files**: app/models/user.py, app/api/auth.py
+
+### Turn 12 - {ISO timestamp}
+- **Action**: Added tests and rate limiting
+- **Status**: in_progress
+- **Details**: 15 test cases passing, rate limiter configured
+
+### Turn 18 - {ISO timestamp}
+- **Action**: All acceptance criteria met
+- **Status**: completed
+- **Summary**: JWT auth API fully implemented with tests
+```
+
+## result-{agentId}-{taskId}-{runId}-{sessionId}.md
+
+Each agent creates `.agents/results/result-{agentId}-{taskId}-{runId}-{sessionId}.md` upon completion (success or failure). Only the owning agent writes to this file. Preserve the injected filename and include the report path in the structured claim. Existing reports under the configured memory base, `.agents/state/memories/`, or `.serena/memories/` remain read fallback until migration; new reports always use `.agents/results/`.
+
+```markdown
+# Result: backend
+## Task: task-1
+## Status: completed
+## Turns Used: 18
+
+## Summary
+Implemented JWT authentication API with user registration, login,
+password hashing (bcrypt), and rate limiting.
+
+## Files Created/Modified
+- `app/models/user.py` (NEW) - User model with password hashing
+- `app/api/auth.py` (NEW) - Auth endpoints
+- `app/middleware/rate_limit.py` (NEW) - Rate limiting middleware
+- `tests/test_auth.py` (NEW) - 15 test cases
+- `alembic/versions/001_create_users.py` (NEW) - Migration
+
+## Acceptance Criteria
+- [x] POST /api/auth/register with email + password
+- [x] POST /api/auth/login returns access + refresh tokens
+- [x] Password hashing with bcrypt
+- [x] Rate limiting on auth endpoints
+
+## Issues Encountered
+- None
+
+## Notes
+- Access token expiry: 15 minutes
+- Refresh token expiry: 7 days
+- Rate limit: 5 requests/minute on login endpoint
+```
+
+### Failed Result Example
+
+```markdown
+# Result: backend
+## Task: task-1
+## Status: failed
+## Turns Used: 20
+
+## Summary
+Unable to complete JWT auth API. Database connection issues prevented testing.
+
+## Files Created/Modified
+- `app/models/user.py` (NEW) - User model (untested)
+- `app/api/auth.py` (NEW) - Auth endpoints (untested)
+
+## Acceptance Criteria
+- [x] POST /api/auth/register with email + password
+- [x] POST /api/auth/login returns access + refresh tokens
+- [x] Password hashing with bcrypt
+- [ ] Rate limiting on auth endpoints (NOT DONE)
+
+## Issues Encountered
+- PostgreSQL connection refused on localhost:5432
+- Could not run integration tests
+- Rate limiting implementation incomplete due to turn limit
+
+## Notes
+- Needs database running to complete testing
+- Rate limiting code is written but untested
+```

package/skills/oma-orchestration/resources/subagent-prompt-template.md

@@ -0,0 +1,30 @@
+# Subagent Prompt Template
+
+Use this template for a bounded task. CLI dispatch injects the owning skill, vendor protocol, execution policy, and result contract; do not duplicate their bodies here.
+
+```markdown
+## Assignment
+- Agent: {AGENT_ROLE}
+- Task ID: {TASK_ID}
+- Workspace: {WORKSPACE_PATH}
+- Scope: {ALLOWED_PATHS}
+
+{TASK_DESCRIPTION}
+
+## Acceptance criteria
+{ACCEPTANCE_CRITERIA}
+
+## Task references
+{RELEVANT_ARTIFACT_PATHS_AND_LOAD_CONDITIONS}
+
+## Material constraints
+{TASK_SPECIFIC_CONSTRAINTS}
+
+Use the injected run and claim identity. Preserve other agents' edits. Report necessary changes outside scope for coordination. Apply existing authorization and pause only dependent work when required information is missing.
+
+Complete the assigned criteria and relevant checks. If interrupted or unable to finish, save progress, unresolved work, and evidence in the injected result contract. Turn estimates guide checkpoints; they are not completion boundaries.
+```
+
+Use the assigned plan task ID and flat report name `result-{agentId}-{taskId}-{runId}-{sessionId}.md`. A report file supplements the structured claim; it is not proof of completion. Select tests or alternative verification for the task's risk under `_shared/core/test-approach.md`. No fixed Charter block is required.
+
+For native dispatch, provide paths to the execution policy, result contract, and owning skill if not already present. Make additional specialist skills available as routes, rather than pasting every skill into the prompt.

package/skills/oma-orchestration/scripts/parallel-run.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# parallel-run.sh - Wrapper for oma agent parallel
+# Usage: ./parallel-run.sh <tasks-file.yaml> [--vendor <vendor>]
+#        ./parallel-run.sh --inline "backend:task1" "frontend:task2" ...
+
+exec oma agent parallel "$@"

package/skills/oma-orchestration/scripts/spawn-agent.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# spawn-agent.sh - Wrapper for oma agent spawn
+# Usage: ./spawn-agent.sh <agent-id> <prompt> <session-id> [-w workspace] [--vendor vendor]
+
+exec oma agent spawn "$@"

package/skills/oma-orchestration/scripts/verify.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# verify.sh - Wrapper for oma verify
+# Usage: ./verify.sh <agent-type> [workspace-path]
+
+AGENT_TYPE="${1:-}"
+WORKSPACE="${2:-.}"
+
+case "$AGENT_TYPE" in
+  backend|frontend|mobile|qa|debug|pm) ;;
+  db|refactor|architecture|tf-infra|docs)
+    echo "SKIP: oma verify does not support agent type '$AGENT_TYPE'; continue with mechanical checks and QA cross-review."
+    exit 0
+    ;;
+  *)
+    echo "ERROR: unknown orchestrator agent type '$AGENT_TYPE'" >&2
+    exit 2
+    ;;
+esac
+
+exec oma verify agent "$AGENT_TYPE" --workspace "$WORKSPACE"

package/skills/oma-orchestration/templates/backend-task.md

@@ -0,0 +1,19 @@
+# Backend SubAgent Task
+
+You are a Backend specialist. Focus only on the task below.
+
+## Guidelines
+> Default stack assumptions. Use the owning skill and existing project conventions; these starter defaults do not authorize stack changes.
+- Use FastAPI with async/await
+- SQLAlchemy for database operations
+- Pydantic for validation
+- JWT for authentication
+- Follow REST conventions
+- Include error handling
+- Select risk-relevant tests or an explicit alternative verification
+
+## Output Requirements
+- Implement the requested functionality
+- Create/modify necessary files
+- Add appropriate tests
+- Document API endpoints if created

package/skills/oma-orchestration/templates/debug-task.md

@@ -0,0 +1,16 @@
+# Debug SubAgent Task
+
+You are a Debug specialist. Focus only on fixing the bug below.
+
+## Approach
+1. Reproduce the issue
+2. Identify root cause
+3. Implement fix
+4. Add regression test
+5. Document the fix
+
+## Output Requirements
+- Explain the root cause
+- Show before/after code
+- Include regression test
+- List related patterns to check

package/skills/oma-orchestration/templates/frontend-task.md

@@ -0,0 +1,18 @@
+# Frontend SubAgent Task
+
+You are a Frontend specialist. Focus only on the task below.
+
+## Guidelines
+> Default stack assumptions. Use the owning skill and existing project conventions; these starter defaults do not authorize stack changes.
+- React with TypeScript
+- TailwindCSS for styling
+- React Query for data fetching
+- Proper loading/error states
+- Accessible components (WCAG 2.2 AA)
+- Mobile-responsive design
+
+## Output Requirements
+- Implement the requested UI/feature
+- Create/modify necessary components
+- Add component tests if appropriate
+- Ensure responsive behavior

package/skills/oma-orchestration/templates/mobile-task.md

@@ -0,0 +1,18 @@
+# Mobile SubAgent Task
+
+You are a Mobile specialist. Focus only on the task below.
+
+## Guidelines
+> Default stack assumptions. Use the owning skill and existing project conventions; these starter defaults do not authorize stack changes.
+- Flutter with Dart
+- Clean Architecture (presentation/domain/data)
+- Riverpod for state management
+- Platform-aware UI components
+- Proper navigation handling
+- Offline-first when applicable
+
+## Output Requirements
+- Implement the requested screen/feature
+- Create/modify necessary files
+- Handle both iOS and Android
+- Test on multiple screen sizes

package/skills/oma-orchestration/templates/qa-task.md

@@ -0,0 +1,16 @@
+# QA SubAgent Task
+
+You are a QA specialist. Focus only on the review below.
+
+## Review Checklist
+- Security (OWASP Top 10)
+- Performance (bundle size, API latency)
+- Accessibility (WCAG 2.2 AA)
+- Code quality (complexity, duplication)
+- Test coverage
+
+## Output Requirements
+- List issues found with severity (CRITICAL/HIGH/MEDIUM/LOW)
+- Provide specific file:line references
+- Suggest fixes for each issue
+- Prioritize actionable feedback

package/skills/oma-orchestration/templates/tasks-example.yaml

@@ -0,0 +1,15 @@
+# Example parallel tasks file
+# Usage: ./parallel-run.sh tasks-example.yaml
+
+tasks:
+  - agent: backend
+    task: "Implement JWT authentication with register and login endpoints"
+    workspace: ./backend
+
+  - agent: frontend
+    task: "Create login and registration forms with validation"
+    workspace: ./frontend
+
+  - agent: mobile
+    task: "Build authentication screens for iOS and Android"
+    workspace: ./mobile

package/skills/oma-pdf/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: oma-pdf
+description: Extract PDF text, headings, tables, and images into Markdown using
+  opendataloader-pdf. Use for PDF parsing, not PDF layout creation.
+---
+
+# PDF Skill - PDF to Markdown Conversion
+
+## Scheduling
+
+### Goal
+Convert PDF files into structured Markdown or another requested extraction format while preserving readable document structure for LLM context, RAG, or downstream review.
+
+### Intent signature
+- User asks to convert, parse, read, extract, or transform a PDF.
+- User needs PDF text, headings, lists, tables, or images prepared for AI consumption.
+- User mentions "PDF to markdown", "parse PDF", "read this PDF", or equivalent wording.
+
+### When to use
+- Converting PDF documents to Markdown for LLM context or RAG
+- Extracting structured content such as tables, headings, lists, images, footnotes, or hyperlinks
+- Preparing PDF data for AI consumption
+- Checking whether a PDF has a text layer before choosing OCR
+
+### When NOT to use
+- Generating or creating PDFs -> use document-generation tools
+- Editing existing PDFs -> out of scope
+- Reading an already-text file -> use direct file reading
+- Processing HWP, HWPX, DOCX, XLSX, or slide decks -> use the matching document skill
+
+### Expected inputs
+- `input_path`: PDF file or folder path
+- `output_dir`: optional target directory
+- `format`: optional output format, default `markdown`
+- `ocr_languages`: optional OCR language list for scanned or image-based PDFs
+- `extraction_options`: optional flags for tagged structure, image extraction, or hybrid conversion
+
+### Expected outputs
+- Markdown, text, JSON, HTML, or combined extraction output
+- Normalized Markdown when Markdown is produced
+- A short report with output path, page count, and conversion issues
+
+### Dependencies
+- `uvx opendataloader-pdf` for standard conversion
+- `uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid` for OCR or hybrid conversion (the hybrid server is a console script of the `[hybrid]` extra, not a standalone package)
+- `uvx mdformat` for Markdown normalization
+- Local filesystem access to input and output paths
+- Optional OCR runtime via the hybrid server
+
+### Control-flow features
+- Branches on text-layer quality, tagged PDF availability, scan/OCR needs, and user-requested output format
+- Calls external CLI tools through `uvx`
+- Reads local files and writes local extraction outputs
+- Uses a hybrid server only when OCR or complex extraction needs justify it
+
+## Structural Flow
+
+### Entry
+1. Confirm that the input path exists and is a PDF file, PDF folder, or supported batch input.
+2. Check file size and warn when the input is large enough to risk slow conversion or memory pressure.
+3. Resolve `output_dir` and the expected output filename.
+
+### Scenes
+1. **PREPARE**: Validate the input path, output target, and requested extraction options.
+2. **ACQUIRE**: Assess whether the PDF has a readable text layer by extracting a text preview.
+3. **ACT**: Convert using standard mode, tagged-structure mode, or hybrid OCR mode.
+4. **VERIFY**: Run `mdformat` for Markdown output and inspect the result for readable structure.
+5. **FINALIZE**: Report output path, page count, format, and any extraction quality issues.
+
+### Transitions
+- If the preview text is readable, use standard conversion.
+- If the PDF is tagged and standard output is garbled, retry with `--use-struct-tree`.
+- If tables are missing or broken, retry with `--table-method cluster` or `--markdown-with-html` before escalating to hybrid mode.
+- If the PDF is scanned or image-based, start or reuse the hybrid OCR server and convert with hybrid mode.
+- If conversion fails because the PDF is encrypted, stop and ask for the password or an unlocked copy.
+- If conversion hits memory or size limits, process smaller page ranges into distinct output directories (or append `--to-stdout`) so repeated runs do not overwrite the same basename.
+
+### Failure and recovery
+| Failure | Recovery |
+|---------|----------|
+| `uvx` unavailable | Ask user to install `uv` before conversion |
+| `opendataloader-pdf-hybrid` not found | Invoke via `uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid`; the bare package name does not exist on PyPI |
+| Password-protected PDF | Ask for password or unlocked PDF |
+| Garbled output | Retry with tagged structure or hybrid mode |
+| Missing tables | Retry with `--table-method cluster` or `--markdown-with-html` first; hybrid mode for scanned tables |
+| OCR language mismatch | Retry with explicit OCR languages, for example `ko,en` |
+| Large file or memory pressure | Split into page ranges using distinct output directories or `--to-stdout`; never reuse one output directory for the same basename |
+
+### Exit
+- Success: output file exists, Markdown is formatted when applicable, and extracted structure is readable.
+- Partial success: output exists but quality issues are reported explicitly.
+- Failure: no reliable output is produced and the blocking cause is reported.
+
+## Logical Operations
+
+### Actions
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Validate path and options | `VALIDATE` | Input preflight in execution protocol |
+| Probe text layer | `READ` | Text preview extraction |
+| Choose conversion strategy | `SELECT` | Standard, tagged, or hybrid mode decision |
+| Run converter | `CALL_TOOL` | `uvx opendataloader-pdf` |
+| Start OCR server | `CALL_TOOL` | `uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid` |
+| Write output artifact | `WRITE` | Markdown, text, JSON, or HTML output |
+| Normalize Markdown | `CALL_TOOL` | `uvx mdformat` |
+| Inspect extraction quality | `VALIDATE` | Structure/readability verification |
+| Report result | `NOTIFY` | Final user-facing summary |
+
+### Tools and instruments
+- `opendataloader-pdf`: primary PDF extraction CLI
+- `opendataloader-pdf-hybrid`: hybrid OCR and complex extraction path
+- `mdformat`: Markdown normalization
+- Filesystem commands such as `file`, `wc`, or `pdfinfo` may be used for preflight when available
+
+### Canonical command path
+```bash
+uvx opendataloader-pdf "{input_path}" -f text --pages 1-3 --to-stdout -q   # text-layer probe (no temp files)
+uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}"
+uvx mdformat "{output_path}"
+```
+
+For scanned/image-based PDFs, start OCR first and then convert through hybrid mode:
+```bash
+uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid --port 5002 --force-ocr --ocr-lang "{languages}"
+uvx opendataloader-pdf --hybrid docling-fast --hybrid-mode full "{input_path}" --format markdown --output-dir "{output_dir}"
+```
+
+On-request flags — `--sanitize` (PII masking), `--pages` (range extraction), `--threads` (parallel pages), `--detect-strikethrough`, hybrid `--enrich-formula` / `--enrich-picture-description` — are detailed in `resources/execution-protocol.md`. The two enrichment flags require client-side `--hybrid-mode full`.
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `LOCAL_FS` | Input PDFs and generated output files |
+| `PROCESS` | `uvx` subprocesses and optional hybrid server |
+| `MEMORY` | Extracted previews and validation notes |
+| `OTHER` | OCR model/runtime behavior inside hybrid mode |
+
+### Preconditions
+- The input PDF path exists and is readable.
+- The output location is writable or can be created.
+- Required CLIs are available through `uvx`.
+- OCR is only attempted when hybrid mode is available or can be started.
+- Defaults come from the `pdf:` section of `.agents/oma-config.yaml`, falling back to `config/pdf-config.yaml` for unset keys; explicit user options override both, and `output.overwrite: false` requires confirmation before replacing an existing output file.
+
+### Effects and side effects
+- Creates or overwrites extraction output depending on configuration and user intent.
+- May start a local hybrid OCR server on the configured port.
+- May consume significant CPU, memory, or time for large or scanned PDFs.
+- Does not intentionally modify the source PDF.
+
+### Guardrails
+1. Do not invent missing content when extraction is incomplete.
+2. Always report garbled text, missing tables, OCR uncertainty, or partial extraction.
+3. Prefer standard conversion first when the text layer is readable.
+4. Use OCR only when the PDF is scanned, image-based, or standard extraction quality is insufficient.
+5. Keep detailed command sequences in `resources/execution-protocol.md` rather than duplicating every variant here.
+
+## References
+- Execution protocol: `resources/execution-protocol.md`
+- Configuration: read the `pdf:` section of `.agents/oma-config.yaml` first, then fall back to `config/pdf-config.yaml` for any key it does not set. User overrides belong in `.agents/oma-config.yaml`, since `oma update` overwrites the skill config.
+- Context loading: `../_shared/core/context-loading.md`
+- Quality principles: `../_shared/core/quality-principles.md`