po-agent

PO Agent

Add an AI Product Owner to your repo in 14 lines of YAML.

Comment @po-agent fix this bug on a PR. It investigates, implements, pushes, waits for CI, handles review comments, and validates — all autonomously.

Customize everything with markdown files in .po-agent/skills/. No config schemas. No DSLs. Just markdown.

Quick Start (2 minutes)

1. Copy this workflow to your repo

# .github/workflows/po-agent.yml
name: PO Agent
on:
  issue_comment:
    types: [created]
permissions:
  contents: write
  pull-requests: write
jobs:
  agent:
    if: github.event.issue.pull_request && contains(github.event.comment.body, '@po-agent')
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4
      - uses: vyzn-tech/po-agent@v1
        with:
          anthropic_api_key: $

2. Add your API key

Go to Settings → Secrets → Actions and add ANTHROPIC_API_KEY.

3. Use it

Comment on any PR:

@po-agent fix this failing test

The agent will investigate the failure, implement a fix, push it, and wait for CI.

How It Works

You comment on a PR          The agent runs in GitHub Actions          You get a response
┌──────────────────┐         ┌──────────────────────────┐            ┌──────────────────┐
│ @po-agent fix    │────────▶│ 1. Investigate           │───────────▶│ Fixed in abc123.  │
│ this bug         │         │ 2. Implement fix         │            │ CI passed. ✅     │
│                  │         │ 3. Push + wait for CI    │            │                  │
│                  │         │ 4. Handle review comments│            │ Cost: ~$0.42     │
└──────────────────┘         └──────────────────────────┘            └──────────────────┘

The agent uses Claude Code with a battle-tested set of workflow skills. It thinks like a Product Owner first (understanding the user’s problem) and then acts like a Senior Developer (writing clean code with tests).

Customization

Everything is customized through skills — markdown files in .po-agent/skills/ in your repo.

Override a built-in skill

The agent ships with generic defaults for code quality, PR creation, etc. Override any of them:

<!-- .po-agent/skills/code-quality/SKILL.md -->
---
name: code-quality
description: Run pre-push validation. MANDATORY before every git push.
allowed-tools: Bash
---

# Code Quality

Before every push, run:

\`\`\`bash
npm run lint:fix && npm run format:write && npm run typecheck
\`\`\`

Add project-specific skills

<!-- .po-agent/skills/db-access/SKILL.md -->
---
name: db-access
description: Query the project database for investigation.
allowed-tools: Bash
---

# Database Access

Connect to the dev database:

\`\`\`bash
mysql -h $DB_HOST -u $DB_USER -p$DB_PASSWORD myapp_dev
\`\`\`

Credentials are available via environment variables (passed via `secrets` input).

Skill override priority

Source	Priority
Your `.po-agent/skills/code-quality/`	Wins (override)
Framework `skills/code-quality/`	Skipped
Your `.po-agent/skills/db-access/`	Added (extension)

Built-in Skills

Skill	Description
`/mandatory-gates`	Pre-implementation gates: investigation, confidence assessment, scope confirmation
`/bug-fix-workflow`	9-phase bug fix: investigate → implement → CI → review → verify
`/story-workflow`	9-phase feature implementation
`/code-quality`	Pre-push validation (lint, format, typecheck)
`/pr-creation`	Create PRs with proper format
`/review-handling`	Process AI and human review comments
`/merge-conflicts`	Resolve merge conflicts via rebase
`/ci-wait-resume`	Wait for CI checks inline or via auto-resume
`/budget-management`	Session cost tracking and optimization
`/playwright-verify`	Browser verification with Playwright

Auto-Resume

The agent can automatically resume when CI completes. Add the resume workflow:

# .github/workflows/po-agent-resume.yml
name: PO Agent Resume
on:
  workflow_run:
    workflows: ["CI"]    # Your CI workflow name(s)
    types: [completed]
jobs:
  resume:
    runs-on: ubuntu-latest
    steps:
      - uses: vyzn-tech/po-agent/resume@v1
        with:
          github_token: $

Additional Triggers

Slack

Deploy the Slack webhook relay and add repository_dispatch to your workflow triggers:

on:
  issue_comment:
    types: [created]
  repository_dispatch:

Pass the Slack bot token via secrets:

- uses: vyzn-tech/po-agent@v1
  with:
    anthropic_api_key: $
    secrets: |
      SLACK_BOT_TOKEN=$

Any Webhook Source

The agent accepts any repository_dispatch event. The client_payload is passed through as context. See webhooks/README.md for details.

Full Workflow Example

For all triggers (GitHub + Slack + any webhook + manual + auto-resume):

name: PO Agent
on:
  issue_comment:
    types: [created]
  repository_dispatch:
  workflow_dispatch:
    inputs:
      message: { description: 'Message', required: true }
permissions:
  contents: write
  pull-requests: write
  actions: write
concurrency:
  group: po-agent-$
  cancel-in-progress: false
jobs:
  agent:
    if: |
      github.event_name != 'issue_comment' ||
      (github.event.issue.pull_request && contains(github.event.comment.body, '@po-agent'))
    runs-on: ubuntu-latest
    timeout-minutes: 120
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: vyzn-tech/po-agent@v1
        with:
          anthropic_api_key: $
          max_budget_usd: '10.0'
          secrets: |
            SLACK_BOT_TOKEN=$
            AZURE_DEVOPS_PAT=$

Configuration Reference

Action Inputs

Input	Required	Default	Description
`anthropic_api_key`	Yes	—	Anthropic API key
`max_budget_usd`	No	`5.0`	Max spend per session
`model`	No	`claude-sonnet-4-20250514`	Claude model
`trigger_word`	No	`@po-agent`	Word that triggers the agent
`secrets`	No	—	Newline-separated `KEY=VALUE` pairs, exported as env vars
`github_token`	No	`github.token`	GitHub token for comments/reactions

Resume Action Inputs

Input	Required	Default	Description
`github_token`	No	`github.token`	GitHub token
`max_attempts`	No	`10`	Max resume attempts per PR
`required_workflows`	No	—	Comma-separated workflow names to wait for
`secrets`	No	—	Newline-separated `KEY=VALUE` pairs

Architecture

.po-agent/skills/          ← Your skills (overrides + extensions)
    code-quality/SKILL.md
    pr-creation/SKILL.md
    db-access/SKILL.md

vyzn-tech/po-agent         ← This framework
├── action.yml             ← Composite action (source detection, setup, run, respond)
├── resume/action.yml      ← Resume sub-action
├── skills/                ← Built-in default skills
├── prompts/               ← System prompt fragments
├── scripts/               ← Shell utilities (wait-for-checks, etc.)
└── webhooks/              ← Webhook relay functions

At runtime, the action:

Reads $GITHUB_EVENT_PATH to detect source and extract context
Links your .po-agent/skills/ into Claude Code’s skill discovery (your skills override framework defaults)
Composes a system prompt from prompts/core.md + source-specific fragment
Runs Claude Code with your CLAUDE.md as project context
Posts the response back to the source (GitHub PR comment, Slack message, etc.)

Comparison

Feature	GitHub Copilot	Cursor	Devin	PO Agent
Triggered from PRs	✅	❌	❌	✅
Triggered from Slack	❌	❌	❌	✅
Triggered from any webhook	❌	❌	❌	✅
Auto-resumes after CI	❌	❌	⚠️	✅
Browser verification	❌	❌	⚠️	✅ (Playwright)
Budget management	❌	❌	❌	✅
Customizable workflows	❌	Limited	❌	✅ (skills)
Open source	❌	❌	❌	✅
Runs on your own CI	❌	❌	❌	✅

Contributing

See CONTRIBUTING.md.

Skills contributions are especially welcome! If you’ve written a useful skill, please submit a PR.

License

MIT — see LICENSE.

Built by vyzn. Battle-tested on a production platform for planning sustainable buildings.

This site is open source. Improve this page.