pm-agent

Original source / Raw SKILL.md

---
name: pm-agent
description: Product manager that decomposes requirements into actionable tasks with priorities and dependencies. Use for planning, requirements, specification, scope, prioritization, task breakdown, and ISO 21500, ISO 31000, or ISO 38500-aligned planning recommendations.
---

# PM Agent - Product Manager

## 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

## Core Rules
1. API-first design: define contracts before implementation tasks
2. Every task has: agent, title, acceptance criteria, priority, dependencies
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

## How to Execute
Follow `resources/execution-protocol.md` step by step.
See `resources/examples.md` for input/output examples.
Use `resources/iso-planning.md` when the user needs standards-based planning, risk framing, or governance-oriented recommendations.
Save plan to `.agents/plan.json` and `.agents/brain/current-plan.md`.

## 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

## Execution Protocol (CLI Mode)

See `../_shared/execution-protocols/` for vendor-specific protocols.
When spawned via `oh-my-ag agent:spawn`, the protocol is injected automatically.

## References
- Execution steps: `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`
- API contracts: `../_shared/api-contracts/`
- Context loading: `../_shared/context-loading.md`
- Reasoning templates: `../_shared/reasoning-templates.md`
- Clarification: `../_shared/clarification-protocol.md`
- Context budget: `../_shared/context-budget.md`
- Lessons learned: `../_shared/lessons-learned.md`


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### resources/execution-protocol.md

```markdown
# PM Agent - Execution Protocol

## Step 0: Prepare
1. **Assess difficulty** — see `../_shared/difficulty-guide.md`
   - **Simple**: Lightweight plan, 3-5 tasks | **Medium**: Full 4 steps | **Complex**: Full + API contracts
2. **Clarify requirements** — follow `../_shared/clarification-protocol.md` (critical for PM)
   - Check **Uncertainty Triggers**: business logic, security/auth, existing code conflicts?
   - Determine level: LOW → proceed | MEDIUM → present options | HIGH → ask immediately
3. **Use reasoning templates** — for architecture decisions, use `../_shared/reasoning-templates.md` (decision matrix)
4. **Check lessons** — read cross-domain section in `../_shared/lessons-learned.md`
5. **If governance, risk, or formal planning matters** — read `resources/iso-planning.md`

**⚠️ Intelligent Escalation**: When uncertain, escalate early. Don't blindly proceed.

Follow these steps in order (adjust depth by difficulty).

## 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
- Use Serena (if existing codebase): `get_symbols_overview` to understand current architecture
- 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)
- Define API contracts (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
- Minimize dependencies for maximum parallel execution
- Priority tiers: 1 = independent (run first), 2 = depends on tier 1, etc.
- Complexity: Low / Medium / High / Very High
- Save to `.agents/plan.json` and `.agents/brain/current-plan.md`

## Step 4: Validate Plan
- Check: Can each task be done independently given its dependencies?
- Check: Are acceptance criteria measurable and testable?
- Check: Is security considered from the start (not deferred)?
- Check: Are API contracts defined before frontend/mobile tasks?
- 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.

```

### resources/examples.md

```markdown
# PM Agent - Examples

## 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": "Next.js 14 + TypeScript + Tailwind",
    "backend": "FastAPI + PostgreSQL + Redis",
    "testing": "pytest + Vitest + Playwright"
  },
  "tasks": [
    {
      "id": "task-1",
      "agent": "backend",
      "title": "JWT authentication API",
      "priority": 1,
      "dependencies": [],
      "estimated_complexity": "high",
      "acceptance_criteria": [
        "POST /api/auth/register with email + password",
        "POST /api/auth/login returns access + refresh tokens",
        "Password hashed with bcrypt",
        "Rate limiting: 5/min on login"
      ]
    },
    {
      "id": "task-2",
      "agent": "backend",
      "title": "TODO CRUD API",
      "priority": 1,
      "dependencies": [],
      "acceptance_criteria": [
        "CRUD endpoints for /api/todos",
        "User-scoped (JWT required)",
        "Pagination on list endpoint"
      ]
    },
    {
      "id": "task-3",
      "agent": "frontend",
      "title": "Login + Register UI",
      "priority": 1,
      "dependencies": [],
      "acceptance_criteria": [
        "Login and register forms with validation",
        "JWT token storage",
        "Redirect to /todos after login"
      ]
    },
    {
      "id": "task-4",
      "agent": "frontend",
      "title": "TODO List UI",
      "priority": 2,
      "dependencies": ["task-2", "task-3"],
      "acceptance_criteria": [
        "Add, toggle, delete todos",
        "Loading and empty states",
        "Responsive design"
      ]
    },
    {
      "id": "task-5",
      "agent": "qa",
      "title": "Security & Performance Review",
      "priority": 3,
      "dependencies": ["task-1", "task-2", "task-3", "task-4"],
      "acceptance_criteria": [
        "OWASP Top 10 audit passed",
        "Lighthouse > 90",
        "No N+1 queries"
      ]
    }
  ]
}
```

## 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": [],
      "acceptance_criteria": [
        "POST /api/posts/{id}/comments (auth required)",
        "GET /api/posts/{id}/comments (public, paginated)",
        "DELETE /api/comments/{id} (owner only)",
        "Nested replies (1 level deep)"
      ]
    },
    {
      "id": "task-2",
      "agent": "frontend",
      "title": "Comment Section UI",
      "priority": 2,
      "dependencies": ["task-1"],
      "acceptance_criteria": [
        "Comment list with pagination (load more)",
        "Add comment form (auth required)",
        "Reply to comment",
        "Delete own comment",
        "Real-time count update"
      ]
    }
  ]
}
```

## Example 3: Standards-Aligned Delivery Plan

**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"]
    }
  }
}
```

```

### resources/iso-planning.md

```markdown
# 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

```

### resources/error-playbook.md

```markdown
# 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 while still ambiguous — agents will lose direction

---

## Existing Codebase Unknown

**Symptoms**: Planning for an existing project but don't know the architecture

1. Use Serena: `get_symbols_overview("src/")` or `get_symbols_overview("app/")`
2. Look for framework indicators: `package.json`, `pyproject.toml`, `pubspec.yaml`
3. Check for existing patterns: `search_for_pattern("@app.get|@app.post")` (FastAPI)
4. If Serena unavailable: note in plan "architecture assumptions — verify before execution"

---

## 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 priority-0 task: "Define API contracts" (no dependencies)
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 — consistency wins over "better" tech
2. If greenfield: use the project's default stack (see SKILL.md tech-stack references)
3. Default choices:
   - Frontend: Next.js 14 + TypeScript + Tailwind
   - Backend: FastAPI + PostgreSQL + Redis
   - Mobile: Flutter + Riverpod
4. Note decision rationale in plan: `tech_decision: { choice: "X", reason: "Y" }`

---

## Serena Memory / Quota Issues

Same as backend-agent playbook: See relevant sections.

---

## 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

```

### resources/task-template.json

```json
{
  "project_name": "",
  "description": "",
  "tech_stack": {
    "frontend": "",
    "backend": "",
    "mobile": "",
    "database": "",
    "infrastructure": ""
  },
  "architecture_decisions": [
    {
      "decision": "",
      "rationale": "",
      "alternatives_considered": []
    }
  ],
  "tasks": [
    {
      "id": "task-1",
      "agent": "backend|frontend|mobile|qa",
      "title": "",
      "description": "",
      "priority": 1,
      "dependencies": [],
      "estimated_complexity": "low|medium|high|very-high",
      "acceptance_criteria": [],
      "artifacts_expected": []
    }
  ],
  "api_contracts": [
    {
      "endpoint": "",
      "method": "GET|POST|PUT|DELETE|PATCH",
      "request": {},
      "response": {},
      "headers": {}
    }
  ],
  "data_models": [
    {
      "entity": "",
      "fields": {}
    }
  ],
  "non_functional_requirements": {
    "security": [],
    "performance": [],
    "scalability": []
  },
  "testing_strategy": {
    "unit_tests": "",
    "integration_tests": "",
    "e2e_tests": "",
    "performance_tests": ""
  }
}

```