# pbierkortte/ai-runbook architecture

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

- Interactive diagram: https://gitdiagram.com/pbierkortte/ai-runbook
- Repository: https://github.com/pbierkortte/ai-runbook

## Overview

1. **What this repo is**
   - This is not a product app; it is a **dotfiles-style AI operating environment**.
   - The repository’s main job is to define, install, and keep synchronized a set of **agent behaviors, skills, prompts, rules, and persona modules** so they can be reused across tools and workspaces.

2. **Primary architectural boundary**
   - The repo is organized around a **source-of-truth vs. generated runtime state** split.
   - Human-edited markdown files define the behavior; scripts then **hydrate** those definitions into runtime-facing files like `AGENTS.md` and manifests.
   - Before commit, generated content is often **dehydrated** back to minimal placeholders so the repo stays diff-clean while runtime can regenerate the full context.

3. **Top-level subsystems**
   - **`skills/`**: reusable task-specific capabilities, each with a `SKILL.md` entry and sometimes supporting files or scripts.
   - **`cores/`**: persona/identity modules; the README describes these as the “C/O/R/E/S” framework and the tree shows both `spectrum` and `extras` variants.
   - **`rules/`** and **`legacy_rules/`**: policy-like instructions that can be staged into agent contexts.
   - **`docs/`**: operational documentation for the conventions and bootstrapping flow.
   - **`script/`**: the orchestration layer that installs tools, wires shell integration, and generates agent-visible artifacts.
   - **`tools/`**: standalone prompt assets for one-off workflows such as job search, writing, and LLM utilities.

4. **How agent context is assembled**
   - The repo uses **markdown heading structure** and **file placement** as configuration.
   - `AGENTS.md` files act as directory-level indexes that supported IDEs and agents can read automatically.
   - The repo root `AGENTS.md` is both a landing page and a generated table of contents, while nested `AGENTS.md` files are hydrated in subdirectories to expose local context.

5. **Rule system**
   - Rules are stored as `RULE.md` files under scoped directories such as `rules/git/RULE.md` and `rules/house/RULE.md`.
   - The README describes a staging step that collects these rules into temporary, excluded files before hydration.
   - This makes rules behave like **directory-scoped policy overlays** that are injected into agent context without polluting normal project commits.

6. **Skills subsystem**
   - `skills/` is the largest functional surface area and represents the repo’s reusable capability library.
   - Each skill is a self-contained prompt bundle, usually centered on `SKILL.md`, with some skills containing helper scripts or bundled agent personas.
   - Examples include transcription, docs consistency, repo-to-prompt conversion, prompt/meta-prompt utilities, and job-search automation prompts.
   - The repo’s installation/update flow is designed so these skills can be installed into other environments via OpenSkills.

7. **Cores / personas subsystem**
   - `cores/` contains the persona or role definitions that shape how an AI agent behaves.
   - The `spectrum` set maps to named roles like architect, engineer, executor, sentinel, steward, etc., while `extras` adds additional variants.
   - Architecturally, these are not tools; they are **behavioral lenses** used to keep agent responses coherent and role-specific.

8. **Operational scripts and lifecycle**
   - `script/` is the execution layer for bootstrapping and maintenance.
   - The scripts cover environment setup (`bootstrap`, `configure-*`, `wire-shell`), agent/skill linkage (`hydrate-*`, `dehydrate-*`, `link-*`, `unlink-*`), and repository hygiene (`refresh-docs`, `rebuild-manifest`, `run-ci`).
   - This makes the repo function like an **infrastructure-as-code system for AI workspace behavior**.

9. **Documentation and generated indexes**
   - `docs/` explains the conventions: heading format, rule injection, Claude Code autoloading, Codespaces auth, dotfiles opt-in, Git/Python config, and the spectrum model.
   - Root files such as `MANIFEST.md` and the docs manifest files act as catalog outputs, keeping the repo navigable for both humans and agents.
   - The structure suggests documentation is not just explanatory; it is also part of the discovery mechanism for the agent system.

10. **Tooling and external integration points**
   - The repo integrates with **GitHub Codespaces** as a dotfiles repository and uses environment variables like `DOTFILES_ENABLE` and agent-tool-specific flags to enable installs.
   - The README references support for tools such as Claude Code, Cline, Kilo, OpenRouter, and Anthropic auth flows, but these are optional integration endpoints rather than core runtime dependencies.
   - A GitHub Actions workflow (`.github/workflows/run-ci.yml`) provides repository-level validation for this configuration system.

11. **Data flow at a glance**
   - A human edits markdown definitions in `skills/`, `cores/`, `rules/`, and `docs/`.
   - Scripts stage rules, hydrate agent indexes, and rebuild manifests.
   - The resulting generated files are consumed by editors, agent tools, and Codespaces bootstrap.
   - Before commit, dehydration removes generated bulk so the repo remains maintainable while still being able to regenerate the full runtime view.

12. **How to diagram it**
   - Model this repo as a **configuration/content pipeline**, not an application server.
   - The key boxes are: source markdown definitions, script-driven generation, runtime agent context files, and optional tool integrations.
   - The main architecture question is not “what request is served?” but “how does the repo turn markdown conventions into agent behavior?”

Main entry points: [`script`](https://github.com/pbierkortte/ai-runbook/tree/master/script) (Scripts), [`script/hydrate-agents`](https://github.com/pbierkortte/ai-runbook/tree/master/script/hydrate-agents) (Hydrate agents), [`README.md`](https://github.com/pbierkortte/ai-runbook/blob/master/README.md) (README), [`cores`](https://github.com/pbierkortte/ai-runbook/tree/master/cores) (Cores)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source definitions"]
  node_rules_hub["Rules<br/>policy overlays"]
  node_legacy_rules_hub["Legacy rules<br/>archived policies"]
  node_tools_hub["Tools<br/>prompt assets"]
end

subgraph group_library["Capabilities library"]
  node_skills_hub["Skills<br/>skill library"]
  node_cores_hub["Cores<br/>persona library"]
  node_spectrum_core["Spectrum<br/>role set"]
  node_extras_core["Extras<br/>role variants"]
end

subgraph group_runtime["Generation and runtime"]
  node_agents_root["Root AGENTS<br/>agent index<br/>[AGENTS.md]"]
  node_manifest_root["Root manifest<br/>catalog<br/>[MANIFEST.md]"]
  node_script_hub["Scripts<br/>orchestration"]
  node_stage_rules["Stage rules<br/>script"]
  node_hydrate_agents["Hydrate agents<br/>script"]
  node_dehydrate_agents["Dehydrate agents<br/>script"]
  node_rebuild_manifest["Rebuild manifest<br/>script"]
  node_bootstrap["Bootstrap<br/>script"]
  node_install_skills["Install skills<br/>script"]
  node_skills_manifest["Skills manifest<br/>agent manifest"]
end

subgraph group_docs["Docs and integrations"]
  node_readme["README<br/>entry doc<br/>[README.md]"]
  node_docs_hub["Docs"]
  node_install_tools["Tool installers<br/>integration scripts"]
  node_ci["Run CI<br/>validation workflow<br/>[run-ci.yml]"]
  node_docs_manifest["Docs manifest<br/>doc index<br/>[MANIFEST.md]"]
  node_docs_agents["Docs AGENTS<br/>agent index<br/>[AGENTS.md]"]
end

node_readme -->|"explains setup"| node_script_hub
node_readme -->|"describes"| node_skills_hub
node_readme -->|"describes"| node_cores_hub
node_readme -->|"describes"| node_rules_hub
node_rules_hub -->|"staged by"| node_stage_rules
node_stage_rules -->|"feeds"| node_hydrate_agents
node_skills_hub -->|"installed by"| node_install_skills
node_cores_hub -->|"influences"| node_hydrate_agents
node_spectrum_core -->|"subset of"| node_cores_hub
node_extras_core -->|"extends"| node_cores_hub
node_hydrate_agents -->|"generates"| node_agents_root
node_hydrate_agents -->|"hydrates"| node_docs_agents
node_dehydrate_agents -->|"shrinks"| node_agents_root
node_rebuild_manifest -->|"generates"| node_manifest_root
node_rebuild_manifest -->|"generates"| node_docs_manifest
node_bootstrap -->|"orchestrates"| node_script_hub
node_bootstrap -->|"optionally installs"| node_install_tools
node_ci -->|"validates"| node_script_hub
node_docs_hub -->|"documents"| node_docs_agents
node_docs_hub -->|"documents"| node_docs_manifest
node_tools_hub -.->|"consumed by"| node_ci
node_skills_hub -->|"publishes"| node_skills_manifest
node_script_hub -->|"builds"| node_skills_manifest
node_script_hub -->|"contains"| node_hydrate_agents
node_script_hub -->|"contains"| node_dehydrate_agents
node_script_hub -->|"contains"| node_rebuild_manifest
node_docs_hub -->|"covered by"| node_ci

click node_readme "https://github.com/pbierkortte/ai-runbook/blob/master/README.md"
click node_agents_root "https://github.com/pbierkortte/ai-runbook/blob/master/AGENTS.md"
click node_manifest_root "https://github.com/pbierkortte/ai-runbook/blob/master/MANIFEST.md"
click node_skills_hub "https://github.com/pbierkortte/ai-runbook/tree/master/skills"
click node_cores_hub "https://github.com/pbierkortte/ai-runbook/tree/master/cores"
click node_rules_hub "https://github.com/pbierkortte/ai-runbook/tree/master/rules"
click node_legacy_rules_hub "https://github.com/pbierkortte/ai-runbook/tree/master/legacy_rules"
click node_docs_hub "https://github.com/pbierkortte/ai-runbook/tree/master/docs"
click node_tools_hub "https://github.com/pbierkortte/ai-runbook/tree/master/tools"
click node_script_hub "https://github.com/pbierkortte/ai-runbook/tree/master/script"
click node_stage_rules "https://github.com/pbierkortte/ai-runbook/tree/master/script/stage-rules"
click node_hydrate_agents "https://github.com/pbierkortte/ai-runbook/tree/master/script/hydrate-agents"
click node_dehydrate_agents "https://github.com/pbierkortte/ai-runbook/tree/master/script/dehydrate-agents"
click node_rebuild_manifest "https://github.com/pbierkortte/ai-runbook/tree/master/script/rebuild-manifest"
click node_bootstrap "https://github.com/pbierkortte/ai-runbook/tree/master/script/bootstrap"
click node_install_skills "https://github.com/pbierkortte/ai-runbook/tree/master/script/install-skills"
click node_install_tools "https://github.com/pbierkortte/ai-runbook/tree/master/script/install-claude"
click node_ci "https://github.com/pbierkortte/ai-runbook/blob/master/.github/workflows/run-ci.yml"
click node_skills_manifest "https://github.com/pbierkortte/ai-runbook/blob/master/agents/openskills-manifest.yml"
click node_docs_manifest "https://github.com/pbierkortte/ai-runbook/blob/master/docs/MANIFEST.md"
click node_docs_agents "https://github.com/pbierkortte/ai-runbook/blob/master/docs/AGENTS.md"
click node_spectrum_core "https://github.com/pbierkortte/ai-runbook/tree/master/cores/spectrum"
click node_extras_core "https://github.com/pbierkortte/ai-runbook/tree/master/cores/extras"

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_rules_hub,node_legacy_rules_hub,node_tools_hub toneBlue
class node_skills_hub,node_cores_hub,node_spectrum_core,node_extras_core toneAmber
class node_agents_root,node_manifest_root,node_script_hub,node_stage_rules,node_hydrate_agents,node_dehydrate_agents,node_rebuild_manifest,node_bootstrap,node_install_skills,node_skills_manifest toneMint
class node_readme,node_docs_hub,node_install_tools,node_ci,node_docs_manifest,node_docs_agents toneRose
```

## Components

### Source definitions

Human-edited markdown sources that define behavior and policy

- [Rules](https://github.com/pbierkortte/ai-runbook/tree/master/rules): policy overlays · Scoped rule files staged into agent context · `rules`
- [Legacy rules](https://github.com/pbierkortte/ai-runbook/tree/master/legacy_rules): archived policies · Older rule definitions kept for compatibility · `legacy_rules`
- [Tools](https://github.com/pbierkortte/ai-runbook/tree/master/tools): prompt assets · Standalone workflow prompts and templates · `tools`

### Capabilities library

Reusable skills and persona modules

- [Skills](https://github.com/pbierkortte/ai-runbook/tree/master/skills): skill library · Reusable task bundles centered on SKILL.md · `skills`
- [Cores](https://github.com/pbierkortte/ai-runbook/tree/master/cores): persona library · Behavioral role definitions in spectrum and extras · `cores`
- [Spectrum](https://github.com/pbierkortte/ai-runbook/tree/master/cores/spectrum): role set · Primary persona set: architect, engineer, executor, sentinel, steward · `cores/spectrum`
- [Extras](https://github.com/pbierkortte/ai-runbook/tree/master/cores/extras): role variants · Additional persona variants beyond spectrum · `cores/extras`

### Generation and runtime

Scripts and generated indexes that assemble agent context

- [Root AGENTS](https://github.com/pbierkortte/ai-runbook/blob/master/AGENTS.md): agent index · Top-level agent-facing table of contents · `AGENTS.md`
- [Root manifest](https://github.com/pbierkortte/ai-runbook/blob/master/MANIFEST.md): catalog · Repository catalog output for discovery · `MANIFEST.md`
- [Scripts](https://github.com/pbierkortte/ai-runbook/tree/master/script): orchestration · Bootstrap, hydration, staging, and maintenance scripts · `script`
- [Stage rules](https://github.com/pbierkortte/ai-runbook/tree/master/script/stage-rules): script · Collects scoped rules for hydration · `script/stage-rules`
- [Hydrate agents](https://github.com/pbierkortte/ai-runbook/tree/master/script/hydrate-agents): script · Builds AGENTS.md context from sources · `script/hydrate-agents`
- [Dehydrate agents](https://github.com/pbierkortte/ai-runbook/tree/master/script/dehydrate-agents): script · Strips generated bulk before commit · `script/dehydrate-agents`
- [Rebuild manifest](https://github.com/pbierkortte/ai-runbook/tree/master/script/rebuild-manifest): script · Regenerates repository catalogs and indexes · `script/rebuild-manifest`
- [Bootstrap](https://github.com/pbierkortte/ai-runbook/tree/master/script/bootstrap): script · Installs and wires the workspace environment · `script/bootstrap`
- [Install skills](https://github.com/pbierkortte/ai-runbook/tree/master/script/install-skills): script · Links skills into other environments · `script/install-skills`
- [Skills manifest](https://github.com/pbierkortte/ai-runbook/blob/master/agents/openskills-manifest.yml): agent manifest · OpenSkills manifest for installed capabilities · `agents/openskills-manifest.yml`

### Docs and integrations

Operational docs, validation, and external tool entrypoints

- [README](https://github.com/pbierkortte/ai-runbook/blob/master/README.md): entry doc · Repository overview and setup guide · `README.md`
- [Docs](https://github.com/pbierkortte/ai-runbook/tree/master/docs): conventions docs · Operational documentation for the runbook system · `docs`
- [Tool installers](https://github.com/pbierkortte/ai-runbook/tree/master/script/install-claude): integration scripts · Optional installs for Claude, Cline, Kilo, yq · `script/install-claude`
- [Run CI](https://github.com/pbierkortte/ai-runbook/blob/master/.github/workflows/run-ci.yml): validation workflow · Repository-level validation pipeline · `.github/workflows/run-ci.yml`
- [Docs manifest](https://github.com/pbierkortte/ai-runbook/blob/master/docs/MANIFEST.md): doc index · Docs-side catalog for navigation · `docs/MANIFEST.md`
- [Docs AGENTS](https://github.com/pbierkortte/ai-runbook/blob/master/docs/AGENTS.md): agent index · Directory-local agent context index for docs · `docs/AGENTS.md`

## Connections

- README → Scripts: explains setup · README documents the lifecycle and orchestration commands
- README → Skills: describes · README positions skills as reusable capability bundles
- README → Cores: describes · README explains the C/O/R/E/S persona framework
- README → Rules: describes · README explains directory-scoped rule overlays
- Rules → Stage rules: staged by · Rules are collected into temporary staged inputs
- Stage rules → Hydrate agents: feeds · Staged rules are incorporated during hydration
- Skills → Install skills: installed by · Skills are linked into target environments by installer scripts
- Cores → Hydrate agents: influences · Persona modules shape hydrated agent context
- Spectrum → Cores: subset of · Spectrum is the main named role set
- Extras → Cores: extends · Extras adds supplementary role variants
- Hydrate agents → Root AGENTS: generates · Hydration produces agent-visible indexes and context files
- Hydrate agents → Docs AGENTS: hydrates · Subdirectory AGENTS.md files are populated from local context
- Dehydrate agents → Root AGENTS: shrinks · Generated bulk is removed before commit
- Rebuild manifest → Root manifest: generates · Repository catalog is rebuilt from source definitions
- Rebuild manifest → Docs manifest: generates · Docs catalog is regenerated alongside the root manifest
- Bootstrap → Scripts: orchestrates · Bootstrap wires the shell and environment lifecycle
- Bootstrap → Tool installers: optionally installs · Bootstrap can set up external tooling integrations
- Run CI → Scripts: validates · Workflow exercises repo maintenance and generation scripts
- Docs → Docs AGENTS: documents · Docs explain local agent index conventions
- Docs → Docs manifest: documents · Docs provide navigable references and conventions
- Tools → Run CI: consumed by · Standalone prompts are governed by repo-level checks indirectly
- Skills → Skills manifest: publishes · Installed skills are summarized in an OpenSkills manifest
- Scripts → Skills manifest: builds · Scripts maintain the runtime-facing skills manifest
- Scripts → Hydrate agents: contains · Hydration is part of the script-driven lifecycle
- Scripts → Dehydrate agents: contains · Dehydration keeps generated files diff-clean
- Scripts → Rebuild manifest: contains · Manifest regeneration is a core maintenance task
- Docs → Run CI: covered by · Documentation and conventions are validated in CI