# idrispwala-web/golden-rules architecture

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

- Interactive diagram: https://gitdiagram.com/idrispwala-web/golden-rules
- Repository: https://github.com/idrispwala-web/golden-rules

## Overview

golden-rules is a Claude Code setup wizard: users choose global rule modules and optional integrations, then it writes configuration and runtime files; a separate project command scaffolds project rules and packs. Its optional brain hooks synchronize a user-owned Git vault at session start and end. The graph also includes the documented status line, skills, and pack capabilities. Evidence is limited to the README and sampled excerpts; unsampled pack contents and integrations are represented only where documented.

Main entry points: [`bin/cli.mjs`](https://github.com/idrispwala-web/golden-rules/blob/main/bin/cli.mjs) (Setup CLI), [`templates/runtime/hooks/brain-pull.mjs`](https://github.com/idrispwala-web/golden-rules/blob/main/templates/runtime/hooks/brain-pull.mjs) (Vault pull hook), [`templates/runtime/hooks/brain-push.mjs`](https://github.com/idrispwala-web/golden-rules/blob/main/templates/runtime/hooks/brain-push.mjs) (Vault push hook), [`lib/install.mjs`](https://github.com/idrispwala-web/golden-rules/blob/main/lib/install.mjs) (Config installer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup wizard"]
  node_cli["Setup CLI<br/>[cli.mjs]"]
  node_prompts["Prompt helpers<br/>[ask.mjs]"]
  node_detection["Environment detection<br/>[detect.mjs]"]
  node_installer["Config installer<br/>[install.mjs]"]
end

subgraph group_configuration["Configuration content"]
  node_ruletemplates["Rule templates"]
  node_packs["Project packs"]
  node_skill["Golden-rules skill<br/>[SKILL.md]"]
end

subgraph group_project["Project scaffolding"]
  node_projectinit["Project initializer<br/>[project.mjs]"]
end

subgraph group_runtime["Claude runtime"]
  node_statusline["Status line<br/>[statusline.mjs]"]
  node_brainpull["Vault pull hook<br/>[brain-pull.mjs]"]
  node_brainpush["Vault push hook<br/>[brain-push.mjs]"]
  node_githelpers["Git sync helpers<br/>[_git.mjs]"]
end

subgraph group_integrations["Optional integrations"]
  node_optionaltools["Optional tools"]
  node_goinstaller["Skill installer<br/>[main.go]"]
end

node_user(("User"))
node_claude(("Claude Code"))
node_vault[("User vault repo")]

node_user -->|"runs setup"| node_cli
node_cli -->|"asks questions"| node_prompts
node_cli -->|"checks environment"| node_detection
node_cli -->|"installs configuration"| node_installer
node_cli -->|"dispatches project"| node_projectinit
node_installer -->|"composes rules"| node_ruletemplates
node_cli -->|"configures command"| node_statusline
node_cli -->|"installs when selected"| node_brainpull
node_cli -->|"installs when selected"| node_brainpush
node_cli -->|"installs skill"| node_skill
node_projectinit -->|"copies selected pack"| node_packs
node_statusline -.->|"prints status"| node_claude
node_claude -->|"runs at session start"| node_brainpull
node_claude -->|"runs at session end"| node_brainpush
node_brainpull -->|"uses sync helpers"| node_githelpers
node_brainpush -->|"uses sync helpers"| node_githelpers
node_brainpull -->|"pulls changes"| node_vault
node_brainpush -->|"commits and pushes"| node_vault
node_cli -->|"offers installation"| node_optionaltools
node_user -.->|"runs skill installer"| node_goinstaller
node_goinstaller -->|"installs skills and tools"| node_claude

click node_cli "https://github.com/idrispwala-web/golden-rules/blob/main/bin/cli.mjs"
click node_prompts "https://github.com/idrispwala-web/golden-rules/blob/main/lib/ask.mjs"
click node_detection "https://github.com/idrispwala-web/golden-rules/blob/main/lib/detect.mjs"
click node_installer "https://github.com/idrispwala-web/golden-rules/blob/main/lib/install.mjs"
click node_projectinit "https://github.com/idrispwala-web/golden-rules/blob/main/lib/project.mjs"
click node_ruletemplates "https://github.com/idrispwala-web/golden-rules/tree/main/templates/claude"
click node_packs "https://github.com/idrispwala-web/golden-rules/tree/main/packs"
click node_skill "https://github.com/idrispwala-web/golden-rules/blob/main/skills/golden-rules/SKILL.md"
click node_statusline "https://github.com/idrispwala-web/golden-rules/blob/main/templates/runtime/statusline.mjs"
click node_brainpull "https://github.com/idrispwala-web/golden-rules/blob/main/templates/runtime/hooks/brain-pull.mjs"
click node_brainpush "https://github.com/idrispwala-web/golden-rules/blob/main/templates/runtime/hooks/brain-push.mjs"
click node_githelpers "https://github.com/idrispwala-web/golden-rules/blob/main/templates/runtime/hooks/_git.mjs"
click node_goinstaller "https://github.com/idrispwala-web/golden-rules/blob/main/main.go"

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_cli,node_prompts,node_detection,node_installer,node_user toneBlue
class node_ruletemplates,node_packs,node_skill,node_vault toneAmber
class node_projectinit toneMint
class node_statusline,node_brainpull,node_brainpush,node_githelpers toneRose
class node_optionaltools,node_goinstaller,node_claude toneIndigo
```

## Components

### Setup wizard

- [Setup CLI](https://github.com/idrispwala-web/golden-rules/blob/main/bin/cli.mjs): `bin/cli.mjs`
- [Prompt helpers](https://github.com/idrispwala-web/golden-rules/blob/main/lib/ask.mjs): `lib/ask.mjs`
- [Environment detection](https://github.com/idrispwala-web/golden-rules/blob/main/lib/detect.mjs): `lib/detect.mjs`
- [Config installer](https://github.com/idrispwala-web/golden-rules/blob/main/lib/install.mjs): `lib/install.mjs`

### Configuration content

- [Rule templates](https://github.com/idrispwala-web/golden-rules/tree/main/templates/claude): `templates/claude`
- [Project packs](https://github.com/idrispwala-web/golden-rules/tree/main/packs): `packs`
- [Golden-rules skill](https://github.com/idrispwala-web/golden-rules/blob/main/skills/golden-rules/SKILL.md): `skills/golden-rules/SKILL.md`

### Project scaffolding

- [Project initializer](https://github.com/idrispwala-web/golden-rules/blob/main/lib/project.mjs): `lib/project.mjs`

### Claude runtime

- [Status line](https://github.com/idrispwala-web/golden-rules/blob/main/templates/runtime/statusline.mjs): `templates/runtime/statusline.mjs`
- [Vault pull hook](https://github.com/idrispwala-web/golden-rules/blob/main/templates/runtime/hooks/brain-pull.mjs): `templates/runtime/hooks/brain-pull.mjs`
- [Vault push hook](https://github.com/idrispwala-web/golden-rules/blob/main/templates/runtime/hooks/brain-push.mjs): `templates/runtime/hooks/brain-push.mjs`
- [Git sync helpers](https://github.com/idrispwala-web/golden-rules/blob/main/templates/runtime/hooks/_git.mjs): `templates/runtime/hooks/_git.mjs`

### Optional integrations

- **Optional tools**
- [Skill installer](https://github.com/idrispwala-web/golden-rules/blob/main/main.go): `main.go`

### Other components

- **User**
- **Claude Code**
- **User vault repo**

## Connections

- User → Setup CLI: runs setup (evidence: `README.md`)
- Setup CLI → Prompt helpers: asks questions (evidence: `bin/cli.mjs`)
- Setup CLI → Environment detection: checks environment (evidence: `bin/cli.mjs`)
- Setup CLI → Config installer: installs configuration (evidence: `bin/cli.mjs`)
- Setup CLI → Project initializer: dispatches project (evidence: `bin/cli.mjs`)
- Config installer → Rule templates: composes rules (evidence: `lib/install.mjs`)
- Setup CLI → Status line: configures command (evidence: `bin/cli.mjs`)
- Setup CLI → Vault pull hook: installs when selected (evidence: `bin/cli.mjs`)
- Setup CLI → Vault push hook: installs when selected (evidence: `bin/cli.mjs`)
- Setup CLI → Golden-rules skill: installs skill (evidence: `bin/cli.mjs`)
- Project initializer → Project packs: copies selected pack (evidence: `lib/project.mjs`)
- Status line → Claude Code: prints status (evidence: `README.md`)
- Claude Code → Vault pull hook: runs at session start
- Claude Code → Vault push hook: runs at session end
- Vault pull hook → Git sync helpers: uses sync helpers (evidence: `templates/runtime/hooks/brain-pull.mjs`)
- Vault push hook → Git sync helpers: uses sync helpers (evidence: `templates/runtime/hooks/brain-push.mjs`)
- Vault pull hook → User vault repo: pulls changes (evidence: `templates/runtime/hooks/brain-pull.mjs`)
- Vault push hook → User vault repo: commits and pushes (evidence: `templates/runtime/hooks/brain-push.mjs`)
- Setup CLI → Optional tools: offers installation (evidence: `bin/cli.mjs`)
- User → Skill installer: runs skill installer (evidence: `README.md`)
- Skill installer → Claude Code: installs skills and tools (evidence: `main.go`)
