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

package/skills/oma-pm/resources/examples.md

@@ -0,0 +1,439 @@
+# PM Agent - Examples
+
+The first two plans illustrate executable acceptance contracts for a sample
+project that already has Bun test scripts. Before dispatch, replace the sample
+paths and commands with the target project's existing checks and confirm that
+they cover the stated criteria. Preserve injected session IDs and freeze the
+contract at first dispatch; these commands are not universal toolchain defaults.
+
+## Example 1: Simple TODO App
+
+**Input**: "Build a TODO app with JWT authentication"
+
+**Output**:
+```json
+{
+  "project_name": "TODO App with JWT Auth",
+  "tech_stack": {
+    "frontend": "resolve from oma-frontend/resources/tech-stack.md at planning time",
+    "backend": "resolve from oma-backend/variants/{node,python,rust}/tech-stack.md at planning time",
+    "mobile": "",
+    "database": "resolve from oma-db guidance at planning time",
+    "infrastructure": ""
+  },
+  "tasks": [
+    {
+      "id": "task-1",
+      "agent": "backend",
+      "title": "JWT authentication API",
+      "priority": 1,
+      "dependencies": [],
+      "estimated_complexity": "high",
+      "scope": [
+        "src/api/auth/",
+        "tests/api/auth.test.ts"
+      ],
+      "test_approach": "tdd",
+      "test_scope": [
+        "unit",
+        "integration"
+      ],
+      "test_approach_rationale": "Deterministic authorization rules with clear inputs and outputs.",
+      "acceptance_criteria": [
+        {
+          "id": "AC1",
+          "description": "POST /api/auth/register with email + password"
+        },
+        {
+          "id": "AC2",
+          "description": "POST /api/auth/login returns access + refresh tokens"
+        },
+        {
+          "id": "AC3",
+          "description": "Password hashed with Argon2id"
+        },
+        {
+          "id": "AC4",
+          "description": "Authentication rate limiting matches the declared project policy"
+        }
+      ],
+      "task": "Implement registration/login within src/api/auth and its tests using the agreed auth contract. Validate unauthorized access, credential storage, token handling, and the configured rate limit. Run the pinned auth check.",
+      "required_checks": [
+        {
+          "id": "check-task-1",
+          "criteria": [
+            "AC1",
+            "AC2",
+            "AC3",
+            "AC4"
+          ],
+          "command": [
+            "bun",
+            "run",
+            "test",
+            "--",
+            "tests/api/auth.test.ts"
+          ],
+          "cwd": "."
+        }
+      ],
+      "retry_policy": "manual"
+    },
+    {
+      "id": "task-2",
+      "agent": "backend",
+      "title": "TODO CRUD API",
+      "priority": 1,
+      "dependencies": [],
+      "estimated_complexity": "medium",
+      "scope": [
+        "src/api/todos/",
+        "tests/api/todos.test.ts"
+      ],
+      "acceptance_criteria": [
+        {
+          "id": "AC1",
+          "description": "CRUD endpoints for /api/todos"
+        },
+        {
+          "id": "AC2",
+          "description": "User-scoped (JWT required)"
+        },
+        {
+          "id": "AC3",
+          "description": "Pagination on list endpoint"
+        }
+      ],
+      "task": "Implement authenticated, user-scoped TODO CRUD and pagination within src/api/todos and its tests using the agreed API contract. Run the pinned todos check.",
+      "required_checks": [
+        {
+          "id": "check-task-2",
+          "criteria": [
+            "AC1",
+            "AC2",
+            "AC3"
+          ],
+          "command": [
+            "bun",
+            "run",
+            "test",
+            "--",
+            "tests/api/todos.test.ts"
+          ],
+          "cwd": "."
+        }
+      ],
+      "retry_policy": "manual"
+    },
+    {
+      "id": "task-3",
+      "agent": "frontend",
+      "title": "Login + Register UI",
+      "priority": 1,
+      "dependencies": [],
+      "estimated_complexity": "medium",
+      "scope": [
+        "src/web/auth/",
+        "tests/web/auth.test.ts"
+      ],
+      "acceptance_criteria": [
+        {
+          "id": "AC1",
+          "description": "Login and register forms with validation"
+        },
+        {
+          "id": "AC2",
+          "description": "JWT token storage"
+        },
+        {
+          "id": "AC3",
+          "description": "Redirect to /todos after login"
+        }
+      ],
+      "task": "Implement login/register forms, validated submission, session handling, and navigation within src/web/auth and its tests using the agreed auth contract. Run the pinned auth UI check.",
+      "required_checks": [
+        {
+          "id": "check-task-3",
+          "criteria": [
+            "AC1",
+            "AC2",
+            "AC3"
+          ],
+          "command": [
+            "bun",
+            "run",
+            "test",
+            "--",
+            "tests/web/auth.test.ts"
+          ],
+          "cwd": "."
+        }
+      ],
+      "retry_policy": "manual"
+    },
+    {
+      "id": "task-4",
+      "agent": "frontend",
+      "title": "TODO List UI",
+      "priority": 2,
+      "dependencies": [
+        "task-2",
+        "task-3"
+      ],
+      "estimated_complexity": "medium",
+      "scope": [
+        "src/web/todos/",
+        "tests/web/todos.test.ts"
+      ],
+      "acceptance_criteria": [
+        {
+          "id": "AC1",
+          "description": "Add, toggle, delete todos"
+        },
+        {
+          "id": "AC2",
+          "description": "Loading and empty states"
+        },
+        {
+          "id": "AC3",
+          "description": "Responsive design"
+        }
+      ],
+      "task": "Implement adding, toggling, and deleting todos plus loading/empty and responsive states within src/web/todos and its tests. Reuse task-2 and task-3 contracts. Run the pinned todos UI check.",
+      "required_checks": [
+        {
+          "id": "check-task-4",
+          "criteria": [
+            "AC1",
+            "AC2",
+            "AC3"
+          ],
+          "command": [
+            "bun",
+            "run",
+            "test",
+            "--",
+            "tests/web/todos.test.ts"
+          ],
+          "cwd": "."
+        }
+      ],
+      "retry_policy": "manual"
+    },
+    {
+      "id": "task-5",
+      "agent": "qa",
+      "title": "Security & Performance Review",
+      "priority": 3,
+      "dependencies": [
+        "task-1",
+        "task-2",
+        "task-3",
+        "task-4"
+      ],
+      "estimated_complexity": "medium",
+      "scope": [],
+      "acceptance_criteria": [
+        {
+          "id": "AC1",
+          "description": "OWASP Top 10 audit passed"
+        },
+        {
+          "id": "AC2",
+          "description": "Changed UI paths meet the declared project performance targets"
+        },
+        {
+          "id": "AC3",
+          "description": "No N+1 queries"
+        }
+      ],
+      "task": "Review the changed auth, TODO API, and UI paths against the project security/performance requirements. Run the existing test:review check and record confirmed findings separately from verification gaps. Do not claim checks that were not run.",
+      "required_checks": [
+        {
+          "id": "check-task-5",
+          "criteria": [
+            "AC1",
+            "AC2",
+            "AC3"
+          ],
+          "command": [
+            "bun",
+            "run",
+            "test:review"
+          ],
+          "cwd": "."
+        }
+      ],
+      "retry_policy": "manual"
+    }
+  ],
+  "session_id": "sample-todo-plan"
+}
+```
+
+## Example 2: Feature Addition to Existing App
+
+**Input**: "Add a comment system to the blog posts"
+
+**Output**:
+```json
+{
+  "project_name": "Blog Comments Feature",
+  "tasks": [
+    {
+      "id": "task-1",
+      "agent": "backend",
+      "title": "Comments API",
+      "priority": 1,
+      "dependencies": [],
+      "estimated_complexity": "medium",
+      "scope": [
+        "src/api/comments/",
+        "migrations/",
+        "tests/api/comments.test.ts"
+      ],
+      "acceptance_criteria": [
+        {
+          "id": "AC1",
+          "description": "POST /api/posts/{id}/comments (auth required)"
+        },
+        {
+          "id": "AC2",
+          "description": "GET /api/posts/{id}/comments (public, paginated)"
+        },
+        {
+          "id": "AC3",
+          "description": "DELETE /api/comments/{id} (owner only)"
+        },
+        {
+          "id": "AC4",
+          "description": "Nested replies (1 level deep)"
+        }
+      ],
+      "task": "Implement paginated comments, one-level replies, and authenticated creation/owner-only deletion within the comments API, migrations, and tests using the agreed API contract. Run the pinned comments API check.",
+      "required_checks": [
+        {
+          "id": "check-task-1",
+          "criteria": [
+            "AC1",
+            "AC2",
+            "AC3",
+            "AC4"
+          ],
+          "command": [
+            "bun",
+            "run",
+            "test",
+            "--",
+            "tests/api/comments.test.ts"
+          ],
+          "cwd": "."
+        }
+      ],
+      "retry_policy": "manual"
+    },
+    {
+      "id": "task-2",
+      "agent": "frontend",
+      "title": "Comment Section UI",
+      "priority": 2,
+      "dependencies": [
+        "task-1"
+      ],
+      "estimated_complexity": "medium",
+      "scope": [
+        "src/web/comments/",
+        "tests/web/comments.test.ts"
+      ],
+      "acceptance_criteria": [
+        {
+          "id": "AC1",
+          "description": "Comment list with pagination (load more)"
+        },
+        {
+          "id": "AC2",
+          "description": "Add comment form (auth required)"
+        },
+        {
+          "id": "AC3",
+          "description": "Reply to comment"
+        },
+        {
+          "id": "AC4",
+          "description": "Delete own comment"
+        },
+        {
+          "id": "AC5",
+          "description": "Real-time count update"
+        }
+      ],
+      "task": "Implement paginated comment display, authenticated creation, replies, owner deletion, and count updates within src/web/comments and its tests using the task-1 API contract. Run the pinned comments UI check.",
+      "required_checks": [
+        {
+          "id": "check-task-2",
+          "criteria": [
+            "AC1",
+            "AC2",
+            "AC3",
+            "AC4",
+            "AC5"
+          ],
+          "command": [
+            "bun",
+            "run",
+            "test",
+            "--",
+            "tests/web/comments.test.ts"
+          ],
+          "cwd": "."
+        }
+      ],
+      "retry_policy": "manual"
+    }
+  ],
+  "session_id": "sample-comments-plan"
+}
+```
+
+## Example 3: Standards-Aligned Metadata Fragment
+
+This is governance metadata to append to an existing plan, not a complete
+executable plan. Executable tasks still need the acceptance/check/replay
+contract shown above. Include controls only when the delivery context needs them.
+
+**Input**: "Plan this enterprise release with risk and governance considerations"
+
+**Output**:
+```json
+{
+  "project_name": "Enterprise Release Plan",
+  "architecture_decisions": [
+    {
+      "decision": "Use phased rollout with feature flags",
+      "rationale": "Reduces operational risk during release",
+      "alternatives_considered": ["big bang release", "tenant-by-tenant rollout"]
+    }
+  ],
+  "project_controls": {
+    "iso_21500": {
+      "scope_defined": true,
+      "stakeholders_identified": ["product", "security", "operations"],
+      "dependencies_mapped": true
+    },
+    "iso_31000": {
+      "top_risks": [
+        "migration rollback failure",
+        "auth regression on legacy users"
+      ],
+      "treatments": [
+        "pre-release restore drill",
+        "shadow auth validation"
+      ]
+    },
+    "iso_38500": {
+      "decision_owner": "engineering manager",
+      "approval_required_for": ["prod migration", "feature-flag enablement"]
+    }
+  }
+}
+```

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

@@ -0,0 +1,62 @@
+# PM Agent - Execution Protocol
+
+## Preparation
+Use the task's scope, existing project conventions, and acceptance criteria. Follow `../../_shared/core/execution-policy.md` when it has not already been supplied. Read only references needed by the selected operation; consult lessons or recovery guides for an observed issue. Expand planning depth only when the change requires it.
+
+## Step 1: Analyze Requirements
+- Parse user request into concrete requirements
+- Identify explicit and implicit features
+- List edge cases and assumptions
+- Ask clarifying questions if ambiguous
+- Inspect existing structure and relevant symbols via `../../_shared/core/code-intelligence.md`; if the configured provider is unavailable, use native search only for paths outside this project or ignored paths
+- If risk or governance matters, identify:
+  - stakeholders
+  - constraints
+  - decision owners
+  - major delivery risks
+
+## Step 2: Design Architecture
+- Select tech stack (frontend, backend, mobile, database, infra)
+- Reuse or update API contracts for changed cross-boundary work (method, path, request/response schema)
+- Design data models (tables, relationships, indexes)
+- Identify security requirements (auth, validation, encryption)
+- Plan infrastructure (hosting, caching, CDN, monitoring)
+- When relevant:
+  - map plan structure to ISO 21500-style project management concepts
+  - record top risks and treatments using ISO 31000-style thinking
+  - note governance, responsibility, and approval needs using ISO 38500-style thinking
+
+## Step 3: Decompose Tasks
+- Break into tasks completable by a single agent
+- Each task has: agent, title, description, acceptance criteria, priority, dependencies, **scope**
+- For executable acceptance gates, `acceptance_criteria` contains `{id, description}` objects; `required_checks` contains unique `{id, criteria, command, cwd}` objects. Cover every criterion with relevant exact argv and a project-relative cwd. See `task-template.json` and `../../_shared/runtime/result-contract.md`.
+- Preserve canonical `dependencies` task IDs and a self-contained `task` prompt for replay. `retry_policy` defaults to `manual`; use `safe` only when repetition cannot duplicate external effects.
+- Optional `inputs` declares a complete set of concrete source, test, configuration and dependency inputs for reusable evidence. Omit it for whole-tree verification. `scope` remains the allowed edit boundary and is not an evidence-input list.
+- `agent`: one of the orchestrator-dispatchable domains — `backend`, `frontend`, `mobile`, `db`, `qa`, `debug`, `pm`, `architecture`, `refactor`, `tf-infra`, `docs` (see the agent mapping table in `.agents/workflows/orchestrate.md`)
+- `scope`: array of directory prefixes this agent is allowed to modify (e.g., `["src/api/", "migrations/"]`). Used by `verify` to detect cross-agent boundary violations in parallel execution.
+- **Test approach (opt-in, per task)**: set `test_approach` where a test strategy matters
+  - `tdd`: deterministic, high-risk behavior (validation, authorization, state transitions, calculations, error handling). Implementation agent must record RED→GREEN evidence (see `TDD_EVIDENCE` block below).
+  - `test_after`: automated tests required, but a useful isolated RED state is impractical
+  - `not_applicable`: automated tests inappropriate — **must** fill `test_approach_rationale` and `alternative_verification` (documented manual/alternative check)
+  - Do **not** mark `tdd` for: documentation, pure styling, generated code, IaC plans, behavior-preserving refactors (refactor tasks keep their characterization-test safety net), or inherently nondeterministic integrations
+  - `test_scope`: which layers the tests cover (e.g., `["unit", "integration"]`)
+  - No `test_approach` value waives a project-defined coverage requirement. Where no target exists, plan evidence for changed behavior and justify exclusions; do not invent a universal percentage
+- Minimize dependencies for maximum parallel execution
+- Priority tiers: 1 = independent (run first), 2 = depends on tier 1, etc.
+  - The numeric tier is the **canonical** `priority` value in plan JSON (what the orchestrator fans out on).
+  - Human-readable trackers (`docs/plans/work/{NNN}-{name}.md`) use the same numeric tier in their Priority column. Do not use a separate P0/P1-style scale.
+- Complexity: Low / Medium / High / Very High
+- Save to `.agents/results/plan-{sessionId}.json` using the injected session ID; record that same ID in the plan JSON `session_id` field. Do not replace an active workflow's ID with a timestamp.
+- Keep injected task/run IDs and the claim path. Write the human-readable `result-{agentId}-{taskId}-{runId}-{sessionId}.md` under the configured memory base per `../../_shared/runtime/memory-protocol.md`. An independent manual run may create local session/task/run IDs once and reuse them throughout its artifacts.
+
+## Step 4: Validate Plan
+- Check: Can each task be done independently given its dependencies?
+- Check: Are acceptance criteria measurable and testable?
+- Check: Is `test_approach` valid where set (`tdd|test_after|not_applicable`), with rationale + alternative verification for every `not_applicable`? (`oma verify agent pm` enforces this contract)
+- Check: Is security considered from the start (not deferred)?
+- Check: Are affected API boundaries settled by an existing or updated contract before dependent frontend/mobile work?
+- Check: Are major risks, owners, and approval points explicit when needed?
+- Output task-board.md format for orchestrator compatibility
+
+## On Error
+See `resources/error-playbook.md` for recovery steps.

package/skills/oma-pm/resources/iso-planning.md

@@ -0,0 +1,110 @@
+# PM Agent - ISO 21500 / 31000 / 38500 Guide
+
+Use this file when the user wants standards-based planning, enterprise delivery structure, risk-aware prioritization, or governance-oriented recommendations.
+
+## Positioning
+
+- **ISO 21500**: project management structure and planning lens
+- **ISO 31000**: risk management lens
+- **ISO 38500**: governance, accountability, and decision-rights lens
+
+Do not turn these into ceremony for simple tasks. Use them when they improve clarity, accountability, or delivery confidence.
+
+## 1. ISO 21500 for PM Work
+
+Use ISO 21500 thinking to strengthen:
+
+- scope definition
+- stakeholder identification
+- dependency mapping
+- schedule and sequencing
+- roles and responsibilities
+- deliverable clarity
+
+Practical PM outputs:
+
+- explicit scope and exclusions
+- task decomposition with dependencies
+- owner assignment
+- milestone or phase structure
+- acceptance criteria and deliverables
+
+## 2. ISO 31000 for Risk-Aware Planning
+
+Use ISO 31000 thinking to improve:
+
+- risk identification
+- impact/likelihood discussion
+- prioritization
+- treatment / mitigation planning
+- residual risk visibility
+
+Practical PM outputs:
+
+- top risks list
+- mitigation tasks
+- contingency tasks
+- release blockers vs monitored risks
+- decision points for escalation
+
+## 3. ISO 38500 for Governance
+
+Use ISO 38500 lightly for:
+
+- decision ownership
+- approval boundaries
+- accountability
+- oversight expectations
+- alignment between business intent and technical execution
+
+Practical PM outputs:
+
+- approver or decision owner
+- who must be informed
+- what needs explicit sign-off
+- where governance review is needed
+
+## 4. When to Apply
+
+Apply these standards when:
+
+- the project is enterprise or regulated
+- many teams or stakeholders are involved
+- risk is material
+- decision rights are unclear
+- the user asks for formal planning or governance
+
+Avoid overusing them when:
+
+- the task is a small feature or bug
+- standards language would slow delivery without adding control
+
+## 5. Output Pattern
+
+When relevant, add a short section like:
+
+```md
+## Standards-Aligned Planning Notes
+
+### ISO 21500
+- Scope:
+- Stakeholders:
+- Major dependencies:
+
+### ISO 31000
+- Top risks:
+- Mitigations:
+- Residual risks:
+
+### ISO 38500
+- Decision owner:
+- Required approvals:
+- Governance checkpoints:
+```
+
+## 6. Guardrails
+
+- Keep recommendations actionable, not ceremonial
+- Do not claim formal compliance
+- Tie each standards suggestion to planning, risk reduction, or decision clarity
+- Keep technical execution delegated to specialist agents

package/skills/oma-pm/resources/plan-phase-protocol.md

@@ -0,0 +1,66 @@
+# PLAN Phase Protocol
+
+Execution guide for PLAN Phase (Steps 1-4) in ultrawork workflow. Use `.agents/workflows/ultrawork/resources/phase-gates.md` for canonical criteria and `.agents/workflows/ultrawork.md` for reviewer dispatch; this resource does not start additional reviews.
+
+---
+
+## Step 1: Create Plan
+
+### Tasks
+- Define scope, features, architecture
+- Resolve material assumptions from context; compare alternatives for unresolved decisions
+
+### Outputs
+- Task decomposition (priority tiers: 1 = independent, ascending)
+- Agent assignments
+- API contracts (if needed)
+
+---
+
+## Step 2: Plan Review (Completeness)
+
+### Review Question
+"Is anything missing?"
+
+### Checklist
+- [ ] All requirements mapped to plan
+- [ ] Dependencies specified
+- [ ] Edge cases considered
+
+---
+
+## Step 3: Review Verification (Meta Review)
+
+### Review Question
+"Was the review done properly?"
+
+### Checklist
+- [ ] The assigned fresh reviewer checks Step 2 findings against plan criteria and evidence
+- [ ] Uncovered requirements or unsupported findings are identified
+- [ ] The verdict follows the canonical PLAN_GATE and CCR dispatch contract
+
+---
+
+## Step 4: Over-Engineering Check (Simplicity)
+
+### Review Question
+"Is this over-engineered?"
+
+### Checklist
+- [ ] Asked "Is this needed for MVP?" for each component
+- [ ] Speculative features removed
+- [ ] No "might need later" code
+
+---
+
+## PLAN_GATE Checklist
+
+Final verification before completing plan:
+- [ ] Acceptance criteria have stable IDs and all are covered by relevant `required_checks` argv/cwd declarations
+- [ ] Dependencies, replay prompts and retry safety are explicit; any narrowed `inputs` set covers all behavioral dependencies
+- [ ] Material assumptions documented
+- [ ] Alternatives considered for unresolved major decisions
+- [ ] Over-engineering review completed
+- [ ] Execution policy applied; existing authorization reused
+
+**Gate failure → Return to Step 1 to revise plan**