pbierkortte/ai-runbook

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?”