Claude Code Pm

Claude Code Product Manager

Overview

PM should do the following: 1. Gathers requirements from users 2. Installs OpenSpec + domain skills for Claude Code 3. Delegates to Claude Code in background mode (non-blocking) 4. Validates completion using OpenSpec artifacts

PM does NOT do technical work. PM acts as a bridge between non-technical user and development agent(claude code), and handles requirements and project orchestration.

When to Use

Use this skill when:

• User requests feature development or bug fixes
• User wants managed development with OpenSpec protocol
• User needs work tracked through standardized artifacts

DO NOT use for:

• Quick questions or explanations
• Direct implementation (user can use Claude Code directly)

OpenSpec Protocol

Artifacts: openspec/changes/<change-name>/

• proposal.md - What and why
• specs/ - Requirements and scenarios
• design.md - How to implement
• tasks.md - Task breakdown with status

Commands: /opsx:new, /opsx:ff, /opsx:apply, /opsx:verify, /opsx:archive

Core Workflow

Phase 1: Requirements Gathering

Ask clarifying questions based on request type:

Bug Fixes: Expected vs actual behavior, reproduction steps, impact Features: Problem statement, users, success criteria, constraints, scope Refactoring: Pain points, desired improvements, preservation needs, risks

Document as simple summary and confirm with user.

Phase 2: Setup

Use the setup script to install OpenSpec and domain skills:

# Using setup script (recommended)
scripts/setup.sh <target_workspace> <skill1> <skill2> ...

# Example:
scripts/setup.sh ~/project api-development test-automation

See scripts/README.md for script details.

Phase 3: Delegate to Claude Code

Use the delegate script to start Claude Code in background:

# Using delegate script (recommended)
scripts/delegate.sh <change-name> [max-turns] [workspace]

# Example:
scripts/delegate.sh user-profile-api 100 ~/workspace

Monitor Progress (as needed):

# Using monitor script
scripts/monitor.sh <change-name> [lines]

# Example:
scripts/monitor.sh user-profile-api 20

See scripts/README.md for script details.

Phase 4: Validation

Use the check-completion script to validate:

# Using check-completion script (recommended)
scripts/check-completion.sh <change-name>

# Example:
scripts/check-completion.sh user-profile-api

The script checks:

• Process completion status
• Exit code and errors
• OpenSpec artifacts
• Task completion percentage

Quick PM spot checks:

• All acceptance criteria met?
• Tests written and passing?
• Documentation updated?

Phase 5: Archive & Handover

Archive the change:

cd <target_workspace>
claude -p --dangerously-skip-permissions "/opsx:archive <change-name>"

Present summary to user:

• What was done (from tasks.md)
• Artifacts created (list key files)
• How to verify (test commands)
• Link to OpenSpec artifacts

Get user feedback and handle adjustment requests.

Skills Installation Guide

Essential: OpenSpec tools

openspec init --tools claude

Domain Skills (select based on project):

Install with:

npx skills add cyberelf/agent_skills --skill <skill-name> --agent all -y

See references/skills-catalog.md for complete list.

Best Practices

DO:

• Ask clarifying questions before starting
• Document requirements simply
• Let Claude Code handle all design/implementation
• Trust OpenSpec protocol and skills
• Monitor progress only when needed
• Quick spot checks on completion

DON'T:

• Design solutions yourself
• Implement code yourself
• Pass custom system prompts (use skills instead)
• Micromanage individual tasks
• Break workflow into manual steps
• Override Claude Code's decisions

Key Flags

• --dangerously-skip-permissions - Auto-approve operations
• --max-turns N - Limit agent turns (30-50 typical)
• --output-format stream-json - Structured output for monitoring
• --verbose - Include detailed execution information
• -p - Print mode (required)

Reference Documents

For detailed information:

• Helper Scripts - Automation scripts for common operations
• Skills Catalog - Available skills directory
• Troubleshooting - Common issues and solutions
• Workflow Details - Step-by-step procedures

---

For assistance: Check references above or consult OpenSpec Documentation

Skills Catalog

Available skills for Claude Code agents, organized by category.

Installing Skills

Use the skills CLI tool to install skills:

# Install from GitHub repository
npx skills add vercel-labs/agent-skills --skill <skill-name> -a claude-code -y

# Install to global scope
npx skills add vercel-labs/agent-skills --skill <skill-name> -a claude-code -g -y

# List available skills in a repository
npx skills add vercel-labs/agent-skills --list

# Find skills by keyword
npx skills find <keyword>

Meta Skills

find-skills

Source: vercel-labs/agent-skills Description: Helps discover and install additional skills when the agent needs new capabilities. When to Use: When you need functionality that might exist as an installable skill.

npx skills add vercel-labs/agent-skills --skill find-skills -a claude-code -y

introspection

Source: Your repository (skills/introspection/SKILL.md) Description: Reviews sessions and instructions to identify learning opportunities and improve. When to Use: After completing work, when mistakes were made, or to ensure standards compliance.

Already available in your workspace.

claude-code-pm

Source: Your repository (skills/claude-code-pm/SKILL.md) Description: Act as a Product Manager managing Claude Code development teams. When to Use: For complex development work requiring managed workflow with quality gates.

This is the current skill.

Issue Management Skills

issue-fixer

Source: Your repository (skills/issue-fixer/SKILL.md) Description: Systematic approach for investigating and fixing bugs with minimal impact. When to Use: Bug reports, test failures, unexpected behavior, or issue fixes.

Already available in your workspace.

Design & Architecture Skills

frontend-design

Source: vercel-labs/agent-skills (common pattern) Description: Frontend design patterns, UI/UX best practices, component architecture. When to Use: Building UI components, designing user interfaces, frontend architecture.

npx skills find frontend-design
# Then install the appropriate skill

api-design

Description: RESTful API design, GraphQL schema design, API best practices. When to Use: Designing new APIs, refactoring existing endpoints.

npx skills find api-design

architecture

Description: System architecture, design patterns, scalability considerations. When to Use: Designing system architecture, selecting patterns, planning scalability.

npx skills find architecture

design-patterns

Description: Common design patterns (Singleton, Factory, Observer, etc.) and when to use them. When to Use: Implementing complex functionality, refactoring for maintainability.

npx skills find design-patterns

Development Skills

code-quality

Description: Code quality standards, clean code principles, readability improvements. When to Use: Code reviews, refactoring, ensuring maintainability.

npx skills find code-quality

testing

Description: Testing strategies, unit tests, integration tests, test-driven development. When to Use: Writing tests, improving test coverage, TDD workflows.

npx skills find testing

e2e-testing

Description: End-to-end testing with Playwright, Cypress, or Selenium. When to Use: Full-stack integration testing, user workflow validation.

npx skills find e2e-testing

refactoring

Description: Safe refactoring techniques, code smells identification, incremental improvements. When to Use: Improving code quality, reducing technical debt, simplifying complex code.

npx skills find refactoring

Specialized Domain Skills

database-design

Description: Database schema design, migrations, query optimization, indexing. When to Use: Working with databases, designing schemas, optimizing queries.

npx skills find database

devops

Description: CI/CD pipelines, containerization, deployment automation, infrastructure. When to Use: Setting up CI/CD, Docker/Kubernetes work, deployment scripts.

npx skills find devops

security-audit

Description: Security vulnerability detection, secure coding practices, OWASP guidelines. When to Use: Security reviews, vulnerability scanning, implementing security features.

npx skills find security

documentation

Description: Technical writing, API documentation, README creation, user guides. When to Use: Writing or improving documentation.

npx skills find documentation

migration

Description: Dependency upgrades, framework migrations, version updates. When to Use: Upgrading packages, migrating to new framework versions.

npx skills find migration

Language/Framework Specific Skills

python-best-practices

Description: Python-specific best practices, type hints, async patterns, Pythonic code. When to Use: Python development, code reviews.

npx skills find python

typescript-patterns

Description: TypeScript patterns, advanced types, generics, type safety. When to Use: TypeScript development, improving type safety.

npx skills find typescript

react-patterns

Description: React patterns, hooks, state management, component composition. When to Use: React development, component design.

npx skills find react

fastapi-development

Description: FastAPI patterns, async routes, dependency injection, Pydantic models. When to Use: FastAPI backend development.

npx skills find fastapi

PM-Recommended Skills Combinations

For Bug Fixes

Install these skills for developer agents working on bug fixes:

npx skills add vercel-labs/agent-skills --skill issue-fixer -a claude-code -y
npx skills add vercel-labs/agent-skills --skill introspection -a claude-code -y
npx skills add vercel-labs/agent-skills --skill testing -a claude-code -y

For Feature Development

Install these skills for feature development:

npx skills add vercel-labs/agent-skills --skill code-quality -a claude-code -y
npx skills add vercel-labs/agent-skills --skill testing -a claude-code -y
npx skills add vercel-labs/agent-skills --skill design-patterns -a claude-code -y
npx skills add vercel-labs/agent-skills --skill documentation -a claude-code -y

For Code Reviews

Install these skills for code review agents:

npx skills add vercel-labs/agent-skills --skill code-quality -a claude-code -y
npx skills add vercel-labs/agent-skills --skill security-audit -a claude-code -y
npx skills add vercel-labs/agent-skills --skill introspection -a claude-code -y

For Full-Stack Development

Install these skills for full-stack work:

npx skills add vercel-labs/agent-skills --skill frontend-design -a claude-code -y
npx skills add vercel-labs/agent-skills --skill api-design -a claude-code -y
npx skills add vercel-labs/agent-skills --skill database-design -a claude-code -y
npx skills add vercel-labs/agent-skills --skill testing -a claude-code -y
npx skills add vercel-labs/agent-skills --skill e2e-testing -a claude-code -y

Discovering New Skills

Using find-skills

1. Install the find-skills skill:

npx skills add vercel-labs/agent-skills --skill find-skills -a claude-code -y

2. Let Claude Code agent search for skills:

claude -p "Use find-skills to discover testing-related skills"

Manual Discovery

Search the skills directory:

npx skills find <keyword>

Browse GitHub repositories:

• https://github.com/vercel-labs/agent-skills
• https://skills.sh/ - Skills directory website

Creating Custom Skills

If you can't find a skill that fits your needs, create one:

# Initialize new skill
npx skills init my-custom-skill

# Edit the SKILL.md file
# Add to your repository
# Use it in your agents

Custom Skill Template

---
name: my-custom-skill
description: What this skill does and when to use it
tags:
  - category
  - keywords
---

# My Custom Skill

## When to Use

Describe when this skill should be invoked.

## Steps

1. First, do this
2. Then, do that
3. Finally, do this

## Examples

Show examples of using this skill.

## Tips

- Helpful tips
- Best practices

Skill Management for PM Agents

Install Skills Programmatically

# Define required skills
REQUIRED_SKILLS=(
  "issue-fixer"
  "introspection"
  "testing"
  "code-quality"
)

# Install each skill
for skill in "${REQUIRED_SKILLS[@]}"; do
  npx skills add vercel-labs/agent-skills --skill "$skill" -a claude-code -y
done

Check Installed Skills

# List all installed skills
npx skills list

# List for specific agent
npx skills list -a claude-code

# List global skills
npx skills list -g

Update Skills

# Check for updates
npx skills check

# Update all skills
npx skills update

Remove Skills

# Remove a skill
npx skills remove <skill-name>

# Remove from specific agent
npx skills remove <skill-name> -a claude-code

# Remove from global scope
npx skills remove <skill-name> --global

Skills Best Practices

1. Install What You Need: Don't over-install skills; they add context overhead 2. Start with Essentials: issue-fixer, introspection, testing are good defaults 3. Domain-Specific Skills: Add skills based on project tech stack 4. Keep Updated: Regularly check for skill updates 5. Document Usage: Note which skills are used for which agent types 6. Remove Unused: Clean up skills that aren't being utilized 7. Custom Skills: Create project-specific skills for recurring patterns 8. Share Skills: Commit useful skills to your repository for team use

Skill Scopes

Project Scope (Default)

Installed to .claude/skills/ in the project directory:

npx skills add vercel-labs/agent-skills --skill <skill-name> -a claude-code -y

Shared with team: Yes (committed to git) Available across projects: No

Global Scope

Installed to ~/.claude/skills/ in user's home directory:

npx skills add vercel-labs/agent-skills --skill <skill-name> -a claude-code -g -y

Shared with team: No Available across projects: Yes

Integration with PM Workflow

Phase 2: Planning & Agent Setup

When setting up agents, install required skills:

cd <target_workspace>

# Install core skills
npx skills add vercel-labs/agent-skills \
  --skill issue-fixer \
  --skill introspection \
  --skill testing \
  -a claude-code -y

# Install domain-specific skills based on workspace analysis
# Example: Python backend
npx skills add vercel-labs/agent-skills \
  --skill python-best-practices \
  -a claude-code -y

# Example: React frontend
npx skills add vercel-labs/agent-skills \
  --skill react-patterns \
  --skill frontend-design \
  -a claude-code -y

Using Skills in Agent Definitions

Reference skills in agent configurations:

{
  "developer": {
    "description": "Senior developer",
    "prompt": "Implement features using best practices",
    "skills": ["issue-fixer", "testing", "code-quality"],
    "model": "sonnet"
  }
}

Dynamic Skill Installation

If an agent needs a skill during execution:

# PM agent detects need for database skill
claude -p "Use find-skills to discover database migration skills, then install the best match"

# Then continue with task
claude -p --agent developer "Create database migration for user table"

Reference

• Skills CLI Documentation: https://github.com/vercel-labs/skills
• Agent Skills Specification: https://agentskills.io/
• Skills Directory: https://skills.sh/
• Claude Code Skills Documentation: https://code.claude.com/docs/en/skills

---

For PM agents: Always analyze the target workspace and requirements to determine which skills will be most valuable for the dev agents to have.

Troubleshooting Guide

Common issues and solutions when using the claude-code-pm skill.

Process Management Issues

Background Process Not Responding

Symptoms:

• No new output in jsonl file
• Process appears stuck
• No progress for extended period

Diagnosis:

# Check if process is still running
ps -p $PID > /dev/null && echo "✓ Running" || echo "✗ Stopped"

# Check recent output
tail -n 50 output.jsonl

# Check for errors
grep -i error output.jsonl | tail -n 10

Solutions:

1. If process is truly stuck (no output for 5+ minutes):

   # Graceful termination
   kill $PID
   
   # Force kill if needed
   kill -9 $PID

2. Restart with adjustments:

   # Increase max-turns or clarify requirements
   claude -p \
     --dangerously-skip-permissions \
     --max-turns 100 \
     --output-format stream-json \
     --verbose \
     "..." > output_retry.jsonl 2>&1 &

3. Inform user and ask if they want to retry or adjust approach.

---

Execution Issues

Claude Code Stops Early

Symptoms:

• Process exits before all tasks complete
• Tasks.md shows incomplete items
• Exit code 0 but work not finished

Causes:

• Insufficient --max-turns
• Unclear requirements
• Implicit stopping condition triggered

Solutions:

1. Increase max-turns:

   # For complex features
   --max-turns 100
   
   # For simple fixes
   --max-turns 50

2. Be explicit in prompt:

   "... then /opsx:verify. Ensure ALL tasks are completed before stopping."

3. Refine requirements:

• Add more specific acceptance criteria
• Clarify ambiguous points
• Provide examples

4. Continue from where it stopped:

   claude -p \
     --dangerously-skip-permissions \
     --max-turns 50 \
     --output-format stream-json \
     --verbose \
     "Continue change '<name>'. Complete remaining tasks and run /opsx:verify." \
     > <name>_continue.jsonl 2>&1 &

---

Verification Fails

Symptoms:

• /opsx:verify reports failures
• Tests don't pass
• Tasks.md shows incomplete checkboxes

Diagnosis:

# Review what failed
cat openspec/changes/<name>/tasks.md

# Check verification output in jsonl
grep -A 10 "verify" output.jsonl | tail -n 20

Solutions:

1. Run fix iteration:

   cd <target_workspace>
   
   claude -p \
     --dangerously-skip-permissions \
     --max-turns 30 \
     --output-format stream-json \
     --verbose \
     "Continue change '<name>'. Fix issues from verification. Use /opsx:apply then /opsx:verify." \
     > <name>_fix.jsonl 2>&1 &
   
   PID=$!
   echo "🔄 Started fix iteration (PID: $PID)"

2. Review specific failures:

• Read tasks.md for unchecked items
• Check test output
• Review error messages

3. Multiple iterations if needed:

• First iteration: Address obvious failures
• Second iteration: Edge cases and polish
• Final iteration: Comprehensive verification

---

Configuration Issues

Skills Not Applied

Symptoms:

• Claude Code doesn't follow expected patterns
• Missing features that skills should provide
• Generic output instead of specialized

Diagnosis:

# Check if skills are installed
ls -la .agents/skills/

# Check OpenSpec tools
ls -la .agents/tools/ | grep opsx

# Verify skill content
cat .agents/skills/<skill-name>/SKILL.md

Solutions:

1. Reinstall OpenSpec:

   cd <target_workspace>
   openspec init --tools claude

2. Reinstall skills with --agent all:

   npx skills add cyberelf/agent_skills --skill <skill-name> --agent all -y

3. Don't pass custom system prompts:

• System prompts override skill context
• Use skills instead of prompts
• Let skills provide specialized knowledge

4. Verify skills are loaded:

   # Check claude reads skills
   grep -r "SKILL.md" .agents/skills/

---

Permission Errors

Symptoms:

• Claude Code still asks for permission
• Operations blocked despite flags
• Interactive prompts appear

Diagnosis:

# Check settings
cat .claude/settings.json

# Verify command flags
echo $LAST_COMMAND

Solutions:

1. Double-check flag spelling:

   # Correct (double dash)
   --dangerously-skip-permissions
   
   # Wrong
   -dangerously-skip-permissions
   --dangerous-skip-permissions

2. Ensure print mode enabled:

   # Must have -p flag
   claude -p --dangerously-skip-permissions ...

3. Check settings.json:

   # Look for restricted operations
   cat .claude/settings.json
   
   # Remove restrictions if present
   # Or add to allowlist

4. Run with explicit permissions:

   # If specific operations blocked
   claude -p \
     --dangerously-skip-permissions \
     --allow-all-operations \
     ...

---

Output and Monitoring Issues

Cannot Parse JSON Output

Symptoms:

• jq commands fail
• Corrupted or incomplete JSON lines
• Mixed text and JSON in output

Solutions:

1. Use stream-json format:

   --output-format stream-json

2. Filter for valid JSON:

   # Extract only JSON lines
   grep '^{' output.jsonl | jq -r 'select(.type == "stream_event")'

3. Parse with error handling:

   # Ignore invalid lines
   cat output.jsonl | jq -r 'select(.type == "stream_event") .event.delta.text' 2>/dev/null

---

Output File Too Large

Symptoms:

• JSONL file grows to hundreds of MB
• Slow to read/parse
• Fills disk space

Solutions:

1. Tail recent entries only:

   tail -n 1000 output.jsonl > recent.jsonl

2. Rotate output files:

   mv output.jsonl output_backup.jsonl
   # Claude Code continues writing to original file handle

3. Filter important events:

   # Extract errors and completions only
   grep -E 'error|warning|completed|verified' output.jsonl > events.jsonl

4. Use compression:

   gzip output.jsonl
   zcat output.jsonl.gz | tail -n 100

---

Workflow Issues

Multiple Concurrent Sessions Conflict

Symptoms:

• Git conflicts
• Overlapping file changes
• Output files overwritten

Solutions:

1. Use git worktrees:

   # Create separate worktree for each task
   git worktree add ../workspace-feature-a feature-a
   git worktree add ../workspace-bugfix-b bugfix-b
   
   # Run Claude Code in each
   cd ../workspace-feature-a
   claude -p ... > feature_a.jsonl 2>&1 &
   
   cd ../workspace-bugfix-b
   claude -p ... > bugfix_b.jsonl 2>&1 &

2. Use unique output files:

   # Include timestamp or change name
   > feature_$(date +%s).jsonl
   > fix_password_$(date +%Y%m%d_%H%M%S).jsonl

3. Track PIDs separately:

   PID_FEATURE_A=$!
   PID_BUGFIX_B=$!
   
   # Monitor each
   ps -p $PID_FEATURE_A
   ps -p $PID_BUGFIX_B

---

Common Mistakes

Mistake: Breaking Work Into Steps

Wrong:

# Step 1
claude -p "Create design"

# Step 2
claude -p "Implement design"

# Step 3
claude -p "Write tests"

Right:

# Single command with OpenSpec
claude -p \
  --dangerously-skip-permissions \
  --max-turns 50 \
  "Use /opsx:new <name>, then /opsx:ff, /opsx:apply, /opsx:verify" \
  > output.jsonl 2>&1 &

---

Mistake: PM Making Technical Decisions

Wrong:

## Requirements
Use React with Redux.
Create components: Header, Sidebar, Dashboard.
API calls via Axios.

Right:

## Requirements
Display user dashboard with navigation.
Must load data from API.
Must be responsive.

---

Mistake: Over-Monitoring

Wrong:

# Checking every 10 seconds
while true; do
  tail -n 5 output.jsonl
  sleep 10
done

Right:

# Check once at start, once at end
echo "Started (PID: $PID)"
wait $PID
echo "Completed with exit code $?"

---

Quick Diagnostic Commands

# Is process running?
ps -p $PID > /dev/null && echo "Running" || echo "Stopped"

# How long has it been running?
ps -p $PID -o etime=

# Recent output (last 20 lines)
tail -n 20 output.jsonl

# Any errors?
grep -i error output.jsonl | tail -n 5

# Parse JSON events
tail -n 100 output.jsonl | jq -r 'select(.type == "stream_event") | .event.delta.text' 2>/dev/null | tail -n 20

# Check exit code
wait $PID
echo $?

# OpenSpec status
cat openspec/changes/<name>/tasks.md | grep -E '\[[ x]\]'

---

Getting Help

If issues persist:

1. Check recent output: tail -n 100 output.jsonl 2. Review OpenSpec artifacts: Especially tasks.md and design.md 3. Consult references:

• CLI Commands
• Workflow Details
• Examples

4. Check OpenSpec docs: https://github.com/Fission-AI/OpenSpec 5. Ask user for clarification: On requirements or priorities

Claude Code PM Workflow Reference

Detailed step-by-step guide using OpenSpec protocol.

Version

Current: v3.0 (OpenSpec Protocol)

• Uses standardized /opsx:* commands
• Implicit multi-agent via skills
• No custom agent JSON definitions
• Full automation with --dangerously-skip-permissions

Workflow Overview

Requirements → OpenSpec Setup → Delegation → Validation → Archive → Handover
     ↓               ↓              ↓            ↓           ↓         ↓
  Document       Install         Execute      /opsx:      /opsx:    Deliver
   + Confirm     Skills          Claude       verify     archive   Summary
                                 Code

Key Principles

1. PM = Requirements Expert: Don't design or implement 2. OpenSpec = Standard Protocol: Use /opsx:* commands 3. Skills = Context: Install skills, don't pass system prompts 4. Implicit Multi-Agent: Claude Code self-organizes 5. Full Automation: Use --dangerously-skip-permissions

Phase 1: Requirements Gathering

Step 1.1: Initial Discovery Questions

Ask these questions systematically:

For Bug Reports:

• What is the expected behavior?
• What is the actual behavior?
• How can the bug be reproduced?
• What error messages appear (if any)?
• When did this start happening?
• What is the impact (users affected, severity)?
• Are there any workarounds?

For Features:

• What problem does this feature solve?
• Who will use this feature?
• What are the success criteria?
• Are there examples or references?
• What constraints exist (performance, security, compatibility)?
• What is out of scope?
• Priority level?

For Refactoring:

• What pain points exist currently?
• What improvements are desired?
• What must be preserved?
• What are the risks?
• How is success measured?

Step 1.2: Create Requirements Document

cd <target_workspace>

# Create simple requirements file
cat > requirements.md << 'EOF'
# <Task Name>

## Goal
<What needs to be accomplished>

## Acceptance Criteria
- [ ] Criterion 1: Specific, measurable outcome
- [ ] Criterion 2: Specific, measurable outcome
- [ ] Criterion 3: Specific, measurable outcome

## Context
<Important background information>
- Affected components
- Related code locations
- Tech stack details

## Constraints
<What must be preserved or avoided>

## Out of Scope
<What will NOT be included>
EOF

IMPORTANT: Don't include design decisions or implementation details. That's for Claude Code to decide.

Step 1.3: User Confirmation

Present to user:

"I've documented the requirements for [task]. Here's what I understand:

>

[Summary of key points]

>

Acceptance criteria:

- Criterion 1

- Criterion 2

- Criterion 3

>

Does this capture everything correctly? Any additions or corrections?"

Wait for explicit confirmation before proceeding.

Phase 2: OpenSpec Setup & Skill Installation

Step 2.1: Install OpenSpec

cd <target_workspace>

# Install OpenSpec protocol tools
openspec init --tools claude

echo "✅ OpenSpec installed"

Step 2.2: Analyze Project & Identify Skills

# Check tech stack
if [ -f package.json ]; then
  echo "Node.js/TypeScript project"
  TECH="nodejs"
elif [ -f pyproject.toml ] || [ -f requirements.txt ]; then
  echo "Python project"
  TECH="python"
fi

# Check for framework
if grep -q '"next"' package.json 2>/dev/null; then
  echo "Next.js detected"
  FRAMEWORK="nextjs"
elif grep -q '"react"' package.json 2>/dev/null; then
  echo "React detected"
  FRAMEWORK="react"
elif grep -q 'fastapi' requirements.txt 2>/dev/null; then
  echo "FastAPI detected"
  FRAMEWORK="fastapi"
fi

Step 2.3: Install Domain Skills

Based on project type and task:

Backend API Tasks:

npx skills add cyberelf/agent_skills --skill api-development --agent all -y
npx skills add cyberelf/agent_skills --skill database-design --agent all -y
npx skills add cyberelf/agent_skills --skill test-automation --agent all -y

Frontend Tasks:

npx skills add cyberelf/agent_skills --skill ui-development --agent all -y
npx skills add cyberelf/agent_skills --skill react-patterns --agent all -y
npx skills add cyberelf/agent_skills --skill test-automation --agent all -y

Bug Fixing:

npx skills add cyberelf/agent_skills --skill debugging --agent all -y
npx skills add cyberelf/agent_skills --skill issue-fixer --agent all -y
npx skills add cyberelf/agent_skills --skill test-automation --agent all -y

Python Projects:

npx skills add cyberelf/agent_skills --skill python-best-practices --agent all -y

TypeScript Projects:

npx skills add cyberelf/agent_skills --skill typescript-patterns --agent all -y

Step 2.4: Create OpenSpec Change

cd <target_workspace>

# Create the change
claude -p "/opsx:new <change-name>"

# This creates: openspec/changes/<change-name>/

Step 2.5: Add Requirements to Change

# Copy requirements to OpenSpec change directory
cp requirements.md openspec/changes/<change-name>/

echo "✅ OpenSpec change created with requirements"

Phase 3: Autonomous Delegation to Claude Code

Step 3.1: Execute Single Autonomous Command

Full automation using OpenSpec protocol:

cd <target_workspace>

# Execute Claude Code with OpenSpec workflow
claude -p \
  --dangerously-skip-permissions \
  --max-turns 50 \
  --output-format json \
  "Continue the OpenSpec change '<change-name>'. Read requirements from requirements.md. Use /opsx:ff to generate all planning artifacts (proposal, specs, design, tasks), then /opsx:apply to implement all tasks, then /opsx:verify to validate. Ensure all tasks are completed." \
  > output.json

echo "✅ Claude Code execution complete"

What happens autonomously: 1. Claude Code reads requirements.md 2. /opsx:ff generates:

• proposal.md (what and why)
• specs/ (detailed requirements)
• design.md (implementation approach)
• tasks.md (task breakdown)

3. /opsx:apply implements all tasks 4. /opsx:verify validates completeness/correctness/coherence

Step 3.2: Monitor Completion

# Parse output
SUCCESS=$(cat output.json | jq -r '.success')
RESULT=$(cat output.json | jq -r '.result')

if [ "$SUCCESS" = "true" ]; then
  echo "✅ Claude Code completed successfully"
  echo "Result: $RESULT"
else
  echo "❌ Claude Code encountered issues"
  ERROR=$(cat output.json | jq -r '.error')
  echo "Error: $ERROR"
fi

Step 3.3: Check Artifacts Created

cd openspec/changes/<change-name>

# Verify all artifacts exist
echo "Checking OpenSpec artifacts..."

[ -f proposal.md ] && echo "✅ proposal.md" || echo "❌ Missing proposal.md"
[ -d specs ] && echo "✅ specs/" || echo "❌ Missing specs/"
[ -f design.md ] && echo "✅ design.md" || echo "❌ Missing design.md"
[ -f tasks.md ] && echo "✅ tasks.md" || echo "❌ Missing tasks.md"

# Check tasks.md for completion
TOTAL_TASKS=$(grep -c "^- \[" tasks.md)
COMPLETED_TASKS=$(grep -c "^- \[x\]" tasks.md)

echo "Tasks: $COMPLETED_TASKS/$TOTAL_TASKS completed"

Phase 4: Validation & Archive

Step 4.1: Review Verification Results

cd <target_workspace>

# Check what /opsx:verify reported
cat openspec/changes/<change-name>/tasks.md

Look for:

• ✅ All tasks checked off [x]
• ✅ Verification notes showing tests passed
• ✅ Implementation matches specs
• ✅ No errors reported

Step 4.2: PM Spot Check (Quick)

Minimal validation - trust OpenSpec:

# 1. Completeness check
TOTAL=$(grep -c "^- \[" openspec/changes/<change-name>/tasks.md)
DONE=$(grep -c "^- \[x\]" openspec/changes/<change-name>/tasks.md)

if [ "$TOTAL" -eq "$DONE" ]; then
  echo "✅ All tasks complete ($DONE/$TOTAL)"
else
  echo "⚠️ Incomplete: $DONE/$TOTAL tasks"
fi

# 2. Tests check (if applicable)
if [ -f package.json ]; then
  npm test && echo "✅ Tests passing" || echo "❌ Tests failing"
elif [ -f pyproject.toml ]; then
  python -m pytest && echo "✅ Tests passing" || echo "❌ Tests failing"
fi

# 3. Artifacts check
ls -la openspec/changes/<change-name>/

That's it. Don't do deep code review - OpenSpec handles quality.

Step 4.3: Archive the Change

cd <target_workspace>

# Archive using OpenSpec
claude -p \
  --dangerously-skip-permissions \
  "/opsx:archive <change-name>"

echo "✅ Change archived"

This will:

• Sync delta specs to main spec repository
• Move to openspec/changes/archive/<date>-<change-name>/
• Finalize the change

Phase 5: Handover to User

Step 5.1: Prepare Delivery Summary

cat > delivery_summary.md << 'EOF'
# ✅ Completed: <Change Name>

**Status**: Complete
**OpenSpec Change**: openspec/changes/archive/<date>-<change-name>/

## What Was Done

<1-2 sentence summary from proposal.md>

## Artifacts Created

- ✅ Proposal: What and why
- ✅ Specs: Requirements and scenarios
- ✅ Design: Implementation approach
- ✅ Tasks: All completed (X/X tasks done)
- ✅ Code: Implementation complete
- ✅ Tests: All passing

## How to Verify

View change artifacts

cat openspec/changes/archive/<date>-<change-name>/proposal.md

Run tests

<test command from tasks.md>

Try it out

<manual testing steps if applicable>

## OpenSpec Artifacts

All artifacts in: `openspec/changes/archive/<date>-<change-name>/`

Review:
- `proposal.md` for what and why
- `specs/` for detailed requirements
- `design.md` for implementation approach
- `tasks.md` for completed tasks
EOF

Step 5.2: Present to User

Share with user:

"✅ Work Complete: <change-name>

>

Claude Code has completed the work following OpenSpec protocol:

- All planning artifacts generated (proposal, specs, design, tasks)

- All tasks implemented

- Verification passed

- Change archived

>

Artifacts location: openspec/changes/archive/<date>-<change-name>/

>

<How to verify section>

>

Let me know if you need any adjustments!"

Step 5.3: Handle User Feedback

Wait for response:

If user approves:

✅ Task complete
PM session successful

If user requests changes:

⚠️ Changes requested
Creating new requirements
Returning to Phase 2 (OpenSpec setup)
Run new iteration with /opsx:ff and /opsx:apply

Troubleshooting

Issue: Claude Code Stopped Early

Symptom: Not all tasks completed

Solution:

# Increase max-turns and be explicit
claude -p --dangerously-skip-permissions --max-turns 100 \
  "Continue change '<name>'. Complete ALL remaining tasks in tasks.md. Use /opsx:apply until EVERY task is checked [x]. Then /opsx:verify."

Issue: Verification Failed

Symptom: /opsx:verify reports issues

Solution:

# Review issues
cat openspec/changes/<change-name>/tasks.md

# Run fix iteration
claude -p --dangerously-skip-permissions --max-turns 30 \
  "Continue change '<name>'. Fix issues from verification. Use /opsx:apply then /opsx:verify."

Issue: Skills Not Working

Symptom: Claude Code doesn't apply domain knowledge

Solution:

# Verify installation
ls -la .agents/skills/

# Reinstall OpenSpec
openspec init --tools claude

# Reinstall other skills
npx skills add cyberelf/agent_skills --skill <skill> --agent all -y

Issue: Permission Errors

Symptom: Claude Code asks for permission despite flags

Solution:

• Check double-dash: --dangerously-skip-permissions
• Ensure -p print mode enabled
• Check .claude/settings.json doesn't restrict operations

PM Success Checklist

Before completing task:

## PM Final Checklist

### Requirements
- [ ] Requirements documented clearly
- [ ] User confirmed understanding
- [ ] No design/implementation by PM

### OpenSpec Setup
- [ ] OpenSpec skill installed
- [ ] Domain skills installed
- [ ] Change created with /opsx:new

### Delegation
- [ ] Single autonomous command executed
- [ ] --dangerously-skip-permissions used
- [ ] Sufficient --max-turns set (30-50)

### Artifacts
- [ ] proposal.md exists
- [ ] specs/ directory exists
- [ ] design.md exists
- [ ] tasks.md exists with all tasks [x]

### Validation
- [ ] /opsx:verify completed
- [ ] PM spot check done
- [ ] Tests passing (if applicable)

### Archive
- [ ] Change archived with /opsx:archive
- [ ] Artifacts in archive directory

### Handover
- [ ] Summary prepared
- [ ] Verification instructions provided
- [ ] User informed

---

Remember: PM handles requirements only. OpenSpec + Claude Code + Skills handle everything else. Trust the protocol.

Helper Scripts

Automation scripts for common claude-code-pm operations.

Available Scripts

setup.sh

Setup OpenSpec and install skills for a workspace.

Usage:

scripts/setup.sh <workspace-path> [skill1] [skill2] ...

Examples:

# Setup in current directory with API skills
scripts/setup.sh . api-development test-automation

# Setup in another workspace with debugging skills
scripts/setup.sh ~/projects/myapp debugging test-automation

---

delegate.sh

Start Claude Code in background for a change.

Usage:

scripts/delegate.sh <change-name> [max-turns] [workspace-path]

Examples:

# Start with defaults (50 turns, current dir)
scripts/delegate.sh user-profile-api

# Start with custom turns
scripts/delegate.sh fix-login-bug 30

# Start in different workspace
scripts/delegate.sh add-dark-mode 40 ~/projects/webapp

What it does:

• Starts Claude Code in background
• Saves PID to .claude_<change-name>.pid
• Redirects output to <change-name>.jsonl
• Shows initial output and monitoring commands

---

monitor.sh

Check status and recent output of a running change.

Usage:

scripts/monitor.sh <change-name> [lines]

Examples:

# Show last 20 lines (default)
scripts/monitor.sh user-profile-api

# Show last 50 lines
scripts/monitor.sh user-profile-api 50

What it shows:

• Process status (running/stopped)
• Elapsed time
• Recent output lines
• Error count and recent errors
• Task progress from tasks.md

---

check-completion.sh

Validate completion and readiness for archive.

Usage:

scripts/check-completion.sh <change-name>

Examples:

scripts/check-completion.sh user-profile-api

What it checks:

• Process status
• Output file size and errors
• OpenSpec artifacts existence
• Task completion percentage
• Readiness for archive

Output:

• ✅ All complete → Ready for archive
• ⏸️ Incomplete tasks → Shows what's left
• ❌ Issues found → Shows errors

---

Typical Workflow

# 1. Setup workspace
cd ~/projects/myapp
scripts/setup.sh . api-development test-automation

# 2. Create requirements.md with your requirements

# 3. Delegate
scripts/delegate.sh user-profile-api 50

# 4. Monitor (optional, while running)
scripts/monitor.sh user-profile-api

# 5. Check completion
scripts/check-completion.sh user-profile-api

# 6. Archive (when complete)
claude -p --dangerously-skip-permissions "/opsx:archive user-profile-api"

---

Environment Requirements

These scripts require:

• bash 4.0+
• claude CLI installed
• openspec CLI installed
• npx (Node.js) for skills installation
• Standard Unix tools: ps, grep, tail, wc

Permissions

All scripts have execute permissions. If needed:

chmod +x scripts/*.sh