# theblackcat98/pags architecture

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

- Interactive diagram: https://gitdiagram.com/theblackcat98/pags
- Repository: https://github.com/theblackcat98/pags

## Overview

PAGS equips a repository with agent-workflow records, an installer, and a checker. The main workflow is: a maintainer installs the records, an agent uses them to guide and document changes, and the checker validates their consistency. The README documents adoption profiles, greenfield/brownfield setup, and optional design records. Installer and checker internals are represented from sampled source; the agent loop and record roles come from the README and templates, so their runtime wiring is shown only where documented.

Main entry points: [`scripts/install-pags.py`](https://github.com/theblackcat98/pags/blob/main/scripts/install-pags.py) (Installer), [`.pags-templates`](https://github.com/theblackcat98/pags/tree/main/.pags-templates) (Record updates), [`scripts/pags-check.py`](https://github.com/theblackcat98/pags/blob/main/scripts/pags-check.py) (Records checker), [`.pags-templates/AGENTS.md`](https://github.com/theblackcat98/pags/blob/main/.pags-templates/AGENTS.md) (Agent change loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_adoption["Adoption"]
  node_installer["Installer<br/>[install-pags.py]"]
  node_adoption_choice["Adoption setup<br/>[install-pags.py]"]
end

subgraph group_records["Project records"]
  node_record_templates["Record templates<br/>[.pags-templates]"]
  node_agent_guide["Agent guide<br/>[AGENTS.md]"]
  node_charter["Charter<br/>[CHARTER.md]"]
  node_work["Work records<br/>[WORK.md]"]
  node_decisions["Decisions<br/>[DECISIONS.md]"]
  node_architecture["Architecture record<br/>[ARCHITECTURE.md]"]
  node_design["Design record<br/>[DESIGN.md]"]
  node_user_readme["User README<br/>[README.md]"]
end

subgraph group_workflow["Agent workflow"]
  node_agent_loop["Agent change loop<br/>[AGENTS.md]"]
  node_record_updates["Record updates<br/>[.pags-templates]"]
end

subgraph group_validation["Consistency checks"]
  node_checker["Records checker<br/>[pags-check.py]"]
  node_parse_records["Parse records<br/>[pags-check.py]"]
  node_consistency_rules["Consistency rules<br/>[pags-check.py]"]
  node_check_report["Check result<br/>[pags-check.py]"]
end

node_maintainer(("Maintainer"))
node_repository[("Target repository")]
node_agent(("Coding agent"))

node_maintainer -->|"runs install"| node_installer
node_installer -->|"detects profile"| node_adoption_choice
node_installer -->|"reads templates"| node_record_templates
node_installer -->|"writes selected files"| node_repository
node_maintainer -->|"sets agent rules"| node_agent_guide
node_agent -->|"follows workflow"| node_agent_loop
node_agent_loop -->|"reads project records"| node_repository
node_agent_loop -->|"updates records"| node_record_updates
node_record_updates -->|"records outcomes and tasks"| node_work
node_record_updates -->|"records choices"| node_decisions
node_record_updates -->|"records current system"| node_architecture
node_maintainer -->|"approves boundaries"| node_charter
node_agent -->|"runs check"| node_checker
node_checker -->|"reads records"| node_repository
node_checker -->|"parses entries"| node_parse_records
node_parse_records -->|"checks parsed entries"| node_consistency_rules
node_consistency_rules -->|"produces findings"| node_check_report
node_checker -->|"reports findings"| node_agent

click node_installer "https://github.com/theblackcat98/pags/blob/main/scripts/install-pags.py"
click node_adoption_choice "https://github.com/theblackcat98/pags/blob/main/scripts/install-pags.py"
click node_record_templates "https://github.com/theblackcat98/pags/tree/main/.pags-templates"
click node_agent_guide "https://github.com/theblackcat98/pags/blob/main/.pags-templates/AGENTS.md"
click node_charter "https://github.com/theblackcat98/pags/blob/main/.pags-templates/CHARTER.md"
click node_work "https://github.com/theblackcat98/pags/blob/main/.pags-templates/WORK.md"
click node_decisions "https://github.com/theblackcat98/pags/blob/main/.pags-templates/DECISIONS.md"
click node_architecture "https://github.com/theblackcat98/pags/blob/main/.pags-templates/ARCHITECTURE.md"
click node_design "https://github.com/theblackcat98/pags/blob/main/.pags-templates/DESIGN.md"
click node_user_readme "https://github.com/theblackcat98/pags/blob/main/.pags-templates/README.md"
click node_agent_loop "https://github.com/theblackcat98/pags/blob/main/.pags-templates/AGENTS.md"
click node_record_updates "https://github.com/theblackcat98/pags/tree/main/.pags-templates"
click node_checker "https://github.com/theblackcat98/pags/blob/main/scripts/pags-check.py"
click node_parse_records "https://github.com/theblackcat98/pags/blob/main/scripts/pags-check.py"
click node_consistency_rules "https://github.com/theblackcat98/pags/blob/main/scripts/pags-check.py"
click node_check_report "https://github.com/theblackcat98/pags/blob/main/scripts/pags-check.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_installer,node_adoption_choice toneBlue
class node_record_templates,node_agent_guide,node_charter,node_work,node_decisions,node_architecture,node_design,node_user_readme,node_repository toneAmber
class node_agent_loop,node_record_updates toneMint
class node_checker,node_parse_records,node_consistency_rules,node_check_report toneRose
class node_maintainer,node_agent toneIndigo
```

## Components

### Adoption

- [Installer](https://github.com/theblackcat98/pags/blob/main/scripts/install-pags.py): `scripts/install-pags.py`
- [Adoption setup](https://github.com/theblackcat98/pags/blob/main/scripts/install-pags.py): `scripts/install-pags.py`

### Project records

- [Record templates](https://github.com/theblackcat98/pags/tree/main/.pags-templates): `.pags-templates`
- [Agent guide](https://github.com/theblackcat98/pags/blob/main/.pags-templates/AGENTS.md): `.pags-templates/AGENTS.md`
- [Charter](https://github.com/theblackcat98/pags/blob/main/.pags-templates/CHARTER.md): `.pags-templates/CHARTER.md`
- [Work records](https://github.com/theblackcat98/pags/blob/main/.pags-templates/WORK.md): `.pags-templates/WORK.md`
- [Decisions](https://github.com/theblackcat98/pags/blob/main/.pags-templates/DECISIONS.md): `.pags-templates/DECISIONS.md`
- [Architecture record](https://github.com/theblackcat98/pags/blob/main/.pags-templates/ARCHITECTURE.md): `.pags-templates/ARCHITECTURE.md`
- [Design record](https://github.com/theblackcat98/pags/blob/main/.pags-templates/DESIGN.md): `.pags-templates/DESIGN.md`
- [User README](https://github.com/theblackcat98/pags/blob/main/.pags-templates/README.md): `.pags-templates/README.md`

### Agent workflow

- [Agent change loop](https://github.com/theblackcat98/pags/blob/main/.pags-templates/AGENTS.md): `.pags-templates/AGENTS.md`
- [Record updates](https://github.com/theblackcat98/pags/tree/main/.pags-templates): `.pags-templates`

### Consistency checks

- [Records checker](https://github.com/theblackcat98/pags/blob/main/scripts/pags-check.py): `scripts/pags-check.py`
- [Parse records](https://github.com/theblackcat98/pags/blob/main/scripts/pags-check.py): `scripts/pags-check.py`
- [Consistency rules](https://github.com/theblackcat98/pags/blob/main/scripts/pags-check.py): `scripts/pags-check.py`
- [Check result](https://github.com/theblackcat98/pags/blob/main/scripts/pags-check.py): `scripts/pags-check.py`

### Other components

- **Maintainer**
- **Target repository**
- **Coding agent**

## Connections

- Maintainer → Installer: runs install
- Installer → Adoption setup: detects profile
- Installer → Record templates: reads templates
- Installer → Target repository: writes selected files
- Maintainer → Agent guide: sets agent rules
- Coding agent → Agent change loop: follows workflow
- Agent change loop → Target repository: reads project records
- Agent change loop → Record updates: updates records
- Record updates → Work records: records outcomes and tasks
- Record updates → Decisions: records choices
- Record updates → Architecture record: records current system
- Maintainer → Charter: approves boundaries
- Coding agent → Records checker: runs check
- Records checker → Target repository: reads records
- Records checker → Parse records: parses entries
- Parse records → Consistency rules: checks parsed entries
- Consistency rules → Check result: produces findings
- Records checker → Coding agent: reports findings