# coleam00/skills architecture

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

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

## Overview

Cole’s AI Skills is a collection of editable agent procedures, with executable Claude Code hooks as a complementary runtime layer. The principal workflow is the README’s ticket loop: prime context, plan, implement, validate, review, commit, and open a PR. Other documented capabilities cover product planning, issue diagnosis, parallel worktrees, skill/rule creation, autonomous factory setup, and agent tools. Skill bodies and hooks/README.md were not sampled, so those subsystems are represented at directory level; hook behavior and its effects are included only where source excerpts show them.

Main entry points: [`.claude/skills/piv-plan-implementation`](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-plan-implementation) (Plan implementation), [`.claude/skills/piv-implement`](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-implement) (Implement), [`.claude/skills/piv-validate`](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-validate) (Validate), [`.claude/skills/piv-review-changes`](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-review-changes) (Review changes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ticket_loop["Ticket workflow"]
  node_prime["Prime context<br/>[prime-codebase]"]
  node_plan_impl["Plan implementation"]
  node_implement["Implement<br/>[piv-implement]"]
  node_validate["Validate<br/>[piv-validate]"]
  node_review["Review changes<br/>[piv-review-changes]"]
  node_commit["Commit<br/>[piv-commit]"]
  node_create_pr["Create PR<br/>[piv-create-pr]"]
  node_full_loop["Run full loop<br/>[piv-run-full-loop]"]
end

subgraph group_planning_context["Planning and context"]
  node_prd["Create PRD<br/>[plan-create-prd]"]
  node_architecture["Plan architecture<br/>[plan-architecture]"]
  node_stories["Create stories"]
  node_slice_epic["Slice epic<br/>[piv-slice-epic]"]
  node_investigate["Investigate issues"]
  node_implement_issue["Implement issue"]
  node_worktrees["Parallel worktrees<br/>[worktree-create]"]
  node_worktree_merge["Merge worktrees<br/>[worktree-merge]"]
end

subgraph group_ai_layer["AI layer building"]
  node_rules["Rules and drift"]
  node_ablation["Ablate AI layer<br/>[ablate-ai-layer]"]
  node_skill_authoring["Author skills<br/>[skills-create]"]
  node_hook_authoring["Create hooks<br/>[hooks-create]"]
  node_process_review["Process review"]
end

subgraph group_tools_autonomy["Tools and autonomy"]
  node_factory["Dark factory<br/>[build-dark-factory]"]
  node_browser["Browser automation<br/>[agent-browser]"]
  node_ast_search["AST search<br/>[ast-grep]"]
  node_screen["Desktop control<br/>[drive-screen]"]
  node_tutor["Setup tutor<br/>[setup-ai-tutor]"]
end

subgraph group_hooks["Runtime hooks"]
  node_session_context["Session context"]
  node_dependency_guard["Dependency guard"]
  node_action_log["Action audit log"]
  node_test_gate["Test stop gate"]
  node_notify["Stop notification<br/>[stop_notify.py]"]
end

node_developer(("Developer"))
node_agent(("Coding agent"))
node_git["Git repository"]

node_developer -->|"selects skill"| node_agent
node_prime -->|"then plan"| node_plan_impl
node_plan_impl -->|"then implement"| node_implement
node_implement -->|"then validate"| node_validate
node_validate -->|"then review"| node_review
node_review -->|"then commit"| node_commit
node_commit -->|"then open PR"| node_create_pr
node_agent -->|"chains workflow"| node_full_loop
node_developer -->|"requests planning"| node_prd
node_developer -->|"requests planning"| node_architecture
node_developer -->|"requests backlog"| node_stories
node_developer -->|"requests slicing"| node_slice_epic
node_developer -->|"reports issue"| node_investigate
node_investigate -->|"informs fix"| node_implement_issue
node_developer -->|"requests parallel work"| node_worktrees
node_worktrees -->|"integrates branches"| node_worktree_merge
node_developer -->|"builds AI layer"| node_rules
node_developer -->|"evaluates rules"| node_ablation
node_developer -->|"authors procedures"| node_skill_authoring
node_developer -->|"authors hooks"| node_hook_authoring
node_developer -->|"reviews process"| node_process_review
node_developer -->|"builds autonomy"| node_factory
node_agent -->|"uses browser"| node_browser
node_agent -->|"searches syntax"| node_ast_search
node_agent -->|"controls desktop"| node_screen
node_developer -->|"sets up sample"| node_tutor
node_git -->|"provides git state"| node_session_context
node_session_context -->|"injects context"| node_agent
node_agent -->|"reads or edits"| node_dependency_guard
node_dependency_guard -->|"blocks or injects"| node_agent
node_agent -->|"records tool event"| node_action_log
node_action_log -->|"writes project log"| node_git
node_agent -->|"attempts to stop"| node_test_gate
node_test_gate -->|"returns test failure"| node_agent
node_agent -->|"finishes turn"| node_notify
node_notify -->|"sends notification"| node_developer

click node_prime "https://github.com/coleam00/skills/tree/main/.claude/skills/prime-codebase"
click node_plan_impl "https://github.com/coleam00/skills/tree/main/.claude/skills/piv-plan-implementation"
click node_implement "https://github.com/coleam00/skills/tree/main/.claude/skills/piv-implement"
click node_validate "https://github.com/coleam00/skills/tree/main/.claude/skills/piv-validate"
click node_review "https://github.com/coleam00/skills/tree/main/.claude/skills/piv-review-changes"
click node_commit "https://github.com/coleam00/skills/tree/main/.claude/skills/piv-commit"
click node_create_pr "https://github.com/coleam00/skills/tree/main/.claude/skills/piv-create-pr"
click node_full_loop "https://github.com/coleam00/skills/tree/main/.claude/skills/piv-run-full-loop"
click node_prd "https://github.com/coleam00/skills/tree/main/.claude/skills/plan-create-prd"
click node_architecture "https://github.com/coleam00/skills/tree/main/.claude/skills/plan-architecture"
click node_stories "https://github.com/coleam00/skills/tree/main/.claude/skills/plan-create-stories"
click node_slice_epic "https://github.com/coleam00/skills/tree/main/.claude/skills/piv-slice-epic"
click node_investigate "https://github.com/coleam00/skills/tree/main/.claude/skills/piv-investigate-issue"
click node_implement_issue "https://github.com/coleam00/skills/tree/main/.claude/skills/piv-implement-issue"
click node_worktrees "https://github.com/coleam00/skills/tree/main/.claude/skills/worktree-create"
click node_worktree_merge "https://github.com/coleam00/skills/tree/main/.claude/skills/worktree-merge"
click node_rules "https://github.com/coleam00/skills/tree/main/.claude/skills/rules-create-global"
click node_ablation "https://github.com/coleam00/skills/tree/main/.claude/skills/ablate-ai-layer"
click node_skill_authoring "https://github.com/coleam00/skills/tree/main/.claude/skills/skills-create"
click node_hook_authoring "https://github.com/coleam00/skills/tree/main/.claude/skills/hooks-create"
click node_process_review "https://github.com/coleam00/skills/tree/main/.claude/skills/system-evolution-review"
click node_factory "https://github.com/coleam00/skills/tree/main/.claude/skills/build-dark-factory"
click node_browser "https://github.com/coleam00/skills/tree/main/.claude/skills/agent-browser"
click node_ast_search "https://github.com/coleam00/skills/tree/main/.claude/skills/ast-grep"
click node_screen "https://github.com/coleam00/skills/tree/main/.claude/skills/drive-screen"
click node_tutor "https://github.com/coleam00/skills/tree/main/.claude/skills/setup-ai-tutor"
click node_session_context "https://github.com/coleam00/skills/blob/main/hooks/session_start_context.py"
click node_dependency_guard "https://github.com/coleam00/skills/blob/main/hooks/pre_tool_use_dependencies.py"
click node_action_log "https://github.com/coleam00/skills/blob/main/hooks/post_tool_use_log.py"
click node_test_gate "https://github.com/coleam00/skills/blob/main/hooks/stop_tests_must_pass.py"
click node_notify "https://github.com/coleam00/skills/blob/main/hooks/stop_notify.py"

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_prime,node_plan_impl,node_implement,node_validate,node_review,node_commit,node_create_pr,node_full_loop toneBlue
class node_prd,node_architecture,node_stories,node_slice_epic,node_investigate,node_implement_issue,node_worktrees,node_worktree_merge toneAmber
class node_rules,node_ablation,node_skill_authoring,node_hook_authoring,node_process_review toneMint
class node_factory,node_browser,node_ast_search,node_screen,node_tutor toneRose
class node_session_context,node_dependency_guard,node_action_log,node_test_gate,node_notify,node_developer,node_agent,node_git toneIndigo
```

## Components

### Ticket workflow

- [Prime context](https://github.com/coleam00/skills/tree/main/.claude/skills/prime-codebase): `.claude/skills/prime-codebase`
- [Plan implementation](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-plan-implementation): `.claude/skills/piv-plan-implementation`
- [Implement](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-implement): `.claude/skills/piv-implement`
- [Validate](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-validate): `.claude/skills/piv-validate`
- [Review changes](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-review-changes): `.claude/skills/piv-review-changes`
- [Commit](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-commit): `.claude/skills/piv-commit`
- [Create PR](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-create-pr): `.claude/skills/piv-create-pr`
- [Run full loop](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-run-full-loop): `.claude/skills/piv-run-full-loop`

### Planning and context

- [Create PRD](https://github.com/coleam00/skills/tree/main/.claude/skills/plan-create-prd): `.claude/skills/plan-create-prd`
- [Plan architecture](https://github.com/coleam00/skills/tree/main/.claude/skills/plan-architecture): `.claude/skills/plan-architecture`
- [Create stories](https://github.com/coleam00/skills/tree/main/.claude/skills/plan-create-stories): `.claude/skills/plan-create-stories`
- [Slice epic](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-slice-epic): `.claude/skills/piv-slice-epic`
- [Investigate issues](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-investigate-issue): `.claude/skills/piv-investigate-issue`
- [Implement issue](https://github.com/coleam00/skills/tree/main/.claude/skills/piv-implement-issue): `.claude/skills/piv-implement-issue`
- [Parallel worktrees](https://github.com/coleam00/skills/tree/main/.claude/skills/worktree-create): `.claude/skills/worktree-create`
- [Merge worktrees](https://github.com/coleam00/skills/tree/main/.claude/skills/worktree-merge): `.claude/skills/worktree-merge`

### AI layer building

- [Rules and drift](https://github.com/coleam00/skills/tree/main/.claude/skills/rules-create-global): `.claude/skills/rules-create-global`
- [Ablate AI layer](https://github.com/coleam00/skills/tree/main/.claude/skills/ablate-ai-layer): `.claude/skills/ablate-ai-layer`
- [Author skills](https://github.com/coleam00/skills/tree/main/.claude/skills/skills-create): `.claude/skills/skills-create`
- [Create hooks](https://github.com/coleam00/skills/tree/main/.claude/skills/hooks-create): `.claude/skills/hooks-create`
- [Process review](https://github.com/coleam00/skills/tree/main/.claude/skills/system-evolution-review): `.claude/skills/system-evolution-review`

### Tools and autonomy

- [Dark factory](https://github.com/coleam00/skills/tree/main/.claude/skills/build-dark-factory): `.claude/skills/build-dark-factory`
- [Browser automation](https://github.com/coleam00/skills/tree/main/.claude/skills/agent-browser): `.claude/skills/agent-browser`
- [AST search](https://github.com/coleam00/skills/tree/main/.claude/skills/ast-grep): `.claude/skills/ast-grep`
- [Desktop control](https://github.com/coleam00/skills/tree/main/.claude/skills/drive-screen): `.claude/skills/drive-screen`
- [Setup tutor](https://github.com/coleam00/skills/tree/main/.claude/skills/setup-ai-tutor): `.claude/skills/setup-ai-tutor`

### Runtime hooks

- [Session context](https://github.com/coleam00/skills/blob/main/hooks/session_start_context.py): `hooks/session_start_context.py`
- [Dependency guard](https://github.com/coleam00/skills/blob/main/hooks/pre_tool_use_dependencies.py): `hooks/pre_tool_use_dependencies.py`
- [Action audit log](https://github.com/coleam00/skills/blob/main/hooks/post_tool_use_log.py): `hooks/post_tool_use_log.py`
- [Test stop gate](https://github.com/coleam00/skills/blob/main/hooks/stop_tests_must_pass.py): `hooks/stop_tests_must_pass.py`
- [Stop notification](https://github.com/coleam00/skills/blob/main/hooks/stop_notify.py): `hooks/stop_notify.py`

### Other components

- **Developer**
- **Coding agent**
- **Git repository**

## Connections

- Developer → Coding agent: selects skill (evidence: `README.md`)
- Prime context → Plan implementation: then plan (evidence: `README.md`)
- Plan implementation → Implement: then implement (evidence: `README.md`)
- Implement → Validate: then validate (evidence: `README.md`)
- Validate → Review changes: then review (evidence: `README.md`)
- Review changes → Commit: then commit (evidence: `README.md`)
- Commit → Create PR: then open PR (evidence: `README.md`)
- Coding agent → Run full loop: chains workflow (evidence: `README.md`)
- Developer → Create PRD: requests planning (evidence: `README.md`)
- Developer → Plan architecture: requests planning (evidence: `README.md`)
- Developer → Create stories: requests backlog (evidence: `README.md`)
- Developer → Slice epic: requests slicing (evidence: `README.md`)
- Developer → Investigate issues: reports issue (evidence: `README.md`)
- Investigate issues → Implement issue: informs fix (evidence: `README.md`)
- Developer → Parallel worktrees: requests parallel work (evidence: `README.md`)
- Parallel worktrees → Merge worktrees: integrates branches (evidence: `README.md`)
- Developer → Rules and drift: builds AI layer (evidence: `README.md`)
- Developer → Ablate AI layer: evaluates rules (evidence: `README.md`)
- Developer → Author skills: authors procedures (evidence: `README.md`)
- Developer → Create hooks: authors hooks (evidence: `README.md`)
- Developer → Process review: reviews process (evidence: `README.md`)
- Developer → Dark factory: builds autonomy (evidence: `README.md`)
- Coding agent → Browser automation: uses browser (evidence: `README.md`)
- Coding agent → AST search: searches syntax (evidence: `README.md`)
- Coding agent → Desktop control: controls desktop (evidence: `README.md`)
- Developer → Setup tutor: sets up sample (evidence: `README.md`)
- Git repository → Session context: provides git state (evidence: `hooks/session_start_context.py`)
- Session context → Coding agent: injects context (evidence: `hooks/session_start_context.py`)
- Coding agent → Dependency guard: reads or edits (evidence: `hooks/pre_tool_use_dependencies.py`)
- Dependency guard → Coding agent: blocks or injects (evidence: `hooks/pre_tool_use_dependencies.py`)
- Coding agent → Action audit log: records tool event (evidence: `hooks/post_tool_use_log.py`)
- Action audit log → Git repository: writes project log (evidence: `hooks/post_tool_use_log.py`)
- Coding agent → Test stop gate: attempts to stop (evidence: `hooks/stop_tests_must_pass.py`)
- Test stop gate → Coding agent: returns test failure (evidence: `hooks/stop_tests_must_pass.py`)
- Coding agent → Stop notification: finishes turn (evidence: `hooks/stop_notify.py`)
- Stop notification → Developer: sends notification (evidence: `hooks/stop_notify.py`)