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

package/skills/oma-pdf/config/pdf-config.yaml

@@ -0,0 +1,27 @@
+# oma-pdf configuration
+# PDF to Markdown conversion settings
+#
+# NOT the place to put your settings: `oma update` overwrites this file. Put
+# overrides under `pdf:` in .agents/oma-config.yaml, which is preserved —
+# that section wins, and this file supplies only the shipped defaults the skill
+# falls back to. Migration 022 moves anything you changed here for you.
+#
+
+format: markdown
+image_output: "off"       # "off", "embedded" (base64), "external"
+image_format: png         # "png" or "jpeg"
+use_struct_tree: false    # Use Tagged PDF structure when available
+
+# OCR settings (hybrid mode only)
+ocr:
+  enabled: false
+  languages: "en"         # Comma-separated: "ko,en", "ja,en", etc.
+  hybrid_port: 5002
+
+# Output behavior
+output:
+  # When no output directory is specified:
+  # "same_dir" = output next to the input PDF
+  # "cwd" = output in current working directory
+  default_location: same_dir
+  overwrite: false        # Prompt before overwriting existing files

package/skills/oma-pdf/resources/execution-protocol.md

@@ -0,0 +1,127 @@
+# PDF Conversion - Execution Protocol
+
+## Step 0: Validate Input
+
+1. Read the `pdf:` section of `.agents/oma-config.yaml` first; use `config/pdf-config.yaml` only for unset keys (image output, struct tree, OCR languages, hybrid port, overwrite behavior). Explicit user options override both.
+2. Confirm the PDF file path exists
+3. Check file size (`wc -c` or `ls -lh`); warn if >100MB
+4. Determine output location:
+   - If user specified output path → use it
+   - If not specified → use the same directory as the input PDF
+5. Determine output filename: `{input_name}.md` (same base name, `.md` extension)
+6. If the output file already exists and config `output.overwrite` is `false`, confirm with the user before overwriting
+
+## Step 1: Assess PDF Type
+
+Quick check to determine conversion strategy — probe only the first pages, no temp files:
+
+```bash
+# Check if PDF has text layer (vs scanned image).
+# -q is required: without it, Java INFO logs mix into stdout.
+uvx opendataloader-pdf input.pdf -f text --pages 1-3 --to-stdout -q
+```
+
+- If output contains readable text → standard mode
+- If output is empty or garbled → needs OCR (hybrid mode)
+
+## Step 2: Convert
+
+### Standard conversion
+```bash
+uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}"
+```
+
+### If Tagged PDF (structured documents, official reports)
+```bash
+uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}" --use-struct-tree
+```
+
+### If tables are missing or broken (try these BEFORE hybrid)
+
+Hybrid mode downloads a large OCR stack; the core CLI has cheaper retries:
+
+```bash
+# Borderless tables: cluster-based detection
+uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}" --table-method cluster
+
+# Complex tables (row/col spans): allow HTML tables inside Markdown
+uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}" --markdown-with-html
+```
+
+Escalate to hybrid mode only if tables are still wrong (typically scanned tables).
+
+### If the PDF is large (memory pressure or slow conversion)
+
+```bash
+# Convert each page range into a distinct directory, then concatenate the files
+uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}/p1-50" --pages "1-50"
+uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}/p51-100" --pages "51-100"
+
+# Or append each range from stdout into one combined file
+uvx opendataloader-pdf "{input_path}" --format markdown --pages "1-50" --to-stdout >> "{output_path}"
+
+# Or parallelize per-page processing (experimental)
+uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}" --threads 4
+```
+
+### Optional flags on request
+
+- `--sanitize` — mask PII (emails, phone numbers, IPs, credit cards, URLs) for AI-ready data prep
+- `--detect-strikethrough` — mark struck-through text with `~~` (experimental)
+- `--markdown-page-separator "%page-number%"` — insert page markers between pages
+- Hybrid server extras: `--enrich-formula` (LaTeX formulas), `--enrich-picture-description` (AI chart/image descriptions). Both require client-side `--hybrid-mode full`; the default `auto` mode may keep pages on the local path and skip enrichment.
+
+### If scanned/image-based PDF (requires hybrid server)
+```bash
+# Start hybrid server (if not already running).
+# The server is a console script of the [hybrid] extra — bare `uvx opendataloader-pdf-hybrid` fails (no such PyPI package).
+# First run downloads a large OCR stack (torch, easyocr, docling); warn the user before starting.
+uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid --port 5002 --force-ocr --ocr-lang "{languages}"
+
+# Convert
+uvx opendataloader-pdf --hybrid docling-fast --hybrid-mode full "{input_path}" --format markdown --output-dir "{output_dir}"
+```
+
+## Step 3: Lint & Format
+
+Run `mdformat` to normalize the converted Markdown:
+
+```bash
+uvx mdformat "{output_path}"
+```
+
+This auto-fixes:
+- Inconsistent heading style
+- Missing blank lines around blocks
+- Trailing whitespace
+- Unordered list marker normalization
+
+## Step 4: Verify
+
+1. Read the generated Markdown file
+2. Verify structure:
+   - Headings preserved (`#`, `##`, etc.)
+   - Tables rendered correctly (pipe syntax)
+   - Lists maintained (bullets, numbered)
+   - No garbled or missing sections
+3. If output directory is temporary, move the file to the target location
+4. If the user needs the content in the conversation, read and present it
+
+## Step 5: Report
+
+Tell the user:
+- Output file path
+- Page count processed — read it from the converter log line `Processing N pages`, or `pdfinfo` when available
+- Any issues encountered (missing tables, OCR quality, etc.)
+- Suggest hybrid mode if standard conversion had quality issues
+
+## Error Recovery
+
+| Error | Recovery |
+|-------|----------|
+| `uvx` not found | Ask user to install `uv`: `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| PDF password protected | Ask user for the password, then retry with `-p "{password}"` (`opendataloader-pdf --password`) |
+| Missing or broken tables | Retry with `--table-method cluster` or `--markdown-with-html` first; hybrid mode only for scanned tables |
+| Hybrid server not running | Guide user to start it, or fall back to standard mode with quality warning |
+| Out of memory on large PDF | Process each `--pages` range into a distinct output directory (or append `--to-stdout`) before concatenating; reusing one directory overwrites the same basename |
+| Network error (hybrid mode) | Check server port, retry, or fall back to standard mode |

package/skills/oma-pm/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: oma-pm
+description: Turn product requirements into scoped tasks with dependencies and
+  acceptance criteria. Use for implementation planning and prioritization.
+---
+
+# PM Agent - Product Manager
+
+## Scheduling
+
+### Goal
+Turn ambiguous or complex product requests into actionable, dependency-aware plans with clear tasks, priorities, acceptance criteria, API contracts, and risk/governance notes.
+
+### Intent signature
+- User asks for planning, requirements, specification, scope, prioritization, task breakdown, roadmap, or implementation plan.
+- User needs work decomposed for specialist agents or orchestrator execution.
+
+### When to use
+- Breaking down complex feature requests into tasks
+- Determining technical feasibility and architecture
+- Prioritizing work and planning sprints
+- Defining API contracts and data models
+
+### When NOT to use
+- Implementing actual code -> delegate to specialized agents
+- Performing code reviews -> use QA Agent
+
+### Expected inputs
+- User request, product goal, constraints, target users, and acceptance expectations
+- Existing codebase context, architecture constraints, and integration points
+- Optional standards, risk, governance, or orchestration requirements
+
+### Expected outputs
+- JSON plan and `task-board.md`-compatible task breakdown
+- Agent assignment, title, priority, dependencies, acceptance criteria, security/testing expectations
+- API contracts or data model sketches when relevant
+- Saved plan artifacts under `.agents/results/`
+
+```yaml
+outputs:
+  - name: plan
+    description: PM task breakdown JSON for orchestrator consumption
+    artifact: ".agents/results/plan-*.json"
+    required: true
+```
+
+### Dependencies
+- `resources/execution-protocol.md`, examples, task template, and ISO planning guide
+- Shared API contract references and project context-loading rules
+- Downstream specialist skills for implementation
+
+### Control-flow features
+- Branches by ambiguity, dependency structure, risk level, and whether standards/governance framing is needed
+- Produces planning artifacts rather than code
+- Optimizes for parallelizable specialist-agent execution
+
+## Structural Flow
+
+### Entry
+1. Clarify the product goal, constraints, and target deliverables.
+2. Identify technical domains and required contracts.
+3. Decide whether ISO/risk/governance framing is relevant.
+
+### Scenes
+1. **PREPARE**: Gather requirements, constraints, and context.
+2. **REASON**: Decompose work, identify dependencies, risks, and API/data contracts.
+3. **ACT**: Produce JSON plan and task-board-compatible output.
+4. **VERIFY**: Check task atomicity, acceptance criteria, security/testing coverage, and dependency shape.
+5. **FINALIZE**: Save plan artifacts and summarize execution path.
+
+### Transitions
+- If requirements are ambiguous, clarify before decomposition.
+- If tasks are tightly coupled, refine contracts or sequencing.
+- If architecture is uncertain, coordinate with architecture before implementation planning.
+- If the user needs automated execution, hand off to orchestrator after plan approval.
+
+### Failure and recovery
+- If scope is too broad, split into phases.
+- If acceptance criteria are vague, rewrite them into testable outcomes.
+- If dependencies block parallel execution, surface sequencing explicitly.
+
+### Exit
+- Success: plan is actionable, testable, prioritized, and compatible with orchestrator execution.
+- Partial success: unresolved assumptions or dependencies are explicit.
+
+## Logical Operations
+
+### Actions
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Read requirements/context | `READ` | User request and project context |
+| Select planning structure | `SELECT` | Task template and workflow needs |
+| Infer tasks and dependencies | `INFER` | Domain decomposition |
+| Validate acceptance criteria | `VALIDATE` | Checklist and task schema |
+| Write plan artifacts | `WRITE` | JSON plan and task-board markdown |
+| Notify plan summary | `NOTIFY` | Final planning report |
+
+### Tools and instruments
+- Task template, examples, ISO planning guide, shared API contracts
+- Local filesystem for result artifacts
+
+### Canonical workflow path
+```text
+1. Define API/data contracts.
+2. Decompose tasks with agent, title, priority, dependencies, and acceptance criteria.
+3. Save `.agents/results/plan-{sessionId}.json` using the injected session ID. Write the run-scoped report from the shared memory/result contract.
+```
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `MEMORY` | Requirements, assumptions, dependencies |
+| `LOCAL_FS` | `.agents/results/plan-{sessionId}.json`, injected claim path and task/run-scoped report |
+| `CODEBASE` | Optional project context and API/data model references |
+
+### Preconditions
+- Product goal and planning boundary are sufficiently clear.
+- Required implementation domains can be identified.
+
+### Effects and side effects
+- Creates plan artifacts and task boards.
+- Influences downstream agent assignments and execution order.
+- Does not directly implement code.
+
+### Guardrails
+1. For changed interfaces, reuse or define API/data contracts before dependent implementation tasks
+2. Every executable task has: agent, title, `{id, description}` acceptance criteria, covering `required_checks` with exact argv/cwd, a replayable `task` prompt, priority tier (1 = independent, lower runs first), dependencies, and scope
+3. Minimize dependencies for maximum parallel execution
+4. Security and testing are part of every task (not separate phases)
+5. Tasks should be completable by a single agent
+6. Output JSON plan + task-board.md for orchestrator compatibility
+7. When relevant, structure plans using ISO 21500 concepts, risk prioritization using ISO 31000 thinking, and responsibility/governance suggestions inspired by ISO 38500
+
+### Common Pitfalls
+- Too Granular: "Implement user auth API" is one task, not five
+- Vague Tasks: "Make it better" -> "Add loading states to all forms"
+- Tight Coupling: tasks should use public APIs, not internal state
+- Deferred Quality: testing is part of every task, not a final phase
+
+## References
+- Local code tools: `../_shared/core/code-intelligence.md` (code search/navigation)
+
+- Runtime identity and run-scoped reports: `../_shared/runtime/memory-protocol.md`, `../_shared/runtime/result-contract.md`
+- Execution steps (follow for the selected task): `resources/execution-protocol.md`
+- Plan examples: `resources/examples.md`
+- ISO planning guide: `resources/iso-planning.md`
+- Error recovery: `resources/error-playbook.md`
+- Task schema: `resources/task-template.json`
+- Ultrawork PLAN phase protocol: `resources/plan-phase-protocol.md` (used when this skill runs inside the ultrawork workflow)
+- Task board spec (orchestrator-consumed format): `../oma-orchestration/resources/memory-schema.md`
+- Human-readable tracker: when running inside the `/plan` workflow, also generate `docs/plans/work/{NNN}-{name}.md` per `.agents/workflows/plan.md`
+- API contract template (SSOT): `../_shared/core/api-contracts/template.md`; write generated contracts to `.agents/results/api-contracts/` (run artifact) or `docs/plans/contracts/` (durable spec)
+- Context loading: `../_shared/core/context-loading.md`
+- Planning depth: `../_shared/core/difficulty-guide.md` (unresolved scope or dependencies)
+- Clarification: `../_shared/core/clarification-protocol.md`
+- Context budget: `../_shared/core/context-budget.md`
+- Lessons learned: `../_shared/core/lessons-learned.md` (matching prior failure or requested retrospective)

package/skills/oma-pm/resources/error-playbook.md

@@ -0,0 +1,75 @@
+# PM Agent - Error Recovery Playbook
+
+When you encounter a failure during planning, follow these recovery steps.
+
+---
+
+## Requirements Ambiguous
+
+**Symptoms**: User request is vague ("Make me a good app", "Make it better")
+
+1. Break down what you DO understand
+2. List specific assumptions you're making
+3. Create plan based on reasonable assumptions
+4. Mark assumptions clearly: `Assumption: [description]`
+5. **NEVER do this**: Create tasks whose ambiguity is left unstated. If you cannot even state a reasonable assumption for a task, stop and ask instead of planning it (agents will lose direction)
+
+---
+
+## Existing Codebase Unknown
+
+**Symptoms**: Planning for an existing project but don't know the architecture
+
+1. Use the configured provider to inspect source structure, following `../../_shared/core/code-intelligence.md`
+2. Look for framework indicators: `package.json`, `pyproject.toml`, `pubspec.yaml`
+3. Check for existing patterns: search for `@app.get|@app.post` (FastAPI) with the configured provider or native tools
+4. If unavailable, inspect paths outside this project or ignored paths with native search; record any remaining architecture assumptions in the plan
+
+---
+
+## Task Decomposition Too Granular or Too Coarse
+
+**Self-check**:
+- Each task should take 1 agent, 10-20 turns
+- If a task needs < 5 turns: merge with a related task
+- If a task needs > 30 turns: split into sub-tasks
+- If unsure: err on the side of fewer, larger tasks
+
+---
+
+## Dependency Deadlock
+
+**Symptoms**: Task A depends on B, B depends on A (circular)
+
+1. Identify the cycle
+2. Break it by defining an API contract or shared interface first
+3. Create a tier-1 task: "Define API contracts" (no dependencies), and shift the formerly-circular tasks to tier 2+
+4. Both tasks then depend on the contract, not on each other
+
+---
+
+## Tech Stack Decision Unclear
+
+**Symptoms**: Multiple valid options, no clear winner
+
+1. Check existing codebase first; consistency wins over "better" tech
+2. If greenfield: use the project's default stack (see SKILL.md tech-stack references)
+3. Default choices: refer to each domain skill's `resources/tech-stack.md` for current versions
+   - Frontend: `oma-frontend/resources/tech-stack.md`
+   - Backend: `oma-backend/variants/{node,python,rust}/tech-stack.md`
+   - Mobile: `oma-mobile/resources/tech-stack.md`
+4. Note decision rationale in plan: `tech_decision: { choice: "X", reason: "Y" }`
+
+---
+
+## Workflow State / Quota Issues
+
+Same as the `oma-backend` playbook: see the "Rate Limit / Quota Error (LLM runtime)" and "Workflow State Unavailable" sections in `../../oma-backend/resources/error-playbook.md`.
+
+---
+
+## General Principles
+
+- **Plans are not code**: They don't need to be perfect. Agents can adjust during execution
+- **Blocked**: If no progress after 5 turns, save current state, `Status: blocked`
+- **No code writing**: PM only plans; delegate implementation to other agents