# shadcn/improve architecture

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

- Interactive diagram: https://gitdiagram.com/shadcn/improve
- Repository: https://github.com/shadcn/improve

## Overview

Improve is an agent skill that audits a codebase and produces implementation plans; it does not implement source changes itself. The main workflow is recon, parallel audit, vetting and prioritization, then plan writing. Its documented branches include focused audits, feature suggestions, plan review, execution by a cheaper agent, reconciliation, and optional GitHub issue publication. The source excerpts were unavailable, so relationships below are limited to those explicitly described in the README; skill internals share the listed skill path.

Main entry points: [`skills/improve/SKILL.md`](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md) (Improve skill)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Audit to plan"]
  node_skill["Improve skill<br/>[SKILL.md]"]
  node_recon["Repository recon<br/>[SKILL.md]"]
  node_audit["Parallel audit<br/>[SKILL.md]"]
  node_vet["Finding vetting<br/>[SKILL.md]"]
  node_prioritize["Prioritization<br/>[SKILL.md]"]
  node_planwrite["Plan writing<br/>[SKILL.md]"]
  node_quick["Quick audit<br/>[SKILL.md]"]
  node_deep["Deep audit<br/>[SKILL.md]"]
  node_focused["Focused audit<br/>[SKILL.md]"]
  node_branch["Branch audit<br/>[SKILL.md]"]
  node_suggestions["Feature suggestions<br/>[SKILL.md]"]
end

subgraph group_operations["Plan operations"]
  node_executor(("Executor agent"))
  node_review["Execution review<br/>[SKILL.md]"]
  node_reconcile["Backlog reconcile<br/>[SKILL.md]"]
  node_reviewplan["Plan critique<br/>[SKILL.md]"]
end

subgraph group_outputs["Plan outputs"]
  node_planfiles["Plan files"]
  node_issues["GitHub issues"]
end

node_user(("User"))

node_user -->|"invokes"| node_skill
node_skill -->|"maps repository"| node_recon
node_skill -->|"fans out"| node_audit
node_skill -->|"rechecks findings"| node_vet
node_skill -->|"orders findings"| node_prioritize
node_user -->|"selects findings"| node_planwrite
node_skill -->|"writes plans"| node_planwrite
node_planwrite -->|"produces"| node_planfiles
node_user -->|"hands off plan"| node_executor
node_executor -->|"returns work"| node_review
node_skill -->|"reviews diff"| node_review
node_user -->|"requests refresh"| node_reconcile
node_skill -->|"verifies backlog"| node_reconcile
node_planwrite -.->|"publishes optionally"| node_issues
node_user -->|"requests mode"| node_quick
node_user -->|"requests mode"| node_deep
node_user -->|"requests category"| node_focused
node_user -->|"requests scope"| node_branch
node_user -->|"requests suggestions"| node_suggestions
node_user -->|"requests critique"| node_reviewplan

click node_skill "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_recon "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_audit "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_vet "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_prioritize "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_planwrite "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_review "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_reconcile "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_quick "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_deep "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_focused "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_branch "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_suggestions "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"
click node_reviewplan "https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md"

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_skill,node_recon,node_audit,node_vet,node_prioritize,node_planwrite,node_quick,node_deep,node_focused,node_branch,node_suggestions,node_user toneBlue
class node_executor,node_review,node_reconcile,node_reviewplan toneAmber
class node_planfiles,node_issues toneMint
```

## Components

### Audit to plan

- [Improve skill](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Repository recon](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Parallel audit](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Finding vetting](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Prioritization](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Plan writing](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Quick audit](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Deep audit](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Focused audit](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Branch audit](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Feature suggestions](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`

### Plan operations

- **Executor agent**
- [Execution review](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Backlog reconcile](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`
- [Plan critique](https://github.com/shadcn/improve/blob/main/skills/improve/SKILL.md): `skills/improve/SKILL.md`

### Plan outputs

- **Plan files**
- **GitHub issues**

### Other components

- **User**

## Connections

- User → Improve skill: invokes (evidence: `README.md`)
- Improve skill → Repository recon: maps repository (evidence: `README.md`)
- Improve skill → Parallel audit: fans out (evidence: `README.md`)
- Improve skill → Finding vetting: rechecks findings (evidence: `README.md`)
- Improve skill → Prioritization: orders findings (evidence: `README.md`)
- User → Plan writing: selects findings (evidence: `README.md`)
- Improve skill → Plan writing: writes plans (evidence: `README.md`)
- Plan writing → Plan files: produces (evidence: `README.md`)
- User → Executor agent: hands off plan (evidence: `README.md`)
- Executor agent → Execution review: returns work (evidence: `README.md`)
- Improve skill → Execution review: reviews diff (evidence: `README.md`)
- User → Backlog reconcile: requests refresh (evidence: `README.md`)
- Improve skill → Backlog reconcile: verifies backlog (evidence: `README.md`)
- Plan writing → GitHub issues: publishes optionally (evidence: `README.md`)
- User → Quick audit: requests mode (evidence: `README.md`)
- User → Deep audit: requests mode (evidence: `README.md`)
- User → Focused audit: requests category (evidence: `README.md`)
- User → Branch audit: requests scope (evidence: `README.md`)
- User → Feature suggestions: requests suggestions (evidence: `README.md`)
- User → Plan critique: requests critique (evidence: `README.md`)