Teddy

Development workflow framework for Claude Code that plans work, decomposes into atomic units, and orchestrates named Agent Teams for coordinated parallel execution.

How It Works

Every unit of work follows a three-phase loop:

PLAN ──▶ APPLY ──▶ UNIFY

1. Plan — Define what to build, decompose into tasks, assign to role-specialized teammates
2. Apply — Spawn Agent Teams via TeamCreate, distribute tasks, execute in parallel worktrees
3. Unify — Reconcile results, merge worktrees, document outcomes

Teddy acts as a senior tech lead: you describe what you want, it plans the work, decomposes it into atomic tasks, and orchestrates a team of agents to execute in parallel.

Install

npx teddy-framework

Choose global (~/.claude/) or local (./.claude/) when prompted. Or specify directly:

npx teddy-framework --global   # available in all projects
npx teddy-framework --local    # scoped to current project

Requires Node.js >= 16.7.0.

Commands

Type /teddy in Claude Code to get started, then use any command:

| Command | Description | |---------|-------------| | /teddy:init | Initialize project with .teddy/ directory | | /teddy:explore | Explore ideas before planning | | /teddy:plan | Create executable plan with teammate assignments | | /teddy:apply | Distribute and execute plan via Agent Teams | | /teddy:amend-plan | Modify active plan mid-execution | | /teddy:unify | Reconcile teammate results and merge | | /teddy:rollback | Revert UNIFY to pre-merge state | | /teddy:status | View team progress and project health | | /teddy:resume | Resume work across sessions | | /teddy:debug | Structured debugging workflow | | /teddy:review | Code review | | /teddy:cleanup | Clean orphaned teams, tasks, and worktrees | | /teddy:map-codebase | Analyze and document existing codebase | | /teddy:flows | Manage skill dependencies with auto-discovery |

Project Structure

When you run /teddy:init, a .teddy/ directory is created in your project:

.teddy/
├── PROJECT.md              # What we're building and why
├── ROADMAP.md              # Milestones and phases
├── STATE.md                # Living state and session continuity
├── phases/
│   └── 01-name/
│       ├── 01-01-PLAN.md   # Executable plan with tasks
│       └── 01-01-SUMMARY.md# Completion documentation
└── codebase/               # Generated by /teddy:map-codebase
    ├── STACK.md            # Languages, frameworks, dependencies
    ├── ARCHITECTURE.md     # Patterns, layers, data flow
    ├── STRUCTURE.md        # Directory layout and conventions
    ├── CONVENTIONS.md      # Code style and patterns
    ├── TESTING.md          # Test framework and practices
    ├── INTEGRATIONS.md     # External services and APIs
    └── CONCERNS.md         # Tech debt and known issues

Key Concepts

Agent Teams

Teddy uses TeamCreate to spawn role-specialized teammates (e.g., backend-dev, frontend-dev, test-eng) that work in parallel via isolated worktrees. Teammates share a task list and communicate directly through SendMessage.

Plans as Prompts

A PLAN.md is not transformed into a prompt — it is the prompt. Each plan contains objectives, acceptance criteria, task assignments, boundaries, and verification steps. Teammates execute directly from it.

Session Continuity

STATE.md tracks current position, active teams, accumulated decisions, and session notes. When you return after a break, /teddy:resume picks up exactly where you left off.

Plan Resilience

Plans can be modified mid-execution with /teddy:amend-plan — pause teammates, update tasks, and resume. If a UNIFY merge goes wrong, /teddy:rollback reverts to the pre-merge state using safety tags created automatically during UNIFY.

Skill Flows

Teddy can auto-discover your custom Claude Code skills and suggest which ones are relevant to your project. Run /teddy:flows to:

1. Discover — Scans ~/.claude/commands/ and reads skill metadata
2. Match — Cross-references skills with your project stack and current phase
3. Confirm — Presents suggestions with confidence levels for your approval

Once configured, skills are:

• Detected during /teddy:plan — suggests relevant skills for each plan
• Verified during /teddy:apply — blocks execution if required skills aren't loaded
• Audited during /teddy:unify — documents gaps for continuous improvement

Codebase Mapping

/teddy:map-codebase spawns 4 parallel Explore agents that analyze your codebase and produce 7 structured documents. These inform planning and onboarding with actual file paths, not vague descriptions.

Framework Files

src/
├── commands/           # Slash command definitions
├── frameworks/         # Core methodology
│   ├── teammate-orchestration.md
│   ├── loop-phases.md
│   ├── plan-format.md
│   ├── quality-principles.md
│   └── skill-flows.md
├── templates/          # Document templates
│   ├── PROJECT.md, ROADMAP.md, STATE.md, PLAN.md, SUMMARY.md, EXPLORATION.md, FLOWS.md
│   └── codebase/       # 7 codebase analysis templates
├── context/            # Runtime session context
└── checklists/         # Quality gates (plan-review, unify-gate)

Changelog

See CHANGELOG.md for a detailed list of changes in each version.

License

MIT