# robertgarcia-ai/skills architecture

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

- Interactive diagram: https://gitdiagram.com/robertgarcia-ai/skills
- Repository: https://github.com/robertgarcia-ai/skills

## Overview

This repository is a library of four Claude Code skills, not a conventional application. Users invoke a skill to produce plans, campaign artifacts, handoffs, or structured intent. The README documents the butterfly-collector campaign stages and word-vomit’s routing outcomes; other internal links are shown only where those descriptions support them. Source inspection was limited to the state validator excerpt, so the skills’ internal procedures are represented at their documented paths rather than inferred from unsampled contents.

Main entry points: [`skills/butterfly-collector/SKILL.md`](https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/SKILL.md) (Campaign Controller), [`skills/word-vomit/SKILL.md`](https://github.com/robertgarcia-ai/skills/blob/main/skills/word-vomit/SKILL.md) (Intent Structurer), [`skills/orchestrator/SKILL.md`](https://github.com/robertgarcia-ai/skills/blob/main/skills/orchestrator/SKILL.md) (Plan Generator), [`skills/handoff/SKILL.md`](https://github.com/robertgarcia-ai/skills/blob/main/skills/handoff/SKILL.md) (Handoff Writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestrator["Orchestration"]
  node_orchestrator_skill["Plan Generator<br/>[SKILL.md]"]
end

subgraph group_butterfly["Bug Campaign"]
  node_campaign_skill["Campaign Controller<br/>[SKILL.md]"]
  node_hunt["Bug Hunt<br/>[hunt.md]"]
  node_execute["Fix Execution<br/>[execute.md]"]
  node_devrun["Dev-Run Bundle<br/>[devrun.md]"]
  node_synthesize["Finding Synthesis<br/>[synthesize.md]"]
  node_campaign_state["Campaign State<br/>[state.md]"]
  node_state_validator["State Validator<br/>[validate_state.py]"]
  node_campaign_templates["Campaign Templates"]
  node_campaign_examples["Campaign Examples"]
end

subgraph group_handoff["Session Handoff"]
  node_handoff_skill["Handoff Writer<br/>[SKILL.md]"]
end

subgraph group_word_vomit["Intent Structuring"]
  node_word_vomit_skill["Intent Structurer<br/>[SKILL.md]"]
  node_word_vomit_refs["Choreography and Examples"]
end

node_user(("User"))
node_execution["Execution Work"]
node_handoff_doc["Handoff Document"]
node_parked_intent["Parked Intent"]

node_user -->|"requests plan"| node_orchestrator_skill
node_orchestrator_skill -->|"produces plan"| node_execution
node_user -->|"starts campaign"| node_campaign_skill
node_campaign_skill -->|"governs phase"| node_hunt
node_campaign_skill -->|"governs phase"| node_execute
node_campaign_skill -->|"generates bundle"| node_devrun
node_campaign_skill -->|"synthesizes findings"| node_synthesize
node_campaign_skill -->|"uses for planning"| node_orchestrator_skill
node_campaign_skill -->|"tracks campaign"| node_campaign_state
node_campaign_templates -.->|"templates artifacts"| node_devrun
node_campaign_examples -->|"illustrates practice"| node_campaign_skill
node_state_validator -->|"validates state"| node_campaign_state
node_user -->|"requests handoff"| node_handoff_skill
node_handoff_skill -->|"produces document"| node_handoff_doc
node_user -->|"provides raw thought"| node_word_vomit_skill
node_word_vomit_skill -.->|"uses references"| node_word_vomit_refs
node_word_vomit_skill -->|"routes to execution"| node_execution
node_word_vomit_skill -->|"routes to handoff"| node_handoff_doc
node_word_vomit_skill -->|"routes to park"| node_parked_intent

click node_orchestrator_skill "https://github.com/robertgarcia-ai/skills/blob/main/skills/orchestrator/SKILL.md"
click node_campaign_skill "https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/SKILL.md"
click node_hunt "https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/references/phases/hunt.md"
click node_execute "https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/references/phases/execute.md"
click node_devrun "https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/references/phases/devrun.md"
click node_synthesize "https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/references/phases/synthesize.md"
click node_campaign_state "https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/references/state.md"
click node_state_validator "https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/scripts/validate_state.py"
click node_campaign_templates "https://github.com/robertgarcia-ai/skills/tree/main/skills/butterfly-collector/references/templates"
click node_campaign_examples "https://github.com/robertgarcia-ai/skills/tree/main/skills/butterfly-collector/references/examples"
click node_handoff_skill "https://github.com/robertgarcia-ai/skills/blob/main/skills/handoff/SKILL.md"
click node_word_vomit_skill "https://github.com/robertgarcia-ai/skills/blob/main/skills/word-vomit/SKILL.md"
click node_word_vomit_refs "https://github.com/robertgarcia-ai/skills/tree/main/skills/word-vomit/references"

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_orchestrator_skill,node_user toneBlue
class node_campaign_skill,node_hunt,node_execute,node_devrun,node_synthesize,node_campaign_state,node_state_validator,node_campaign_templates,node_campaign_examples toneAmber
class node_handoff_skill toneMint
class node_word_vomit_skill,node_word_vomit_refs toneRose
class node_execution,node_handoff_doc,node_parked_intent toneIndigo
```

## Components

### Orchestration

- [Plan Generator](https://github.com/robertgarcia-ai/skills/blob/main/skills/orchestrator/SKILL.md): `skills/orchestrator/SKILL.md`

### Bug Campaign

- [Campaign Controller](https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/SKILL.md): `skills/butterfly-collector/SKILL.md`
- [Bug Hunt](https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/references/phases/hunt.md): `skills/butterfly-collector/references/phases/hunt.md`
- [Fix Execution](https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/references/phases/execute.md): `skills/butterfly-collector/references/phases/execute.md`
- [Dev-Run Bundle](https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/references/phases/devrun.md): `skills/butterfly-collector/references/phases/devrun.md`
- [Finding Synthesis](https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/references/phases/synthesize.md): `skills/butterfly-collector/references/phases/synthesize.md`
- [Campaign State](https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/references/state.md): `skills/butterfly-collector/references/state.md`
- [State Validator](https://github.com/robertgarcia-ai/skills/blob/main/skills/butterfly-collector/scripts/validate_state.py): `skills/butterfly-collector/scripts/validate_state.py`
- [Campaign Templates](https://github.com/robertgarcia-ai/skills/tree/main/skills/butterfly-collector/references/templates): `skills/butterfly-collector/references/templates`
- [Campaign Examples](https://github.com/robertgarcia-ai/skills/tree/main/skills/butterfly-collector/references/examples): `skills/butterfly-collector/references/examples`

### Session Handoff

- [Handoff Writer](https://github.com/robertgarcia-ai/skills/blob/main/skills/handoff/SKILL.md): `skills/handoff/SKILL.md`

### Intent Structuring

- [Intent Structurer](https://github.com/robertgarcia-ai/skills/blob/main/skills/word-vomit/SKILL.md): `skills/word-vomit/SKILL.md`
- [Choreography and Examples](https://github.com/robertgarcia-ai/skills/tree/main/skills/word-vomit/references): `skills/word-vomit/references`

### Other components

- **User**
- **Execution Work**
- **Handoff Document**
- **Parked Intent**

## Connections

- User → Plan Generator: requests plan (evidence: `README.md`)
- Plan Generator → Execution Work: produces plan (evidence: `README.md`)
- User → Campaign Controller: starts campaign (evidence: `README.md`)
- Campaign Controller → Bug Hunt: governs phase (evidence: `README.md`)
- Campaign Controller → Fix Execution: governs phase (evidence: `README.md`)
- Campaign Controller → Dev-Run Bundle: generates bundle (evidence: `README.md`)
- Campaign Controller → Finding Synthesis: synthesizes findings (evidence: `README.md`)
- Campaign Controller → Plan Generator: uses for planning (evidence: `README.md`)
- Campaign Controller → Campaign State: tracks campaign (evidence: `README.md`)
- Campaign Templates → Dev-Run Bundle: templates artifacts
- Campaign Examples → Campaign Controller: illustrates practice (evidence: `README.md`)
- State Validator → Campaign State: validates state (evidence: `skills/butterfly-collector/scripts/validate_state.py`)
- User → Handoff Writer: requests handoff (evidence: `README.md`)
- Handoff Writer → Handoff Document: produces document (evidence: `README.md`)
- User → Intent Structurer: provides raw thought (evidence: `README.md`)
- Intent Structurer → Choreography and Examples: uses references
- Intent Structurer → Execution Work: routes to execution (evidence: `README.md`)
- Intent Structurer → Handoff Document: routes to handoff (evidence: `README.md`)
- Intent Structurer → Parked Intent: routes to park (evidence: `README.md`)
