Skip to content

srstomp/pokayokay

BranchesTags

Repository files navigation

                 __                           __
    ____  ____  / /______ _  __  ______  / /______ ___  __
   / __ \/ __ \/ //_/ __ `/ / / / / __ \/ //_/ __ `/ / / /
  / /_/ / /_/ / ,< / /_/ / / /_/ / /_/ / ,< / /_/ / /_/ /
 / .___/\____/_/|_|\__,_/  \__, /\____/_/|_|\__,_/\__, /
/_/                       /____/                 /____/

pokayokay

AI-assisted development orchestration - A Claude Code plugin that orchestrates AI-assisted development sessions with configurable human oversight, bridging the gap between hands-on control and full automation through skills, hooks, agents, and integration with ohno for task management.

Features

  • PRD to Tasks - Automatically break down requirements into epics, stories, and tasks
  • Orchestrated Sessions - Work across multiple sessions without losing context
  • Human Checkpoints - Choose your autonomy level: supervised, semi-auto, auto, or unattended
  • Multi-Dimensional Auditing - Verify accessibility, testing, security, docs, and observability
  • 21 Specialized Skills - Route work to domain-specific workflows automatically
  • Spike Protocol - Time-boxed investigations with mandatory decisions

Prerequisites

  • Claude Code v1.0.0 or later
  • Node.js v18 or later (for ohno CLI)
  • Git (for version control integration)

Installation

The easiest way to install is with the setup wizard:

npx pokayokay

This interactive wizard will:

  1. Install the pokayokay Claude Code plugin
  2. Configure the ohno MCP server
  3. Initialize ohno in your project
  4. Optionally set up kaizen integration

Run npx pokayokay doctor anytime to verify your installation.

Manual Installation

Click to expand manual steps 
# 1. Add the marketplace (one-time setup)
claude plugin marketplace add srstomp/pokayokay

# 2. Install the plugin
claude plugin install pokayokay@srstomp-pokayokay

Or from inside Claude Code REPL:

/plugin marketplace add srstomp/pokayokay
/plugin install pokayokay@srstomp-pokayokay

Required: ohno MCP Server

Add to your MCP configuration (~/.claude/settings.json):

{
  "mcpServers": {
    "ohno": {
      "command": "npx",
      "args": ["@stevestomp/ohno-mcp"]
    }
  }
}

Initialize ohno

npx @stevestomp/ohno-cli init

Quick Start

# 1. Run setup wizard (if not done already)
npx pokayokay

# 2. Restart Claude Code to activate MCP server

# 3. Plan from a PRD
/pokayokay:plan docs/prd.md

# 4. View kanban board
npx @stevestomp/ohno-cli serve

# 5. Start working
/pokayokay:work supervised

# 6. Audit completeness
/pokayokay:audit --full

Commands

Core Workflow

Command Description
/pokayokay:plan [--headless] [--review] <path> Analyze PRD and create tasks with skill routing
/pokayokay:revise [--direct] Revise existing plan with impact analysis
/pokayokay:work [mode] [-n N] Start/continue work session (supervised/semi-auto/auto/unattended)
/pokayokay:audit [feature] Audit feature completeness across 5 dimensions
/pokayokay:review Analyze session patterns and skill effectiveness
/pokayokay:handoff Prepare session handoff with context preservation
/pokayokay:hooks View and manage hook configuration
/pokayokay:worktrees List, cleanup, switch, or remove worktrees

Ad-Hoc Work

Command Description
/pokayokay:quick <task> Create task and work inline (no agents)
/pokayokay:fix [--thorough] <bug> Bug fix with diagnosis + light pipeline (--thorough for full)
/pokayokay:spike <question> Time-boxed technical investigation
/pokayokay:hotfix <incident> Production incident response

Development

Command Description
/pokayokay:api <task> API design - REST/GraphQL patterns
/pokayokay:arch <area> Architecture review and refactoring
/pokayokay:db <task> Database schema and migrations
/pokayokay:test <task> Testing strategy and implementation
/pokayokay:integrate <api> Third-party API integration
/pokayokay:sdk <task> SDK creation and extraction

Infrastructure & Quality

Command Description
/pokayokay:cicd <task> CI/CD pipeline creation and optimization
/pokayokay:security <area> Security audit and vulnerability scanning
/pokayokay:observe <task> Logging, metrics, and tracing

Research & Documentation

Command Description
/pokayokay:research <topic> Extended technical research
/pokayokay:docs <task> Technical documentation

Skills

The plugin includes 21 specialized skills loaded on demand via commands or planner routing:

Orchestration (process skills - add structure Claude wouldn't do alone)

  • work-session - Coordinator workflow, modes, agent dispatch
  • planning - PRD-to-task breakdown with ohno integration
  • plan-revision - Impact analysis on existing plans
  • spike - Time-boxed investigation with structured output
  • deep-research - Multi-day technology evaluation
  • session-review - Post-session analysis and handoff prep
  • feature-audit - L0-L5 completeness verification
  • worktrees - Git worktree management
  • browser-verification - Playwright UI verification

Domain (reference material for implementer agents)

  • api-design - REST/GraphQL endpoint design
  • api-integration - Third-party API consumption
  • database-design - Schema design, migrations, optimization
  • architecture-review - Code structure, module boundaries
  • ci-cd - GitHub Actions, GitLab CI, deployment strategies
  • cloud-infrastructure - AWS service selection, CDK patterns
  • observability - Logging, metrics, tracing, alerting
  • testing-strategy - Test architecture, coverage, E2E patterns
  • security-audit - OWASP Top 10, dependency scanning
  • error-handling - Error hierarchies, recovery patterns
  • sdk-development - TypeScript SDK extraction and publishing
  • documentation - READMEs, API docs, ADRs

Audit Dimensions

The /pokayokay:audit command checks 5 dimensions:

Dimension Levels Description
Accessibility L0-L5 Is the feature user-accessible?
Testing T0-T4 Test coverage and types
Documentation D0-D4 Code comments to user docs
Security S0-S4 Input validation to hardened
Observability O0-O4 Logging to full telemetry 
/pokayokay:audit                    # Quick (accessibility only)
/pokayokay:audit --dimension testing  # Specific dimension
/pokayokay:audit --full              # All dimensions

Work Modes

Mode Task Story Epic
supervised PAUSE PAUSE PAUSE
semi-auto log PAUSE PAUSE
auto skip log PAUSE
unattended skip skip skip

Parallel Execution

Run multiple tasks simultaneously for faster throughput:

# Run up to 3 tasks in parallel
/pokayokay:work semi-auto -n 3

# Adaptive sizing (starts at 2, adjusts based on outcomes)
/pokayokay:work semi-auto -n auto

Note: -p is reserved for the Claude CLI --prompt flag. Use -n for parallel count.

How it works:

  • Coordinator dispatches N implementer agents in a single message
  • Each agent works independently with fresh context
  • Results processed as they complete
  • Dependency graph prevents unsafe parallelization

Adaptive mode (-n auto):

  • Starts at 2 parallel tasks
  • Scales up (max 4) when tasks succeed consecutively
  • Scales down (min 2) when failures occur
  • Displays batch size changes during session

Recommended settings:

  • Default: 1 (sequential, safest)
  • Independent tasks: 2-3
  • Adaptive: auto (recommended for most sessions)
  • Maximum: 5

Tradeoffs:

  • Higher token usage (N concurrent contexts)
  • Potential git conflicts (auto-resolved when possible)
  • No shared learning between parallel agents

Session Resume

Resume interrupted work sessions without losing context:

# Resume the last session, picking up where you left off
/pokayokay:work --continue

Loads tasks with saved WIP data from ohno, skips brainstorming for resumed tasks, and dispatches the implementer with previous context.

Headless Session Chaining

When context fills during auto-mode work, sessions can automatically chain — finishing gracefully and spawning a new session that resumes from WIP. This is configured in .claude/pokayokay.json, not via a command flag:

{
  "headless": {
    "max_chains": 10,
    "report": "on_complete",
    "notify": "terminal"
  }
}

Chaining requires an explicit scope to prevent runaway sessions:

# Scope to a story — chains will continue until story tasks are done
/pokayokay:work auto --story story-abc123

# Scope to an epic
/pokayokay:work auto --epic epic-def456

Chain reports are generated to .ohno/reports/. The max chains limit (default 10) prevents runaway execution.

Worktree Isolation

Tasks automatically run in isolated git worktrees based on type:

Task Type Behavior Override
feature, bug, spike Worktree --in-place
chore, docs In-place --worktree 
# Default: smart based on task type
/pokayokay:work

# Force worktree for a chore
/pokayokay:work --worktree

# Force in-place for a feature
/pokayokay:work --in-place

Story-based reuse: Tasks in the same story share a worktree, keeping related changes together.

On completion: Choose to merge, create PR, keep worktree, or discard work.

Sub-Agents

pokayokay includes 13 specialized sub-agents that run in isolated context windows for verbose operations:

Agent Model Purpose
yokay-auditor Sonnet L0-L5 completeness scanning (read-only)
yokay-brainstormer Sonnet Refines ambiguous tasks into clear requirements
yokay-browser-verifier Sonnet Browser verification for UI changes (read-only)
yokay-explorer Haiku Fast codebase exploration (read-only, 5-10x cheaper)
yokay-fixer Sonnet Auto-retry on test failures with targeted fixes
yokay-implementer Sonnet TDD implementation with fresh context
yokay-planner Sonnet PRD analysis and structured plan generation
yokay-reviewer Sonnet Code review and analysis (read-only)
yokay-security-scanner Sonnet OWASP vulnerability scanning (read-only)
yokay-spec-reviewer Sonnet Adversarial spec compliance review
yokay-quality-reviewer Sonnet Code quality review (after spec passes)
yokay-spike-runner Sonnet Time-boxed investigations
yokay-test-runner Haiku Test execution with concise output

Why Sub-Agents?

  • Context isolation - Verbose scan output stays separate from main conversation
  • Cost optimization - Haiku agents are 5-10x cheaper for exploration
  • Enforced constraints - Read-only agents can't accidentally modify files
  • Parallel execution - Run multiple investigations simultaneously

Commands like /pokayokay:audit, /pokayokay:security, and /pokayokay:spike automatically delegate to the appropriate agent.

Brainstorm Gate

For ambiguous or under-specified tasks, yokay-brainstormer runs before implementation:

  1. Detects vague descriptions or missing acceptance criteria
  2. Explores codebase for context
  3. Produces clear requirements and technical approach
  4. Requests confirmation before implementation proceeds

This prevents wasted work from misunderstood requirements.

Two-Stage Review

After implementation, two sequential reviewers check the work:

Stage Agent Checks
1 yokay-spec-reviewer Adversarial spec compliance (requirements met? no scope creep?)
2 yokay-quality-reviewer Code quality (well-written and tested?)

Stage 2 only runs if Stage 1 passes. Both must PASS before a task is marked complete.

Hook System

pokayokay includes a guaranteed hook system that executes actions at key lifecycle points via Claude Code's native hooks:

Hook Trigger Actions
pre-session Session starts Verify clean, pre-flight (unattended), recover
pre-task Task starts Check blockers, suggest skills, setup worktree
post-task Task completes Sync, commit, detect spike, capture knowledge
post-story Story completes Test, story integration, audit gate
post-epic Epic completes Audit gate
on-blocker Task blocked Notification
pre-commit Before git commit Lint, check ref sizes
post-session Session ends Sync, session summary, curate memory, session chain

Intelligent Hooks

Beyond lifecycle automation, hooks provide intelligent guidance:

Action Hook Purpose
suggest-skills pre-task Suggests relevant skills based on task keywords
detect-spike post-task Detects uncertainty signals, suggests spike conversion
capture-knowledge post-task Auto-suggests docs for spike/research tasks
audit-gate post-story/epic Checks quality thresholds at boundaries

Hooks are registered through the plugin system and routed by bridge.py. The ohno MCP server provides boundary metadata when tasks complete, enabling automatic detection of story/epic completion.

Use /pokayokay:hooks to view and manage hook configuration.

See HOOKS.md for configuration and customization.

Spike Protocol

For high-uncertainty work:

  1. Time-box: 2-4 hours (max 1 day)
  2. 50% Checkpoint: Assess progress
  3. Mandatory Decision: GO / NO-GO / PIVOT / MORE-INFO
  4. Output: .claude/spikes/[name].md

Documentation

See GUIDE.md for:

  • Command relationships diagram
  • Skill routing patterns
  • Keyword detection
  • Integration with ohno

Development

git clone https://github.com/srstomp/pokayokay.git
claude --plugin-dir ./plugins/pokayokay

Dependencies

  • ohno - Task management via MCP

License

MIT

About

An orchestration plugin for Claude Code that enables reliable autonomous development sessions with configurable checkpoints and task management.

pokayokay.com

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

5 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages