Woog

A personal development toolkit for AI agents covering the full product development lifecycle — product discovery, design, spec-driven engineering, and shipping — plus deep thinking, code quality, and ecosystem patterns.

Quick Start

Install Woog with a single command. It auto-detects your AI harness (Claude Code or OpenCode), configures agents, and sets up session hooks:

# Initialize woog in your project
bunx @vw2231/woog@latest init

# Or install everything including skills
bunx @vw2231/woog@latest init --all

# Non-interactive mode (CI/CD)
bunx @vw2231/woog@latest init --yes

That's it. Your project is now configured for spec-driven development.

What Gets Installed

Woog sets up three things in your project:

1. Skills (35 available across 6 plugins)

Specialized knowledge modules that auto-invoke based on context. Plugins: product, design, spec, oracle, code, engine (Engine-specific extensions). (typescript and python skills ship in the repo but are unregistered/hidden.) Install them via the CLI (--all flag) or separately:

npx skills add vw2231/woog

2. Agent Personas (3 subagents)

Harness-agnostic agent definitions configured with appropriate models:

| Agent | Role | Claude | OpenCode | |-------|------|--------|----------| | Scout | Fast codebase reconnaissance | haiku | deepseek-v4-flash | | Oracle | Strategic thinking, requirements, analysis | opus | kimi-k2.6 | | Architect | DDD, system design, architecture | opus | deepseek-v4-pro |

Agents are generated into .claude/agents/ or .opencode/agents/ with harness-specific model identifiers.

3. Session Hooks

Context injection that runs on every session start, clear, or compact:

• Claude Code: hooks/woog-session-start outputs project context as JSON
• OpenCode: .opencode/plugins/woog.js provides config and transform hooks

4. Task Tracking (optional)

The spec workflow skills support beads for dependency-aware task tracking:

# Install beads (optional but recommended)
npm install -g beads

Why beads? It provides bd ready (finds next unblocked task), bd dep add (dependency management), and bd list (progress tracking) that harness-native todos can't match.

Fallback: If beads isn't installed, skills fall back to the harness's native todo system (TodoWrite for Claude Code, built-in todos for OpenCode).

5. Configuration

Single source of truth in .woog/config.json:

{
  "version": "1.0.0",
  "harness": "claude",
  "skills_source": "vw2231/woog",
  "agents": [
    { "template": "scout", "model": "haiku" },
    { "template": "oracle", "model": "opus" },
    { "template": "architect", "model": "opus" }
  ]
}

CLI Commands

init (default)

Initialize woog in the current project.

bunx @vw2231/woog@latest init [options]

Options:

• --harness <type> - Force harness type (claude or opencode)
• --all - Also install skills via npx skills add
• --yes - Non-interactive mode with default models
• --project - Install skills in project directory (default: global)

Idempotent: Re-running init is safe. It regenerates files without deleting anything unless you switch harnesses.

update

Refresh hooks and agents from the latest templates without touching skills:

bunx @vw2231/woog@latest update

remove

Remove all woog-generated files from the project:

bunx @vw2231/woog@latest remove

Skills remain installed. Run npx skills remove vw2231/woog to remove them separately.

Skills

This repository includes 35 registered skills across 6 plugins, covering the full product development lifecycle from discovery to shipping. (16 typescript-* / python-* skills also ship in the repo but are currently unregistered.)

Installing Skills

If you didn't use --all during init, install skills manually:

# Install all skills
npx skills add vw2231/woog

# Install specific skills
npx skills add vw2231/woog --skill product-discover
npx skills add vw2231/woog --skill design-brief
npx skills add vw2231/woog --skill spec-brainstorm

Skill Types

Skills fall into six categories based on what they do.

Product Workflows (product:*)

Conversational discovery-to-prioritization pipeline. Each writes a markdown artifact and pulls real data from Amplitude, Attention, Linear, Atlassian, and Slack via MCP. Use one question at a time with hard stops between phases.

• product-orchestrator — Routes between product-* skills, enforces hard transitions
• product-discover → docs/discovery/<topic>.md — Problem statement + 2-5 evidence-backed pain points
  • product-discover-segment — Sub-skill: WHO is affected (Amplitude cohorts + Linear)
  • product-discover-pain — Sub-skill: WHAT hurts (Attention calls + Linear + Slack)
  • product-discover-context — Sub-skill: WHY NOW + strategy alignment (Atlassian + Slack)
• product-research → docs/research/<topic>-research.md — Hypothesis validation, JTBD map, verdict (READY / NEEDS MORE / BACK TO DISCOVERY)
• product-requirements → docs/requirements/<topic>-prd.md — Stories with AC, leading + lagging metrics, non-goals, constraints
• product-prioritize → docs/priorities/<topic>-priorities.md — RICE / MoSCoW / hybrid scoring, MVP cut, phased sequence
• oracle-jtbd — Jobs-to-be-done framework as a thinking lens (invoked by discover, research, design-brief)
• oracle-user-empathy — User research heuristics, pain extraction, bias counters (invoked by discover-pain, research, design-brief)

Design (design:*)

Design-system-agnostic principles and prototyping. Works with any design system; pairs with engine:* for design-system-specific lookups.

• design-principles — Universal design principles, decision trees, 8-file reference library (animations, ui-polish, design-rules, component-design, forms-controls, marketing-pages, touch-accessibility, performance)
• design-brief — Bridge between product and design → docs/design-briefs/<topic>-brief.md (user + JTBD + journey with emotional curve + tasks + design success criteria). Loaded by design-prototype before generating options.
• design-prototype — 5-option UI exploration workflow with Designer Toolkit overlay; always loads design-principles and the design brief

Workflow Skills (spec:*)

Process-oriented skills that guide you through structured engineering workflows. Produce artifacts and should be followed step-by-step.

• spec-brainstorm → spec.md — Discovery, requirements, architecture
• spec-plan → plan.json — Break spec into implementable tasks
• spec-implement — Execute tasks with TDD
• spec-finish — Validate, review, prepare for PR
• spec-ship-work — End-to-end shipping: issue + visual + reviewer subagent + branch/commit/push + PR + CI watch loop
• spec-orchestrator — Route to the right skill based on context

Thinking Skills (oracle:*)

Analytical skills that provide patterns, principles, and deep reasoning. Adapt to your specific situation; auto-load when relevant.

• oracle-architect — DDD, hexagonal architecture, component design
• oracle-challenge — Challenge assumptions, validate decisions
• oracle-doubt — Adversarial review of non-trivial decisions
• oracle-grillme — Socratic interrogation of plans against domain model
• oracle-security — Security architecture and threat modeling
• oracle-testing — Stub-driven TDD, layer boundary testing
• oracle-thinkdeep — Extended sequential reasoning for complex problems

oracle-jtbd and oracle-user-empathy ship under the Product plugin (listed above).

Utility Skills (code:*)

Task-specific tools you invoke when you need them.

• code-commit — Generate and validate conventional commits
• code-debug — Systematic debugging workflow
• code-docs — README, API docs, changelog generation
• code-handoff — Compact conversation into handoff document
• code-review — Multi-agent code review with specialized reviewers
• code-subagents — Dispatch patterns for parallel implementation

Engine Extensions (engine:*, opt-in)

Engine-specific layers on top of the generic design:* and spec:* skills. Each extends a base skill with Engine tooling (Atlas design system, Supernova MCP, Linear engine workspace, opsx, nx). Skip these if you're not in an Engine codebase.

• engine-atlas — Atlas tokens + Supernova MCP (extends design-principles)
• engine-prototype — /opsx:prototype launcher, nx dev members, Atlas validation per option (extends design-prototype)
• engine-ship-work — Linear MCP (engine workspace), macOS screencapture, Engine team/project format (extends spec-ship-work)

Skills are auto-invoked based on their description when you work in relevant contexts. No commands needed—just install and AI agents will use them when appropriate.

Bundled but unregistered: typescript-* (8 skills) and python-* (8 skills) ship in the repo under skills/ but are not registered in marketplace.json, so they're hidden from install. Re-add their plugin blocks to marketplace.json to surface them.

How Skills Work

Skills are auto-invoked based on context. When you say "create a spec for user auth", the AI matches this to spec-brainstorm and loads it automatically.

Namespace Philosophy

Skills are organized into six categories based on their role:

| Category | Prefix | Type | Invocation | Output | Flexibility | |----------|--------|------|------------|--------|-------------| | Product | product: | Conversational workflow | User + parent skill | Artifact (docs/) | Follow Q&A discipline | | Design | design: | Knowledge + workflow | Context + user | Guidance + artifact | Adapt to design system | | Workflow | spec: | Process | User/previous skill | Artifact | Follow exactly | | Thinking | oracle: | Analytical | Context-driven | Guidance | Adapt to context | | Utility | code: | Task-specific | User command | Result | Use as needed | | Engine Extensions | engine: | Tool integration | Alongside base skill | Engine-specific behaviour | Engine-only, opt-in |

• Product (product:) — Upstream half of the PDLC: frame, validate, document, prioritize. Conversational Q&A with hard stops between phases; pulls real data via MCP. Includes the JTBD and user-empathy thinking lenses.
• Design (design:) — Universal design principles + brief + UI exploration workflow. Pairs with engine:* for design-system-specific token/component lookups.
• Workflow (spec:) — Engineering pipeline from research → plan → implement → finish → ship. Sequential steps that produce artifacts.
• Thinking (oracle:) — Analytical lenses (architecture, security, sequential reasoning) that auto-load when relevant.
• Utility (code:) — Task-specific tools you invoke directly when needed.
• Engine Extensions (engine:) — Opt-in layer that adds Engine-specific tooling (Atlas, Supernova MCP, Linear engine workspace, opsx) on top of the generic design:* and spec:* skills. Skip if not in an Engine codebase.

Full PDLC Workflow

Woog spans the full product development lifecycle. Each phase produces a discrete artifact that feeds the next.

graph LR
    PD[product-discover] -->|discovery.md| PR[product-research]
    PR -->|research.md| PQ[product-requirements]
    PQ -->|prd.md| PP[product-prioritize]
    PP -->|priorities.md| DB[design-brief]
    DB -->|brief.md| DX[design-prototype]
    DB -->|brief.md| SB[spec-brainstorm]
    DX --> SB
    SB -->|spec.md| SP[spec-plan]
    SP -->|plan.json| SI[spec-implement]
    SI --> SF[spec-finish]
    SF --> SS[spec-ship-work]

    PR -.->|invalidated| PD
    PQ -.->|too big| PR
    PP -.->|wrong scope| PQ
    SP -.->|design flaw| SB
    SI -.->|missing tasks| SP
    SF -.->|bugs found| SI

Standard flow:

1. Discover — Frame the problem with evidence → discovery.md
2. Research — Validate hypotheses against qual + quant → research.md
3. Requirements — Generate PRD (stories, AC, metrics) → prd.md
4. Prioritize — Score, sequence, draw the MVP line → priorities.md
5. Brief — Define user + journey (with emotional curve) + tasks + design success criteria → brief.md
6. Prototype (optional) — 5 UI options grounded in the brief + Designer Toolkit overlay
7. Spec → Plan → Implement → Finish — Engineering pipeline
8. Ship-work — Issue + visual + reviewer + branch + commit + push + PR + CI loop

Iteration is normal. Backflows (dotted lines) are expected when:

• Research invalidates the problem → back to discovery
• Implementation finds missing tasks → update plan
• Validation finds bugs → back to implement

Skips are fine when justified. Skip product-prioritize when there's only one PRD. Skip design-prototype when UX is settled. Surface the skip explicitly so you know what you're trading off.

When to Use Which Skill

| User says | Skill invoked | |------------|---------------| | "What's the actual problem here" / "who are we solving for" | product-discover | | "How many users does this affect" / "size the segment" | product-discover-segment | | "What's the user pain" / "extract pain from calls" | product-discover-pain | | "How does this fit strategy" / "what's the OKR" | product-discover-context | | "Validate the problem" / "synthesize the research" | product-research | | "Write the PRD" / "user stories" / "acceptance criteria" | product-requirements | | "Prioritize this" / "what's MVP" / "RICE this" | product-prioritize | | "Write the design brief" / "who is this for" / "user journey" | design-brief | | "Let's prototype" / "what are some options" / "explore directions" | design-prototype | | "What's the design principle" / "review this UI" | design-principles | | "Create a spec for X" / "what should we build" | spec-brainstorm | | "Write a plan" | spec-plan | | "Implement this" | spec-implement | | "Ship this" / "create a ticket and PR" | spec-ship-work | | "Review this code" | code-review | | "Debug this" | code-debug | | "How should I test this" | oracle-testing | | "What's the architecture" | oracle-architect | | "What job is the user hiring this for" | oracle-jtbd | | "Am I leading the witness in this interview" | oracle-user-empathy |

Development

For local development with Claude Code, use the --plugin-dir flag to load skills directly:

claude --plugin-dir ./woog

Restart Claude Code after making changes to reload skills.

To work on the CLI itself:

# Build the CLI
bun run build

# Test locally
bun ./dist/woog.js init --yes

License

MIT Copyright (c) 2026 Martin Richards