Cpo Ai Skill

Command Parsing

/cpo-go <name> <description...>
        │       │
        │       └── Everything after the name = product description
        └── First word after /cpo-go = project name (lowercase, no spaces)

On Command Detection

When /cpo-go is invoked:

1. Parse project name and description
2. Create project directory: ./{project-name}/
3. Initialize Git and GitHub repository
4. Initialize master-project.json with parsed name
5. Skip to streamlined discovery (fewer questions since context is provided)
6. Begin Phase 1 with the description as the product idea

See: references/phase-details.md for complete workflow steps.

Core Philosophy

"From Vision to Production with Systematic Excellence"

The CPO AI acts as a virtual Chief Product Officer, combining:

• Product Strategy: Qualifying ideas, defining scope, identifying MVP
• Market Research: Analyzing competitors, design patterns, and best practices
• Technical Architecture: Expert tech stack and deployment recommendations
• World-Class Design: Production-grade UI avoiding generic AI aesthetics
• Project Management: Sequential execution with quality gates
• Quality Assurance: Testing each stage before progression
• Documentation: Creating user guides and deployment docs

Workflow Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                         CPO AI SKILL WORKFLOW                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  PHASE 1: DISCOVERY          PHASE 2: PLANNING         PHASE 3: EXECUTION   │
│  ┌──────────────────┐       ┌──────────────────┐       ┌──────────────────┐ │
│  │ Receive Idea     │──────►│ Strategic Plan   │──────►│ Stage-by-Stage   │ │
│  │ Ask Questions    │       │ Epics & Stages   │       │ Implementation   │ │
│  │ Define Scope     │       │ Story Breakdown  │       │ Test & Commit    │ │
│  │ Identify MVP     │       │ Master Project   │       │ Iterate Until    │ │
│  └──────────────────┘       └──────────────────┘       │ Complete         │ │
│                                                        └──────────────────┘ │
│                                                                 │            │
│  PHASE 4: VALIDATION        PHASE 5: DELIVERY                   │            │
│  ┌──────────────────┐       ┌──────────────────┐                │            │
│  │ Full Project     │◄──────│ User Guide       │◄───────────────┘            │
│  │ Testing          │       │ Documentation    │                             │
│  │ Fix Any Issues   │       │ Final Commit     │                             │
│  │ Quality Gate     │──────►│ Push & Go Live   │                             │
│  └──────────────────┘       └──────────────────┘                             │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Specialized Subagents

The CPO AI orchestrates six specialized subagents for best-in-class results:

See: subagents/ directory for detailed agent definitions.

Atomic Tools vs Outcomes

Agent-Native Design Principle

This skill follows the Agent-native principle: "Tools should be atomic primitives. Features are outcomes achieved by an agent operating in a loop."

Atomic Tools Used

The CPO AI skill uses these atomic primitives:

• Read/Write/Edit - File system operations
• Glob/Grep - Code search and discovery
• Bash - Execute commands (git, npm, test runners)
• TaskCreate/TaskUpdate/TaskList - Progress tracking
• TeamCreate/SendMessage - Swarm coordination for parallel work
• mcpmemory***** - Research caching and pattern learning

Key insight: The skill does NOT implement custom workflow tools like analyze_and_plan_product() or implement_stage(). Instead, it uses atomic tools in a loop.

Outcomes Achieved via Prompts

The five phases (Discovery, Planning, Implementation, Validation, Delivery) are outcomes, not hardcoded workflows. The agent achieves these outcomes by:

1. Discovery - The agent uses Read to check for existing state, asks questions via natural language prompts, and uses Write to create definition documents
2. Planning - The agent invokes specialized subagents (also prompt-based), synthesizes their outputs, and writes master-project.json
3. Implementation - The agent delegates to autonomous-dev skill (prompt-based), monitors progress via TaskList, and tests via fulltest-skill (prompt-based)
4. Validation - The agent runs test commands via Bash, analyzes results, and fixes issues iteratively
5. Delivery - The agent generates docs via prompts, commits via Bash, and invokes deployment agent (prompt-based)

How to Modify Behavior via Prompts

Want to change discovery questions?

Edit the prompt in references/phase-details.md lines 24-83. The questions are part of the agent's instructions, not hardcoded logic.

Want different epic patterns?

Modify the prompts that guide epic decomposition (Phase 2), or save new patterns to Memory MCP via mcp__memory__create_entities with type epic-pattern:{type}.

Want to customize stage implementation?

The implementation strategy is controlled by prompts in:

• The subagent definitions in subagents/ directory
• The autonomous-dev skill invocation parameters
• Environment variables and project-specific prompts

Want different testing strategies?

Modify the fulltest-skill invocation parameters or create project-specific test prompts in .claude.md.

Want custom swarm behavior?

Edit the TeammateTool message templates (lines 285-360) to change how the leader coordinates with workers. The swarm behavior emerges from these prompt-based messages, not from hardcoded orchestration.

Contrast: Workflow-Shaped Anti-Pattern

What this skill does NOT do:

// Anti-pattern: Hardcoded workflow
function cpo_workflow(productIdea) {
  const questions = askDiscoveryQuestions(); // Hardcoded Q&A
  const plan = generatePlan(questions); // Hardcoded planning
  for (const stage of plan.stages) {
    implementStage(stage); // Hardcoded implementation
    runTests(stage); // Hardcoded testing
  }
  deploy(); // Hardcoded deployment
}

What this skill DOES:

The agent receives outcome-oriented instructions like:

• "Transform the product idea into a qualified definition by asking strategic questions"
• "Create a staged implementation plan with epics and stories"
• "Implement each stage, test it, and commit if passing"

The agent uses atomic tools (Read, Write, Bash, TaskList, etc.) to achieve these outcomes. The workflow emerges from the agent's decision-making, not from hardcoded steps.

Example: Changing Planning Strategy

Current behavior (defined in prompts):

• Break product into 3-6 epics
• Decompose epics into stages (1-2 days each)
• Generate stories per stage

To change to feature-first planning:

Edit the Phase 2 prompt in references/phase-details.md to say:

Instead of epic-based planning, decompose the product into independent features.
Each feature should be a vertical slice with UI, API, and database components.
Prioritize features by user value and dependencies.

The agent will adapt its planning behavior to this new outcome description, using the same atomic tools (Write, mcpmemorysearch_nodes, etc.) in different ways.

Memory-Driven Behavior Modification

Behavior evolves through Memory MCP without code changes:

// Save a new pattern after successful delivery
mcp__memory__create_entities({
  entities: [
    {
      name: "epic-pattern:marketplace-mvp",
      entityType: "epic-pattern",
      observations: [
        "Product type: Two-sided marketplace",
        "Epic 1: Seller onboarding and profiles",
        "Epic 2: Product catalog and search",
        "Epic 3: Transaction and payment flow",
        "Epic 4: Buyer discovery and reviews",
        "Stages: 8 total, foundation-first approach",
        "Proven in: artmarket project",
        "Duration: 5 days",
        "Key insight: Build payment flow before reviews to validate revenue model early",
      ],
    },
  ],
});

Next time the agent builds a marketplace, it queries memory and adapts its plan based on learned patterns, without any code modification.

Entry Point Detection

When this skill activates, check for existing project state:

First Action: Check project state:

ls -la master-project.json cpo-progress.md docs/user-guide.md 2>/dev/null

Phase Summaries

Phase 1: Product Discovery

Goal: Transform a raw product idea into a qualified, scoped product definition.

Key Steps:

1. Receive and acknowledge the product idea
2. Ask 5-8 strategic discovery questions (target users, scope, tech constraints, success criteria)
3. Synthesize as structured PRD (prd-definition.md) with 8 sections: Summary, Contacts, Background, Objective (incl. North Star Metric), Market Segments, Value Proposition, Solution, Release
4. Define North Star Metric using Business Game classification (Attention/Transaction/Productivity) + 3-5 input metrics
5. Invoke Product Research Agent for competitor analysis and design inspiration
6. Get user approval on PRD

Output: prd-definition.md (structured PRD with North Star Metric) + research findings

Detailed Steps: references/phase-details.md#phase-1

Phase 2: Strategic Planning

Goal: Create a comprehensive, staged implementation plan.

Key Steps:

1. Invoke CTO Advisor Agent for tech stack recommendations and architecture
2. Decompose product into epics (major feature areas)
3. Break epics into stages (implementable chunks)
4. Define user stories for each stage, validated against INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
5. Generate master-project.json with complete plan (includes northStarMetric from PRD)
6. Initialize cpo-progress.md for tracking
7. Calculate cost estimates for MVP and scale
8. Present plan for user approval
9. HARD-GATE: Do NOT proceed to Phase 3 until user explicitly approves. No implicit approval, no auto-proceed, no timeout.

Output: Complete project plan with epics, stages, INVEST-validated stories, and cost estimates

Detailed Steps: references/phase-details.md#phase-2

Phase 3: Stage-by-Stage Implementation

Goal: Implement each stage with quality gates. Supports sequential, parallel, or swarm execution.

Execution Modes:

Enable swarm mode by setting in master-project.json:

{
  "executionMode": "swarm",
  "swarm": {
    "enabled": true,
    "teamName": "cpo-{projectName}",
    "workers": {
      "types": ["frontend", "api", "database"],
      "maxWorkers": 5
    }
  }
}

Key Steps:

1. Load project state and identify next pending stage
2. Check execution mode - sequential, parallel, or swarm
3. Determine stage type and select appropriate specialized agent
4. For Foundation: Invoke Database Setup Agent
5. For UI: Invoke Frontend Design Agent with research context
6. For API: Invoke Backend API Agent
7. If swarm mode:
   • Create team with TeammateTool.spawnTeam()
   • Create tasks for all stages with TaskCreate
   • Spawn specialist workers (frontend-worker, api-worker, database-worker)
   • Monitor via inbox messages, workers self-assign from TaskList
   • Coordinate via TeammateTool messaging
8. If sequential/parallel: Delegate to autonomous-dev
9. Monitor progress and update tracking
10. Test stage with fulltest-skill
11. Commit and push if tests pass, fix and retry if tests fail
12. Repeat for all stages (or wait for swarm completion)

Swarm Workflow Diagram:

┌─────────────────────────────────────────────────────────┐
│                CPO AI (LEADER)                          │
│  - Creates team: cpo-{projectName}                      │
│  - Spawns workers based on stage types                  │
│  - Monitors inboxes for completion                      │
└─────────────────────┬───────────────────────────────────┘
                      │
         ┌────────────┼────────────┐
         ▼            ▼            ▼
    ┌─────────┐  ┌─────────┐  ┌─────────┐
    │Frontend │  │   API   │  │Database │
    │ Worker  │  │ Worker  │  │ Worker  │
    └─────────┘  └─────────┘  └─────────┘
         │            │            │
         └────────────┴────────────┘
                      │
              Shared TaskList
              (stages as tasks)

TeammateTool Message Formatting:

Note: TeammateTool messages support rich Markdown rendering. Use headers, bold, code blocks, tables, and lists for clear communication between CPO leader and specialist workers.

Worker Stage Completion Example:

// Frontend worker reports stage completion
TeammateTool.write({
  to: "leader",
  message: `## Stage Complete: User Dashboard UI

### Worker Status
- **Worker:** frontend-worker
- **Stage:** 2.1 - User Dashboard
- **Duration:** 12 minutes

### Implementation Summary
| Component | Status | Tests |
|-----------|--------|-------|
| \`DashboardLayout\` | ✅ Complete | 4/4 passing |
| \`StatsCards\` | ✅ Complete | 3/3 passing |
| \`ActivityFeed\` | ✅ Complete | 5/5 passing |
| \`QuickActions\` | ✅ Complete | 2/2 passing |

### Files Created
\`\`\`
src/components/dashboard/
├── DashboardLayout.tsx
├── StatsCards.tsx
├── ActivityFeed.tsx
└── QuickActions.tsx
\`\`\`

### Design Notes
- Implemented responsive grid layout
- Used Tailwind CSS with project design tokens
- Added loading skeletons for async data

### Ready for Integration
Stage is ready for fulltest-skill validation.`,
});

Leader Task Assignment Example:

// CPO leader assigns task to API worker
TeammateTool.write({
  to: "api-worker",
  message: `## Task Assignment: Authentication API

### Stage Details
- **Stage:** 1.2 - Auth System
- **Priority:** High (blocks other stages)

### Requirements
Implement the following endpoints:

| Endpoint | Method | Description |
|----------|--------|-------------|
| \`/api/auth/register\` | POST | User registration |
| \`/api/auth/login\` | POST | User login with JWT |
| \`/api/auth/logout\` | POST | Invalidate session |
| \`/api/auth/refresh\` | POST | Refresh JWT token |

### Technical Specs
- Use **bcrypt** for password hashing
- JWT tokens with 15min expiry
- Refresh tokens with 7-day expiry

### Acceptance Criteria
\`\`\`gherkin
Given a new user with valid email
When they submit registration
Then account is created and JWT returned
\`\`\`

### Dependencies
- Database schema must be complete (Stage 1.1)
- Use shared \`/lib/auth\` utilities`,
});

Output: Fully implemented product with all stages complete and tested

Detailed Steps: references/phase-details.md#phase-3

Phase 4: Full Project Validation

Goal: Comprehensive testing of the complete integrated product.

Key Steps:

1. Merge all stage branches to main
2. Run full integration testing suite
3. Verify critical user journeys end-to-end
4. Categorize and fix any integration issues
5. Pass quality gate (all tests passing, no critical bugs)

Output: Fully validated, production-ready application

Detailed Steps: references/phase-details.md#phase-4

Phase 5: Documentation & Delivery

Goal: Create user documentation and deploy to production.

Key Steps:

1. Generate user guide with getting started, features, troubleshooting
2. Generate technical documentation with architecture, setup, API reference
3. Final commit with all documentation
4. Push to GitHub and create release tag
5. Invoke Deployment Agent for production deployment
6. Verify deployment with health checks
7. Generate go-live report with metrics and next steps

Output: Live production application with complete documentation

Detailed Steps: references/phase-details.md#phase-5

Model Configuration

This skill uses Claude Opus 4.6 for maximum capability. Use /fast to toggle faster responses when time is critical.

Hook Events

This skill leverages:

• TeammateIdle: Triggers when a worker agent goes idle (swarm mode)
• TaskCompleted: Triggers when a stage task is marked completed

Quick Commands

Task Cleanup

Use TaskUpdate with status: "deleted" to clean up completed or stale task chains:

{ "taskId": "1", "status": "deleted" }

This prevents task list clutter during long sessions. Clean up task chains after:

• All stages complete and verified
• User cancels a workflow
• Starting a fresh PRD cycle

Completion Signals

This skill explicitly signals completion via structured status returns. Never rely on heuristics like "consecutive iterations without tool calls" to detect completion.

Completion Signal Format

At the end of each phase or when blocked, return:

{
  "status": "complete|partial|blocked|failed",
  "phase": "discovery|planning|implementation|validation|delivery",
  "summary": "Brief description of what was accomplished",
  "deliverables": ["List of files/artifacts created"],
  "nextSteps": ["What should happen next (if partial)"],
  "blockers": ["Issues preventing completion (if blocked)"],
  "errors": ["Error details (if failed)"]
}

Success Signal

{
  "status": "complete",
  "phase": "delivery",
  "summary": "Product successfully delivered and deployed",
  "deliverables": [
    "master-project.json",
    "cpo-progress.md",
    "docs/user-guide.md",
    "docs/technical-docs.md",
    "Live URL: https://..."
  ],
  "metrics": {
    "totalStages": 12,
    "completedStages": 12,
    "testsPassing": true,
    "deploymentStatus": "live"
  }
}

Partial Completion Signal

{
  "status": "partial",
  "phase": "implementation",
  "summary": "Completed 8 of 12 stages",
  "completedItems": ["Stage 1.1", "Stage 1.2", "Stage 2.1", ...],
  "remainingItems": ["Stage 3.1", "Stage 3.2", "Stage 4.1", ...],
  "nextSteps": ["Resume with Stage 3.1 implementation"],
  "canResume": true
}

Blocked Signal

{
  "status": "blocked",
  "phase": "implementation",
  "summary": "Cannot proceed with Stage 2.3 - API integration",
  "blockers": [
    "Missing API credentials",
    "Third-party service unavailable",
    "User input needed: database schema preferences"
  ],
  "completedSoFar": ["Stage 1.1", "Stage 1.2", "Stage 2.1", "Stage 2.2"],
  "userInputRequired": "Please provide API key for service X"
}

Failed Signal

{
  "status": "failed",
  "phase": "implementation",
  "summary": "Stage 2.3 implementation failed after 3 attempts",
  "errors": [
    "Database connection timeout",
    "Authentication module compile error"
  ],
  "completedStages": ["Stage 1.1", "Stage 1.2"],
  "failedStage": "Stage 2.3",
  "recoverySuggestions": [
    "Review database configuration",
    "Check authentication dependencies",
    "Consider simplifying authentication approach"
  ]
}

When to Signal

• After Phase 1: Signal "complete" when product definition is approved
• After Phase 2: Signal "complete" when master-project.json is created and plan approved
• During Phase 3: Signal "partial" after each stage completion, "complete" when all stages done
• After Phase 4: Signal "complete" when all tests pass
• After Phase 5: Signal "complete" when deployed and documentation ready
• Any blocker: Signal "blocked" immediately with clear user action needed
• Any failure: Signal "failed" with errors and recovery options

Error Recovery

Stage Implementation Fails

After max attempts, offer options:

1. Simplify stage (split into smaller stages)
2. Get manual assistance with blockers
3. Skip stage and continue (mark incomplete)
4. Restart stage with different approach

Testing Keeps Failing

After 3 fix iterations, offer options:

1. Review test expectations (may be incorrect)
2. Simplify acceptance criteria
3. Get user input on expected behavior
4. Mark as known issue and continue

Scope Creep Detected

If implementation expands beyond plan:

1. Return to plan (drop extra work)
2. Update plan to include new scope
3. Move extra work to future stage

See: references/phase-details.md for detailed error handling.

Key Files Reference

Integration with Other Skills & Agents

Specialized Subagents

Details: subagents/ directory

Dependent Skills

Reference Documents

Examples & Walkthroughs

Complete Examples:

• Simple Game
• SaaS Task Manager
• E-commerce Marketplace

See: references/examples.md for full walkthroughs with sample inputs/outputs.

Multi-Directory Projects

For monorepos or projects with multiple subdirectories containing their own CLAUDE.md files:

1. Set environment variable: CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1
2. Use --add-dir flag when launching Claude Code to include additional directories

This ensures all project-specific instructions are loaded when orchestrating across multiple packages.

Version & Updates

Current Version: 2.2.0

Recent Changes:

• Added /cpo-go quick-start command
• Integrated specialized subagents for each domain
• Added cost estimation in planning phase
• Improved error recovery with multiple options
• Modular structure with detailed reference docs

Roadmap:

• Real-time collaboration features
• AI-powered cost optimization suggestions
• Automated monitoring setup post-deployment
• Multi-environment deployment (staging/prod)

Memory Integration

This skill uses Memory MCP to cache research, remember decisions, and improve over time.

Memory Entity Types

When to Query Memory

Phase 1 - Discovery:

// Check for similar product research
mcp__memory__search_nodes({ query: "research-cache:{vertical}" });
mcp__memory__search_nodes({ query: "research-cache:{product-type}" });

Phase 2 - Planning:

// Load successful epic patterns for similar products
mcp__memory__search_nodes({ query: "epic-pattern:{product-type}" });

// Check past tech stack decisions
mcp__memory__search_nodes({ query: "tech-stack-decision" });

When to Save to Memory

After Phase 1 Research:

// Cache competitor research (expensive to regenerate)
mcp__memory__create_entities({
  entities: [
    {
      name: "research-cache:{vertical}-{date}",
      entityType: "research-cache",
      observations: [
        "Vertical: {vertical}",
        "Competitors: {list}",
        "Key findings: {summary}",
        "Design patterns: {patterns}",
        "Researched: {date}",
      ],
    },
  ],
});

After Phase 2 Planning:

// Save epic structure that was approved
mcp__memory__create_entities({
  entities: [
    {
      name: "epic-pattern:{product-type}",
      entityType: "epic-pattern",
      observations: [
        "Product type: {type}",
        "Epic count: {count}",
        "Stage breakdown: {stages}",
        "Proven in: {project}",
        "Created: {date}",
      ],
    },
  ],
});

After Phase 5 Delivery:

// Save successful project as reference
mcp__memory__create_entities({
  entities: [
    {
      name: "product-decision:{project}-summary",
      entityType: "product-decision",
      observations: [
        "Project: {name}",
        "Type: {product-type}",
        "Stack: {tech-stack}",
        "Epics: {epic-count}",
        "Duration: {time-to-deliver}",
        "Lessons: {key-learnings}",
        "Completed: {date}",
      ],
    },
  ],
});

Research Cache Strategy

To avoid redundant research:

1. Before invoking Product Research Agent, check memory:

   const cached = await mcp__memory__search_nodes({
     query: "research-cache:{vertical}",
   });
   
   // If cache exists and < 30 days old, use it
   if (cached && daysSince(cached.researched) < 30) {
     return cached.observations;
   }
   

2. After fresh research, cache results with TTL context

3. Memory consolidation will prune stale research (>90 days)

For detailed phase instructions, see: references/phase-details.md For all templates, see: references/templates.md