# sprngr/rubber-duck architecture

> Architecture diagram of the GitHub repository sprngr/rubber-duck, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sprngr/rubber-duck
- Repository: https://github.com/sprngr/rubber-duck

## Overview

Rubber Duck is a human-directed, Socratic assistant operating system for developer work. A developer starts with an agent or routes an intent through quack; policy frames scope and approval before a bounded skill performs work, followed by review and verification. Separate skills cover design, debugging, patching, review, and related tasks; duck-tape preserves session context, while duck-adventure is an optional interactive game. The README documents these capabilities; source excerpts are limited, so links between individual skills and session persistence are not inferred beyond documented routing and hook behavior.

Main entry points: [`src/skills/duck-policy/SKILL.md`](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-policy/SKILL.md) (Scope and approval), [`src/skills/quack`](https://github.com/sprngr/rubber-duck/tree/main/src/skills/quack) (Quack router), [`src/skills/duck-tape/hooks/opencode.plugin.js`](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-tape/hooks/opencode.plugin.js) (Compaction hook), [`src/agents/rubber-duck`](https://github.com/sprngr/rubber-duck/tree/main/src/agents/rubber-duck) (Rubber Duck agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Assistant entry"]
  node_rubberduck["Rubber Duck agent"]
  node_duckling["Duckling subagent"]
  node_quack["Quack router"]
  node_session_hook["Session-start hook"]
end

subgraph group_workflow["Decision workflow"]
  node_policy["Scope and approval<br/>[SKILL.md]"]
  node_adapt["Adaptation<br/>[SKILL.md]"]
end

subgraph group_skills["Developer skills"]
  node_design["Design<br/>[SKILL.md]"]
  node_debug["Debug<br/>[SKILL.md]"]
  node_patch["Patch<br/>[SKILL.md]"]
  node_refactor["Refactor and simplify<br/>[SKILL.md]"]
  node_review["Review and risk<br/>[SKILL.md]"]
  node_triage["Triage and teach<br/>[SKILL.md]"]
  node_other_skills["Other work skills"]
  node_adventure["Duck-adventure game"]
end

subgraph group_context["Session context"]
  node_tape["Duck-tape checkpoint<br/>[SKILL.md]"]
  node_tape_hook["Compaction hook<br/>[opencode.plugin.js]"]
  node_state["Session state files"]
end

node_developer(("Developer"))
node_harness["Agent harness"]

node_developer -->|"starts task"| node_rubberduck
node_developer -->|"routes intent"| node_quack
node_rubberduck -->|"invokes by default"| node_policy
node_quack -->|"delegates work"| node_duckling
node_quack -->|"routes intent"| node_policy
node_policy -->|"requests approval"| node_developer
node_developer -->|"approves scope"| node_policy
node_policy -->|"selects skill"| node_design
node_policy -->|"selects skill"| node_debug
node_policy -->|"selects skill"| node_patch
node_policy -->|"selects skill"| node_refactor
node_policy -->|"selects skill"| node_review
node_policy -->|"selects skill"| node_triage
node_quack -->|"routes intent"| node_other_skills
node_developer -->|"adapts setup"| node_adapt
node_harness -.->|"dispatches session events"| node_session_hook
node_session_hook -.->|"injects directive"| node_harness
node_harness -.->|"dispatches compaction"| node_tape_hook
node_tape_hook -.->|"writes checkpoint"| node_state
node_tape_hook -.->|"reads messages"| node_harness
node_developer -->|"manages context"| node_tape
node_developer -->|"plays game"| node_adventure

click node_rubberduck "https://github.com/sprngr/rubber-duck/tree/main/src/agents/rubber-duck"
click node_duckling "https://github.com/sprngr/rubber-duck/tree/main/src/agents/duckling"
click node_quack "https://github.com/sprngr/rubber-duck/tree/main/src/skills/quack"
click node_policy "https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-policy/SKILL.md"
click node_adapt "https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-adapt/SKILL.md"
click node_design "https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-design/SKILL.md"
click node_debug "https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-debug/SKILL.md"
click node_patch "https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-patch/SKILL.md"
click node_refactor "https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-refactor/SKILL.md"
click node_review "https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-review/SKILL.md"
click node_triage "https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-triage/SKILL.md"
click node_other_skills "https://github.com/sprngr/rubber-duck/tree/main/src/skills"
click node_tape "https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-tape/SKILL.md"
click node_tape_hook "https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-tape/hooks/opencode.plugin.js"
click node_session_hook "https://github.com/sprngr/rubber-duck/blob/main/src/install/hooks/session-start/session-start.opencode.plugin.js"
click node_adventure "https://github.com/sprngr/rubber-duck/tree/main/src/skills/duck-adventure"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rubberduck,node_duckling,node_quack,node_session_hook toneBlue
class node_policy,node_adapt toneAmber
class node_design,node_debug,node_patch,node_refactor,node_review,node_triage,node_other_skills,node_adventure toneMint
class node_tape,node_tape_hook,node_state toneRose
class node_developer,node_harness toneIndigo
```

## Components

### Assistant entry

- [Rubber Duck agent](https://github.com/sprngr/rubber-duck/tree/main/src/agents/rubber-duck): `src/agents/rubber-duck`
- [Duckling subagent](https://github.com/sprngr/rubber-duck/tree/main/src/agents/duckling): `src/agents/duckling`
- [Quack router](https://github.com/sprngr/rubber-duck/tree/main/src/skills/quack): `src/skills/quack`
- [Session-start hook](https://github.com/sprngr/rubber-duck/blob/main/src/install/hooks/session-start/session-start.opencode.plugin.js): `src/install/hooks/session-start/session-start.opencode.plugin.js`

### Decision workflow

- [Scope and approval](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-policy/SKILL.md): `src/skills/duck-policy/SKILL.md`
- [Adaptation](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-adapt/SKILL.md): `src/skills/duck-adapt/SKILL.md`

### Developer skills

- [Design](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-design/SKILL.md): `src/skills/duck-design/SKILL.md`
- [Debug](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-debug/SKILL.md): `src/skills/duck-debug/SKILL.md`
- [Patch](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-patch/SKILL.md): `src/skills/duck-patch/SKILL.md`
- [Refactor and simplify](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-refactor/SKILL.md): `src/skills/duck-refactor/SKILL.md`
- [Review and risk](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-review/SKILL.md): `src/skills/duck-review/SKILL.md`
- [Triage and teach](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-triage/SKILL.md): `src/skills/duck-triage/SKILL.md`
- [Other work skills](https://github.com/sprngr/rubber-duck/tree/main/src/skills): `src/skills`
- [Duck-adventure game](https://github.com/sprngr/rubber-duck/tree/main/src/skills/duck-adventure): `src/skills/duck-adventure`

### Session context

- [Duck-tape checkpoint](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-tape/SKILL.md): `src/skills/duck-tape/SKILL.md`
- [Compaction hook](https://github.com/sprngr/rubber-duck/blob/main/src/skills/duck-tape/hooks/opencode.plugin.js): `src/skills/duck-tape/hooks/opencode.plugin.js`
- **Session state files**

### Other components

- **Developer**
- **Agent harness**

## Connections

- Developer → Rubber Duck agent: starts task
- Developer → Quack router: routes intent
- Rubber Duck agent → Scope and approval: invokes by default
- Quack router → Duckling subagent: delegates work
- Quack router → Scope and approval: routes intent
- Scope and approval → Developer: requests approval
- Developer → Scope and approval: approves scope
- Scope and approval → Design: selects skill
- Scope and approval → Debug: selects skill
- Scope and approval → Patch: selects skill
- Scope and approval → Refactor and simplify: selects skill
- Scope and approval → Review and risk: selects skill
- Scope and approval → Triage and teach: selects skill
- Quack router → Other work skills: routes intent
- Developer → Adaptation: adapts setup
- Agent harness → Session-start hook: dispatches session events
- Session-start hook → Agent harness: injects directive
- Agent harness → Compaction hook: dispatches compaction
- Compaction hook → Session state files: writes checkpoint
- Compaction hook → Agent harness: reads messages
- Developer → Duck-tape checkpoint: manages context
- Developer → Duck-adventure game: plays game