# sammcj/agentic-coding architecture

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

- Interactive diagram: https://gitdiagram.com/sammcj/agentic-coding
- Repository: https://github.com/sammcj/agentic-coding

## Overview

This repository is a personal toolkit for agentic coding: portable skills and guidance, plus Claude Code hooks and Pi extensions/diagnostics. The central user workflow is selecting a skill to extend an agent’s capabilities; several skills also expose standalone validation, transformation, or generation tools. The map highlights sampled runtime branches and README-documented categories. Many skill implementations and root-level rules/templates are not in the supplied tree or excerpts, so those are represented only at the directory level.

Main entry points: [`Skills`](https://github.com/sammcj/agentic-coding/tree/main/Skills) (Composable skills), [`Skills/yue2-music/scripts/run_yue2.py`](https://github.com/sammcj/agentic-coding/blob/main/Skills/yue2-music/scripts/run_yue2.py) (YuE2 workflow), [`Claude/hooks`](https://github.com/sammcj/agentic-coding/tree/main/Claude/hooks) (Claude Code hooks), [`Skills/rewrite-slop/scripts/check_output.py`](https://github.com/sammcj/agentic-coding/blob/main/Skills/rewrite-slop/scripts/check_output.py) (Rewrite checker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_skills["Agent skills"]
  node_skills_catalog["Composable skills"]
end

subgraph group_skill_quality["Skill quality"]
  node_skill_validator["Skill validator<br/>[validate_skill.py]"]
  node_skill_report["Skill report<br/>[render_report.py]"]
  node_rewrite_checker["Rewrite checker<br/>[check_output.py]"]
  node_rewrite_syntax["Sentence checks<br/>[syntax.py]"]
  node_rewrite_report["Rewrite report<br/>[render_report.py]"]
end

subgraph group_media["Media workflows"]
  node_music_runner["YuE2 workflow<br/>[run_yue2.py]"]
  node_abc_tools["ABC score tools<br/>[abc_tools.py]"]
  node_media_skills["Media skills"]
end

subgraph group_integrations["Agent integrations"]
  node_home_assistant["Home Assistant tools"]
  node_claude_hooks["Claude Code hooks"]
  node_compound_approval["Command approval"]
  node_cache_heal["Plugin cache repair"]
end

subgraph group_pi_tools["Pi tools"]
  node_pi_extensions["Pi extensions"]
  node_file_changes["File change tracking<br/>[index.ts]"]
  node_pi_diagnostics["Pi diagnostics"]
  node_capture_proxy["Request capture proxy<br/>[capture-proxy.mjs]"]
end

node_user(("Agent user"))
node_music_model["YuE2 inference"]

node_user -->|"selects skills"| node_skills_catalog
node_skills_catalog -->|"includes validation"| node_skill_validator
node_skills_catalog -->|"includes rewriting checks"| node_rewrite_checker
node_skills_catalog -->|"includes music generation"| node_music_runner
node_skills_catalog -->|"includes integrations"| node_home_assistant
node_skill_report -->|"reads findings"| node_skill_validator
node_rewrite_checker -->|"imports checks"| node_rewrite_syntax
node_rewrite_report -->|"reads findings"| node_rewrite_checker
node_rewrite_report -->|"uses sentence checks"| node_rewrite_syntax
node_music_runner -->|"parses scores"| node_abc_tools
node_music_runner -.->|"runs inference"| node_music_model
node_user -->|"uses capabilities"| node_media_skills
node_user -->|"configures agent tools"| node_claude_hooks
node_claude_hooks -->|"provides command approval"| node_compound_approval
node_claude_hooks -->|"provides cache repair"| node_cache_heal
node_user -.->|"extends Pi"| node_pi_extensions
node_pi_extensions -->|"includes tracking extension"| node_file_changes
node_user -.->|"uses diagnostics"| node_pi_diagnostics
node_pi_diagnostics -->|"includes request capture"| node_capture_proxy

click node_skills_catalog "https://github.com/sammcj/agentic-coding/tree/main/Skills"
click node_skill_validator "https://github.com/sammcj/agentic-coding/blob/main/Skills/skill-creator-primer/scripts/validate_skill.py"
click node_skill_report "https://github.com/sammcj/agentic-coding/blob/main/Skills/skill-creator-primer/scripts/render_report.py"
click node_rewrite_checker "https://github.com/sammcj/agentic-coding/blob/main/Skills/rewrite-slop/scripts/check_output.py"
click node_rewrite_syntax "https://github.com/sammcj/agentic-coding/blob/main/Skills/rewrite-slop/scripts/syntax.py"
click node_rewrite_report "https://github.com/sammcj/agentic-coding/blob/main/Skills/rewrite-slop/scripts/render_report.py"
click node_music_runner "https://github.com/sammcj/agentic-coding/blob/main/Skills/yue2-music/scripts/run_yue2.py"
click node_abc_tools "https://github.com/sammcj/agentic-coding/blob/main/Skills/yue2-music/scripts/abc_tools.py"
click node_media_skills "https://github.com/sammcj/agentic-coding/tree/main/Skills"
click node_home_assistant "https://github.com/sammcj/agentic-coding/tree/main/Skills/home-assistant/scripts"
click node_claude_hooks "https://github.com/sammcj/agentic-coding/tree/main/Claude/hooks"
click node_compound_approval "https://github.com/sammcj/agentic-coding/blob/main/Claude/hooks/approve-compound-commands.go"
click node_cache_heal "https://github.com/sammcj/agentic-coding/blob/main/Claude/hooks/context-mode-cache-heal.mjs"
click node_pi_extensions "https://github.com/sammcj/agentic-coding/tree/main/Pi/extensions"
click node_file_changes "https://github.com/sammcj/agentic-coding/blob/main/Pi/extensions/filechanges/index.ts"
click node_pi_diagnostics "https://github.com/sammcj/agentic-coding/tree/main/Pi/diagnostics"
click node_capture_proxy "https://github.com/sammcj/agentic-coding/blob/main/Pi/diagnostics/capture-proxy.mjs"

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_skills_catalog,node_user toneBlue
class node_skill_validator,node_skill_report,node_rewrite_checker,node_rewrite_syntax,node_rewrite_report toneAmber
class node_music_runner,node_abc_tools,node_media_skills toneMint
class node_home_assistant,node_claude_hooks,node_compound_approval,node_cache_heal toneRose
class node_pi_extensions,node_file_changes,node_pi_diagnostics,node_capture_proxy,node_music_model toneIndigo
```

## Components

### Agent skills

- [Composable skills](https://github.com/sammcj/agentic-coding/tree/main/Skills): `Skills`

### Skill quality

- [Skill validator](https://github.com/sammcj/agentic-coding/blob/main/Skills/skill-creator-primer/scripts/validate_skill.py): `Skills/skill-creator-primer/scripts/validate_skill.py`
- [Skill report](https://github.com/sammcj/agentic-coding/blob/main/Skills/skill-creator-primer/scripts/render_report.py): `Skills/skill-creator-primer/scripts/render_report.py`
- [Rewrite checker](https://github.com/sammcj/agentic-coding/blob/main/Skills/rewrite-slop/scripts/check_output.py): `Skills/rewrite-slop/scripts/check_output.py`
- [Sentence checks](https://github.com/sammcj/agentic-coding/blob/main/Skills/rewrite-slop/scripts/syntax.py): `Skills/rewrite-slop/scripts/syntax.py`
- [Rewrite report](https://github.com/sammcj/agentic-coding/blob/main/Skills/rewrite-slop/scripts/render_report.py): `Skills/rewrite-slop/scripts/render_report.py`

### Media workflows

- [YuE2 workflow](https://github.com/sammcj/agentic-coding/blob/main/Skills/yue2-music/scripts/run_yue2.py): `Skills/yue2-music/scripts/run_yue2.py`
- [ABC score tools](https://github.com/sammcj/agentic-coding/blob/main/Skills/yue2-music/scripts/abc_tools.py): `Skills/yue2-music/scripts/abc_tools.py`
- [Media skills](https://github.com/sammcj/agentic-coding/tree/main/Skills): `Skills`

### Agent integrations

- [Home Assistant tools](https://github.com/sammcj/agentic-coding/tree/main/Skills/home-assistant/scripts): `Skills/home-assistant/scripts`
- [Claude Code hooks](https://github.com/sammcj/agentic-coding/tree/main/Claude/hooks): `Claude/hooks`
- [Command approval](https://github.com/sammcj/agentic-coding/blob/main/Claude/hooks/approve-compound-commands.go): `Claude/hooks/approve-compound-commands.go`
- [Plugin cache repair](https://github.com/sammcj/agentic-coding/blob/main/Claude/hooks/context-mode-cache-heal.mjs): `Claude/hooks/context-mode-cache-heal.mjs`

### Pi tools

- [Pi extensions](https://github.com/sammcj/agentic-coding/tree/main/Pi/extensions): `Pi/extensions`
- [File change tracking](https://github.com/sammcj/agentic-coding/blob/main/Pi/extensions/filechanges/index.ts): `Pi/extensions/filechanges/index.ts`
- [Pi diagnostics](https://github.com/sammcj/agentic-coding/tree/main/Pi/diagnostics): `Pi/diagnostics`
- [Request capture proxy](https://github.com/sammcj/agentic-coding/blob/main/Pi/diagnostics/capture-proxy.mjs): `Pi/diagnostics/capture-proxy.mjs`

### Other components

- **Agent user**
- **YuE2 inference**

## Connections

- Agent user → Composable skills: selects skills (evidence: `README.md`)
- Composable skills → Skill validator: includes validation (evidence: `README.md`)
- Composable skills → Rewrite checker: includes rewriting checks (evidence: `README.md`)
- Composable skills → YuE2 workflow: includes music generation (evidence: `README.md`)
- Composable skills → Home Assistant tools: includes integrations (evidence: `README.md`)
- Skill report → Skill validator: reads findings (evidence: `Skills/skill-creator-primer/scripts/render_report.py`)
- Rewrite checker → Sentence checks: imports checks (evidence: `Skills/rewrite-slop/scripts/check_output.py`)
- Rewrite report → Rewrite checker: reads findings (evidence: `Skills/rewrite-slop/scripts/render_report.py`)
- Rewrite report → Sentence checks: uses sentence checks (evidence: `Skills/rewrite-slop/scripts/render_report.py`)
- YuE2 workflow → ABC score tools: parses scores (evidence: `Skills/yue2-music/scripts/run_yue2.py`)
- YuE2 workflow → YuE2 inference: runs inference
- Agent user → Media skills: uses capabilities (evidence: `README.md`)
- Agent user → Claude Code hooks: configures agent tools (evidence: `README.md`)
- Claude Code hooks → Command approval: provides command approval (evidence: `Claude/hooks/approve-compound-commands.go`)
- Claude Code hooks → Plugin cache repair: provides cache repair (evidence: `Claude/hooks/context-mode-cache-heal.mjs`)
- Agent user → Pi extensions: extends Pi
- Pi extensions → File change tracking: includes tracking extension (evidence: `Pi/extensions/filechanges/index.ts`)
- Agent user → Pi diagnostics: uses diagnostics
- Pi diagnostics → Request capture proxy: includes request capture (evidence: `Pi/diagnostics/capture-proxy.mjs`)
