# burgebj/brag architecture

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

- Interactive diagram: https://gitdiagram.com/burgebj/brag
- Repository: https://github.com/burgebj/brag

## Overview

This repository provides two agent skills for turning a project into a short launch video: the classic `/brag` workflow and the lean `/brag-slim` alternative. The principal workflow inspects the project, plans its story and tone, composes a video brief, then delegates building and rendering to Hyperframes and produces share copy. README and tree support the documented stages and optional voiceover; the skill instructions themselves were not sampled, so internal call-level wiring is shown only where documented.

Main entry points: [`skills/brag/SKILL.md`](https://github.com/burgebj/brag/blob/main/skills/brag/SKILL.md) (/brag skill), [`skills/brag/references/step-3-compose.md`](https://github.com/burgebj/brag/blob/main/skills/brag/references/step-3-compose.md) (Compose brief), [`skills/brag/references/step-4-deliver.md`](https://github.com/burgebj/brag/blob/main/skills/brag/references/step-4-deliver.md) (Deliver outputs), [`skills/brag/references/step-2-plan.md`](https://github.com/burgebj/brag/blob/main/skills/brag/references/step-2-plan.md) (Plan story)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Creative workflow"]
  node_brag["/brag skill<br/>[SKILL.md]"]
  node_inspect["Inspect project<br/>[step-1-inspect.md]"]
  node_plan["Plan story<br/>[step-2-plan.md]"]
  node_compose["Compose brief<br/>[step-3-compose.md]"]
  node_deliver["Deliver outputs<br/>[step-4-deliver.md]"]
  node_tones["Tone guidance<br/>[tones.md]"]
  node_audio["Audio guidance<br/>[audio.md]"]
end

subgraph group_classic["Classic assets"]
  node_assets["Music and SFX"]
  node_cue_data["Bundled cue presets"]
  node_cue_analysis["Music cue analysis"]
end

subgraph group_slim["Slim workflow"]
  node_slim["/brag-slim skill<br/>[SKILL.md]"]
  node_slim_instructions["Slim instructions<br/>[slim.md]"]
end

subgraph group_delivery["Video delivery"]
  node_hyperframes["Hyperframes CLI"]
  node_kokoro["Kokoro narration"]
  node_output["brag-output"]
  node_video["Rendered brag.mp4"]
end

node_user(("Project user"))
node_agent(("Skills agent"))

node_user -->|"requests video"| node_agent
node_agent -->|"invokes skill"| node_brag
node_agent -.->|"invokes alternative"| node_slim
node_brag -->|"inspects project"| node_inspect
node_brag -->|"plans story"| node_plan
node_brag -->|"writes brief"| node_compose
node_brag -->|"prepares outputs"| node_deliver
node_plan -->|"uses guidance"| node_tones
node_compose -->|"uses guidance"| node_audio
node_compose -->|"selects media"| node_assets
node_audio -.->|"may use cues"| node_cue_data
node_cue_analysis -->|"generates presets"| node_cue_data
node_slim -->|"includes instructions"| node_slim_instructions
node_compose -->|"hands off brief"| node_hyperframes
node_hyperframes -->|"builds and renders"| node_video
node_deliver -->|"writes deliverables"| node_output
node_deliver -->|"delivers video"| node_video
node_kokoro -.->|"provides narration"| node_hyperframes

click node_brag "https://github.com/burgebj/brag/blob/main/skills/brag/SKILL.md"
click node_inspect "https://github.com/burgebj/brag/blob/main/skills/brag/references/step-1-inspect.md"
click node_plan "https://github.com/burgebj/brag/blob/main/skills/brag/references/step-2-plan.md"
click node_compose "https://github.com/burgebj/brag/blob/main/skills/brag/references/step-3-compose.md"
click node_deliver "https://github.com/burgebj/brag/blob/main/skills/brag/references/step-4-deliver.md"
click node_tones "https://github.com/burgebj/brag/blob/main/skills/brag/references/tones.md"
click node_audio "https://github.com/burgebj/brag/blob/main/skills/brag/references/audio.md"
click node_assets "https://github.com/burgebj/brag/tree/main/skills/brag/assets"
click node_cue_data "https://github.com/burgebj/brag/tree/main/skills/brag/assets/music/cues"
click node_cue_analysis "https://github.com/burgebj/brag/blob/main/skills/brag/scripts/analyze_music_cues.py"
click node_slim "https://github.com/burgebj/brag/blob/main/skills/brag-slim/SKILL.md"
click node_slim_instructions "https://github.com/burgebj/brag/blob/main/skills/brag/slim.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_brag,node_inspect,node_plan,node_compose,node_deliver,node_tones,node_audio,node_user toneBlue
class node_assets,node_cue_data,node_cue_analysis toneAmber
class node_slim,node_slim_instructions toneMint
class node_hyperframes,node_kokoro,node_output,node_video toneRose
class node_agent toneIndigo
```

## Components

### Creative workflow

- [/brag skill](https://github.com/burgebj/brag/blob/main/skills/brag/SKILL.md): `skills/brag/SKILL.md`
- [Inspect project](https://github.com/burgebj/brag/blob/main/skills/brag/references/step-1-inspect.md): `skills/brag/references/step-1-inspect.md`
- [Plan story](https://github.com/burgebj/brag/blob/main/skills/brag/references/step-2-plan.md): `skills/brag/references/step-2-plan.md`
- [Compose brief](https://github.com/burgebj/brag/blob/main/skills/brag/references/step-3-compose.md): `skills/brag/references/step-3-compose.md`
- [Deliver outputs](https://github.com/burgebj/brag/blob/main/skills/brag/references/step-4-deliver.md): `skills/brag/references/step-4-deliver.md`
- [Tone guidance](https://github.com/burgebj/brag/blob/main/skills/brag/references/tones.md): `skills/brag/references/tones.md`
- [Audio guidance](https://github.com/burgebj/brag/blob/main/skills/brag/references/audio.md): `skills/brag/references/audio.md`

### Classic assets

- [Music and SFX](https://github.com/burgebj/brag/tree/main/skills/brag/assets): `skills/brag/assets`
- [Bundled cue presets](https://github.com/burgebj/brag/tree/main/skills/brag/assets/music/cues): `skills/brag/assets/music/cues`
- [Music cue analysis](https://github.com/burgebj/brag/blob/main/skills/brag/scripts/analyze_music_cues.py): `skills/brag/scripts/analyze_music_cues.py`

### Slim workflow

- [/brag-slim skill](https://github.com/burgebj/brag/blob/main/skills/brag-slim/SKILL.md): `skills/brag-slim/SKILL.md`
- [Slim instructions](https://github.com/burgebj/brag/blob/main/skills/brag/slim.md): `skills/brag/slim.md`

### Video delivery

- **Hyperframes CLI**
- **Kokoro narration**
- **brag-output**
- **Rendered brag.mp4**

### Other components

- **Project user**
- **Skills agent**

## Connections

- Project user → Skills agent: requests video
- Skills agent → /brag skill: invokes skill
- Skills agent → /brag-slim skill: invokes alternative
- /brag skill → Inspect project: inspects project
- /brag skill → Plan story: plans story
- /brag skill → Compose brief: writes brief
- /brag skill → Deliver outputs: prepares outputs
- Plan story → Tone guidance: uses guidance
- Compose brief → Audio guidance: uses guidance
- Compose brief → Music and SFX: selects media
- Audio guidance → Bundled cue presets: may use cues
- Music cue analysis → Bundled cue presets: generates presets
- /brag-slim skill → Slim instructions: includes instructions
- Compose brief → Hyperframes CLI: hands off brief
- Hyperframes CLI → Rendered brag.mp4: builds and renders
- Deliver outputs → brag-output: writes deliverables
- Deliver outputs → Rendered brag.mp4: delivers video
- Kokoro narration → Hyperframes CLI: provides narration