Wrangler

Wrangler is a Claude Code plugin that provides project governance, systematic workflows, and development tooling for AI-assisted software development. It ensures alignment between developers and AI agents through constitutional principles, tracked specifications, proven skill patterns, and automated quality enforcement.

What Wrangler Does

• Skills Library -- 40 proven workflow patterns covering TDD, debugging, code review, governance, and more
• MCP Server -- 18 tools for issue tracking, session orchestration, and workspace management
• Workflow Engine -- Automated spec-to-PR orchestration with phase-based execution and TDD enforcement
• Git Hooks -- Pre-commit and pre-push testing and quality gates
• Project Governance -- Constitution, roadmap, specifications, and issue tracking

Quick Start

Install Wrangler as a Claude Code plugin, then verify the installation:

/wrangler:help

Initialize the .wrangler/ workspace in your project:

/wrangler:init-workspace

Explore available commands and skills:

/wrangler:sitrep
/wrangler:issues

Skills Library

Skills are proven, reusable workflow patterns that Claude Code discovers and activates automatically when relevant to a task. When a skill exists for your current work, it is mandatory -- not optional.

40 skills organized across these areas:

Category	Skills	Examples
Testing	3	TDD enforcement, test execution, anti-pattern detection
Debugging	3	Systematic debugging, root cause tracing, verification
Collaboration	7	Brainstorming, code review, implementation, parallel agents
Git Workflows	6	Worktrees, branch management, hooks setup
Issue Management	3	Issue creation, specifications, idea capture
Governance	8	Constitution, roadmap, metrics, alignment checks
Frontend	4	Design, E2E testing, visual regression, accessibility
Code Analysis	5	Code location, pattern finding, research
System	3	Wrangler usage, self-update, status reporting
Meta	4	Skill authoring, testing, sharing, file organization

See docs/skill-invocation-patterns.md for task-to-skill mapping.

MCP Server

The built-in MCP server provides markdown-based tracking for issues, specifications, and workflow sessions. All data is stored as markdown files with YAML frontmatter in the .wrangler/ directory and version-controlled with git.

Issue Management (11 tools)

issues_create, issues_list, issues_search, issues_get, issues_update, issues_delete, issues_labels, issues_metadata, issues_projects, issues_mark_complete, issues_all_complete

Session Orchestration (6 tools)

session_start, session_phase, session_checkpoint, session_complete, session_get, session_status

Workspace Management (1 tool)

init_workspace

Issues and specifications are stored as {counter}-{slug}.md files (e.g., 000001-add-auth.md) with structured frontmatter for status, priority, labels, assignee, and project metadata.

See docs/mcp-usage.md for the complete tools reference.

Workflow Engine

The workflow engine (workflows/engine/) orchestrates complex spec-to-implementation workflows using the Claude Agent SDK. It provides deterministic, phase-based execution with built-in quality gates.

• Spec-implementation workflow -- Takes a specification and drives it through plan, execute, verify, and publish phases
• Code-review workflow -- Automated review with structured feedback
• Phase-based execution -- Each phase has defined entry/exit criteria
• Session tracking -- Checkpoints enable pause, resume, and recovery
• TDD enforcement -- Tests must pass before phase transitions

The engine is actively developed with 532 tests. See workflows/engine/ for details.

Slash Commands

14 commands that trigger specific workflows:

Command	Purpose
/wrangler:implement	Implement from specs, plans, or issues
/wrangler:run-tests	Run tests and fix failures
/wrangler:commit-push-pr	Commit, push, and create PR
/wrangler:write-plan	Create an implementation plan
/wrangler:generate-plan-for-spec	Break a specification into issues
/wrangler:issues	Show issue and specification status
/wrangler:idea	Capture a new idea
/wrangler:audit-session	Audit session workflow adherence
/wrangler:init-workspace	Initialize .wrangler/ workspace
/wrangler:sitrep	Situational report on project state
/wrangler:help	Documentation and help
/wrangler:setup-git-hooks	Configure git hooks
/wrangler:update-git-hooks	Update hook configuration
/wrangler:update-yourself	Update wrangler plugin

See docs/slash-commands.md for detailed usage.

Project Governance

Wrangler implements a three-tier governance framework:

1. Constitution (.wrangler/CONSTITUTION.md) -- Core design principles that guide all development decisions. Immutable unless formally amended.
2. Roadmap (.wrangler/ROADMAP.md) -- Strategic planning with phased execution milestones.
3. Specifications and Issues -- Tactical execution. Specifications define planned work; issues track implementation tasks.

The governance system includes automated verification, constitutional alignment checks, and metric tracking. Run /wrangler:init-workspace to initialize governance files for a new project.

See docs/governance.md for the full governance guide.

Git Hooks

Automated testing and code quality enforcement through git hooks:

• Pre-commit -- Runs formatter, linter, and unit tests before each commit
• Pre-push -- Runs full test suite before pushing to protected branches
• Commit-msg -- Validates commit message format (optional)

TDD-aware: hooks can be bypassed during the RED phase when failing tests are expected. Run /wrangler:setup-git-hooks to configure.

See docs/git-hooks.md for details.

Directory Structure

wrangler/
├── skills/                     # 40 workflow skills
├── commands/                   # 14 slash commands
├── mcp/                        # MCP server (TypeScript)
│   ├── tools/
│   │   ├── issues/             # 11 issue management tools
│   │   ├── session/            # 6 session orchestration tools
│   │   └── workspace/          # 1 workspace management tool
│   ├── providers/              # Storage providers (markdown)
│   ├── types/                  # TypeScript types and schemas
│   └── __tests__/              # MCP test suite
├── workflows/
│   └── engine/                 # Workflow engine (Claude Agent SDK)
│       ├── src/                # Engine source
│       └── __tests__/          # Engine test suite (532 tests)
├── hooks/                      # Session hooks
├── docs/                       # Documentation
├── .claude-plugin/             # Plugin configuration
└── .wrangler/                  # Workspace (per-project)
    ├── CONSTITUTION.md         # Design principles
    ├── ROADMAP.md              # Strategic roadmap
    ├── issues/                 # Issue tracking
    ├── specifications/         # Feature specifications
    ├── ideas/                  # Ideas and proposals
    ├── plans/                  # Implementation plans
    ├── memos/                  # Reference material, RCAs
    ├── memory/                 # Persistent agent memory
    ├── docs/                   # Generated governance docs
    ├── config/                 # Runtime configuration
    ├── orchestration/          # Workflow orchestration data
    ├── cache/                  # Runtime cache (gitignored)
    └── logs/                   # Runtime logs (gitignored)

Documentation

Document	Description
docs/mcp-usage.md	Complete MCP tools reference
docs/governance.md	Project governance framework
docs/workflows.md	Development workflows (TDD, verification, code review)
docs/slash-commands.md	Slash commands reference
docs/skill-invocation-patterns.md	Task-to-skill mapping
docs/session-hooks.md	Session hooks and state management
docs/git-hooks.md	Git hooks enforcement framework
docs/versioning.md	Versioning and updates
docs/verification-requirements.md	Evidence requirements for claims
docs/workflow-patterns.md	Multi-agent workflow patterns

Development

MCP Server

npm run build:mcp              # Build
npm run test:mcp               # Run tests
npm run watch:mcp              # Watch mode

Workflow Engine

cd workflows/engine
npm run build                  # Build
npm test                       # Run tests
npm run test:coverage          # Coverage report

Requirements

• Claude Code with plugin support
• Git repository
• Node.js 20+

License

MIT