# eirkkr/fieldkit architecture

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

- Interactive diagram: https://gitdiagram.com/eirkkr/fieldkit
- Repository: https://github.com/eirkkr/fieldkit

## Overview

Field Kit is shared guidance and Claude Code tooling that consumer repositories link rather than copy. The main workflow is: a developer opts a repository into the kit, Claude reads its always-on and task-specific guidance, then uses shared skills; hooks can enforce selected rules during tool calls, commits, or turn completion. Separate branches provide OpenSpec and Python-specific workflows, while machine-level setup registers hooks and the status line. Relationships for unsampled capabilities rely on README statements; source-level evidence is limited to the excerpts shown.

Main entry points: [`skills`](https://github.com/eirkkr/fieldkit/tree/main/skills) (Shared skills), [`scripts`](https://github.com/eirkkr/fieldkit/tree/main/scripts) (Settings setup), [`hooks/conventions.py`](https://github.com/eirkkr/fieldkit/blob/main/hooks/conventions.py) (Rule logic), [`KIT.md`](https://github.com/eirkkr/fieldkit/blob/main/KIT.md) (Kit entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guidance["Shared guidance"]
  node_kit_entry["Kit entry<br/>[KIT.md]"]
  node_conventions["Conventions"]
  node_decisions["Design records"]
end

subgraph group_workflows["Agent workflows"]
  node_core_skills["Shared skills"]
  node_git_skills["Git skills<br/>[SKILL.md]"]
  node_change_plan["Change planning<br/>[SKILL.md]"]
  node_change_stage["Change staging<br/>[SKILL.md]"]
  node_pr_merge["PR and merge<br/>[SKILL.md]"]
  node_openspec_skills["OpenSpec skills"]
  node_openspec_overlay["OpenSpec overlays"]
  node_openspec_schema["Workflow schemas"]
  node_python_skills["Python skills"]
end

subgraph group_enforcement["Rule enforcement"]
  node_rule_logic["Rule logic<br/>[conventions.py]"]
  node_branch_hook["Branch hook"]
  node_merge_hook["Merge hook"]
  node_stop_hook["Formatter hook<br/>[stop-autofix.py]"]
  node_git_hooks["Git hooks"]
end

subgraph group_machine["Machine integration"]
  node_settings_scripts["Settings setup"]
  node_settings_edit["Settings editor<br/>[settings_edit.py]"]
  node_statusline["Status line"]
end

node_developer(("Developer"))
node_consumer_repo["Consumer repo"]
node_claude(("Claude Code"))
node_settings["Claude settings"]

node_developer -->|"opts in"| node_consumer_repo
node_consumer_repo -->|"imports"| node_kit_entry
node_kit_entry -->|"points to"| node_conventions
node_developer -->|"invokes"| node_core_skills
node_core_skills -->|"includes"| node_git_skills
node_core_skills -->|"includes"| node_change_plan
node_core_skills -->|"includes"| node_change_stage
node_core_skills -->|"includes"| node_pr_merge
node_developer -->|"opts into"| node_openspec_skills
node_openspec_overlay -->|"patches"| node_openspec_skills
node_developer -->|"opts into"| node_openspec_schema
node_developer -->|"opts into"| node_python_skills
node_branch_hook -->|"checks with"| node_rule_logic
node_merge_hook -->|"checks with"| node_rule_logic
node_git_hooks -->|"checks with"| node_rule_logic
node_claude -->|"runs before tools"| node_branch_hook
node_claude -->|"runs before tools"| node_merge_hook
node_claude -->|"runs at turn end"| node_stop_hook
node_developer -->|"enables"| node_git_hooks
node_developer -->|"installs"| node_settings_scripts
node_settings_scripts -->|"uses"| node_settings_edit
node_settings_scripts -->|"registers hooks"| node_settings
node_settings_scripts -->|"links"| node_statusline
node_settings -->|"configures"| node_claude
node_decisions -->|"documents rationale"| node_developer

click node_kit_entry "https://github.com/eirkkr/fieldkit/blob/main/KIT.md"
click node_conventions "https://github.com/eirkkr/fieldkit/tree/main/conventions"
click node_decisions "https://github.com/eirkkr/fieldkit/tree/main/docs/decisions"
click node_core_skills "https://github.com/eirkkr/fieldkit/tree/main/skills"
click node_git_skills "https://github.com/eirkkr/fieldkit/blob/main/skills/push/SKILL.md"
click node_change_plan "https://github.com/eirkkr/fieldkit/blob/main/skills/change-plan/SKILL.md"
click node_change_stage "https://github.com/eirkkr/fieldkit/blob/main/skills/change-stage/SKILL.md"
click node_pr_merge "https://github.com/eirkkr/fieldkit/blob/main/skills/pr/SKILL.md"
click node_openspec_skills "https://github.com/eirkkr/fieldkit/tree/main/repo-skills"
click node_openspec_overlay "https://github.com/eirkkr/fieldkit/tree/main/repo-skills-overlay"
click node_openspec_schema "https://github.com/eirkkr/fieldkit/tree/main/schemas"
click node_python_skills "https://github.com/eirkkr/fieldkit/tree/main/python-skills"
click node_rule_logic "https://github.com/eirkkr/fieldkit/blob/main/hooks/conventions.py"
click node_branch_hook "https://github.com/eirkkr/fieldkit/blob/main/hooks/pretooluse-branch-name.py"
click node_merge_hook "https://github.com/eirkkr/fieldkit/blob/main/hooks/pretooluse-merge-message.py"
click node_stop_hook "https://github.com/eirkkr/fieldkit/blob/main/hooks/stop-autofix.py"
click node_git_hooks "https://github.com/eirkkr/fieldkit/tree/main/hooks"
click node_settings_scripts "https://github.com/eirkkr/fieldkit/tree/main/scripts"
click node_settings_edit "https://github.com/eirkkr/fieldkit/blob/main/scripts/settings_edit.py"
click node_statusline "https://github.com/eirkkr/fieldkit/tree/main/statusline"

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_kit_entry,node_conventions,node_decisions toneBlue
class node_core_skills,node_git_skills,node_change_plan,node_change_stage,node_pr_merge,node_openspec_skills,node_openspec_overlay,node_openspec_schema,node_python_skills toneAmber
class node_rule_logic,node_branch_hook,node_merge_hook,node_stop_hook,node_git_hooks toneMint
class node_settings_scripts,node_settings_edit,node_statusline toneRose
class node_developer,node_consumer_repo,node_claude,node_settings toneIndigo
```

## Components

### Shared guidance

- [Kit entry](https://github.com/eirkkr/fieldkit/blob/main/KIT.md): `KIT.md`
- [Conventions](https://github.com/eirkkr/fieldkit/tree/main/conventions): `conventions`
- [Design records](https://github.com/eirkkr/fieldkit/tree/main/docs/decisions): `docs/decisions`

### Agent workflows

- [Shared skills](https://github.com/eirkkr/fieldkit/tree/main/skills): `skills`
- [Git skills](https://github.com/eirkkr/fieldkit/blob/main/skills/push/SKILL.md): `skills/push/SKILL.md`
- [Change planning](https://github.com/eirkkr/fieldkit/blob/main/skills/change-plan/SKILL.md): `skills/change-plan/SKILL.md`
- [Change staging](https://github.com/eirkkr/fieldkit/blob/main/skills/change-stage/SKILL.md): `skills/change-stage/SKILL.md`
- [PR and merge](https://github.com/eirkkr/fieldkit/blob/main/skills/pr/SKILL.md): `skills/pr/SKILL.md`
- [OpenSpec skills](https://github.com/eirkkr/fieldkit/tree/main/repo-skills): `repo-skills`
- [OpenSpec overlays](https://github.com/eirkkr/fieldkit/tree/main/repo-skills-overlay): `repo-skills-overlay`
- [Workflow schemas](https://github.com/eirkkr/fieldkit/tree/main/schemas): `schemas`
- [Python skills](https://github.com/eirkkr/fieldkit/tree/main/python-skills): `python-skills`

### Rule enforcement

- [Rule logic](https://github.com/eirkkr/fieldkit/blob/main/hooks/conventions.py): `hooks/conventions.py`
- [Branch hook](https://github.com/eirkkr/fieldkit/blob/main/hooks/pretooluse-branch-name.py): `hooks/pretooluse-branch-name.py`
- [Merge hook](https://github.com/eirkkr/fieldkit/blob/main/hooks/pretooluse-merge-message.py): `hooks/pretooluse-merge-message.py`
- [Formatter hook](https://github.com/eirkkr/fieldkit/blob/main/hooks/stop-autofix.py): `hooks/stop-autofix.py`
- [Git hooks](https://github.com/eirkkr/fieldkit/tree/main/hooks): `hooks`

### Machine integration

- [Settings setup](https://github.com/eirkkr/fieldkit/tree/main/scripts): `scripts`
- [Settings editor](https://github.com/eirkkr/fieldkit/blob/main/scripts/settings_edit.py): `scripts/settings_edit.py`
- [Status line](https://github.com/eirkkr/fieldkit/tree/main/statusline): `statusline`

### Other components

- **Developer**
- **Consumer repo**
- **Claude Code**
- **Claude settings**

## Connections

- Developer → Consumer repo: opts in (evidence: `README.md`)
- Consumer repo → Kit entry: imports (evidence: `README.md`)
- Kit entry → Conventions: points to (evidence: `README.md`)
- Developer → Shared skills: invokes (evidence: `README.md`)
- Shared skills → Git skills: includes (evidence: `README.md`)
- Shared skills → Change planning: includes (evidence: `README.md`)
- Shared skills → Change staging: includes (evidence: `README.md`)
- Shared skills → PR and merge: includes (evidence: `README.md`)
- Developer → OpenSpec skills: opts into (evidence: `README.md`)
- OpenSpec overlays → OpenSpec skills: patches (evidence: `README.md`)
- Developer → Workflow schemas: opts into (evidence: `README.md`)
- Developer → Python skills: opts into (evidence: `README.md`)
- Branch hook → Rule logic: checks with (evidence: `hooks/pretooluse-branch-name.py`)
- Merge hook → Rule logic: checks with (evidence: `hooks/pretooluse-merge-message.py`)
- Git hooks → Rule logic: checks with (evidence: `hooks/conventions.py`)
- Claude Code → Branch hook: runs before tools (evidence: `README.md`)
- Claude Code → Merge hook: runs before tools (evidence: `README.md`)
- Claude Code → Formatter hook: runs at turn end (evidence: `README.md`)
- Developer → Git hooks: enables (evidence: `README.md`)
- Developer → Settings setup: installs (evidence: `README.md`)
- Settings setup → Settings editor: uses (evidence: `scripts/register_hooks.py`)
- Settings setup → Claude settings: registers hooks (evidence: `README.md`)
- Settings setup → Status line: links (evidence: `README.md`)
- Claude settings → Claude Code: configures (evidence: `README.md`)
- Design records → Developer: documents rationale (evidence: `README.md`)