# Teddy

Development workflow framework for [Claude Code](https://docs.anthropic.com/en/docs/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:

```text
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

```bash
npx teddy-framework
```

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

```bash
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:

```text
.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

```text
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](CHANGELOG.md) for a detailed list of changes in each version.

## License

MIT