# jaabster-dev/u-gas architecture

> Architecture diagram of the GitHub repository jaabster-dev/u-gas, 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/jaabster-dev/u-gas
- Repository: https://github.com/jaabster-dev/u-gas

## Overview

U-GAS helps a person start or resume an AI-assisted project while keeping durable project context in ordinary files. The main workflow is: use the Starter to generate a prompt, give it to an AI agent with persistent file access, and return material results so project state stays current. PICA files and agent guidance support continuity; standalone scripts check project/distribution contracts, pending handoffs, and Git branch health. The README documents the workflow, but the Starter and guidance implementations were not sampled, so their internal links are limited to documented relationships.

Main entry points: [`starter/index.html`](https://github.com/jaabster-dev/u-gas/blob/main/starter/index.html) (Project Starter), [`scripts/pica_contract.py`](https://github.com/jaabster-dev/u-gas/blob/main/scripts/pica_contract.py) (PICA contract helpers), [`templates/pica`](https://github.com/jaabster-dev/u-gas/tree/main/templates/pica) (PICA controls), [`scripts/check_u_gas.py`](https://github.com/jaabster-dev/u-gas/blob/main/scripts/check_u_gas.py) (U-GAS self-check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_onboarding["Project onboarding"]
  node_starter["Project Starter<br/>[index.html]"]
end

subgraph group_continuity["Project continuity"]
  node_project["Project workspace"]
  node_pica["PICA controls"]
end

subgraph group_guidance["Agent guidance"]
  node_resume["Resume guidance"]
  node_governance["Agent governance<br/>[GOVERNANCE.md]"]
  node_github["GitHub workflow<br/>[GITHUB_WORKFLOW.md]"]
  node_patching["Safe large-file patches"]
  node_collaboration["Multi-agent coordination"]
  node_structure["Repository structure guidance"]
  node_compliance["Compliance guidance<br/>[COMPLIANCE.md]"]
  node_skills["Operational skills"]
end

subgraph group_checks["Local checks"]
  node_pica_helpers["PICA contract helpers<br/>[pica_contract.py]"]
  node_self_check["U-GAS self-check<br/>[check_u_gas.py]"]
  node_handoff_check["Handoff contract checker<br/>[check_handoff.py]"]
  node_health_check["Git branch health"]
end

node_person(("Project owner"))
node_agent(("AI coding agent"))

node_person -->|"chooses mode"| node_starter
node_starter -->|"generates prompt"| node_agent
node_agent -->|"creates or continues"| node_project
node_agent -->|"reads and updates"| node_pica
node_agent -->|"follows continuity"| node_resume
node_agent -.->|"follows guidance"| node_governance
node_agent -.->|"follows guidance"| node_github
node_agent -.->|"follows guidance"| node_patching
node_agent -.->|"follows guidance"| node_collaboration
node_agent -.->|"follows guidance"| node_structure
node_agent -.->|"follows guidance"| node_compliance
node_agent -.->|"uses skills"| node_skills
node_self_check -->|"uses helpers"| node_pica_helpers
node_pica_helpers -->|"loads templates"| node_pica

click node_starter "https://github.com/jaabster-dev/u-gas/blob/main/starter/index.html"
click node_pica "https://github.com/jaabster-dev/u-gas/tree/main/templates/pica"
click node_resume "https://github.com/jaabster-dev/u-gas/blob/main/ai/SESSION_CONTINUITY.md"
click node_governance "https://github.com/jaabster-dev/u-gas/blob/main/ai/GOVERNANCE.md"
click node_github "https://github.com/jaabster-dev/u-gas/blob/main/ai/GITHUB_WORKFLOW.md"
click node_patching "https://github.com/jaabster-dev/u-gas/blob/main/ai/LARGE_FILE_PATCHING.md"
click node_collaboration "https://github.com/jaabster-dev/u-gas/blob/main/ai/MULTI_AGENT_COLLABORATION.md"
click node_structure "https://github.com/jaabster-dev/u-gas/blob/main/ai/REPOSITORY_STRUCTURE.md"
click node_compliance "https://github.com/jaabster-dev/u-gas/blob/main/ai/COMPLIANCE.md"
click node_skills "https://github.com/jaabster-dev/u-gas/tree/main/skills"
click node_pica_helpers "https://github.com/jaabster-dev/u-gas/blob/main/scripts/pica_contract.py"
click node_self_check "https://github.com/jaabster-dev/u-gas/blob/main/scripts/check_u_gas.py"
click node_handoff_check "https://github.com/jaabster-dev/u-gas/blob/main/scripts/check_handoff.py"
click node_health_check "https://github.com/jaabster-dev/u-gas/blob/main/scripts/check_repository_health.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_starter toneBlue
class node_project,node_pica toneAmber
class node_resume,node_governance,node_github,node_patching,node_collaboration,node_structure,node_compliance,node_skills toneMint
class node_pica_helpers,node_self_check,node_handoff_check,node_health_check toneRose
class node_person,node_agent toneIndigo
```

## Components

### Project onboarding

- [Project Starter](https://github.com/jaabster-dev/u-gas/blob/main/starter/index.html): `starter/index.html`

### Project continuity

- **Project workspace**
- [PICA controls](https://github.com/jaabster-dev/u-gas/tree/main/templates/pica): `templates/pica`

### Agent guidance

- [Resume guidance](https://github.com/jaabster-dev/u-gas/blob/main/ai/SESSION_CONTINUITY.md): `ai/SESSION_CONTINUITY.md`
- [Agent governance](https://github.com/jaabster-dev/u-gas/blob/main/ai/GOVERNANCE.md): `ai/GOVERNANCE.md`
- [GitHub workflow](https://github.com/jaabster-dev/u-gas/blob/main/ai/GITHUB_WORKFLOW.md): `ai/GITHUB_WORKFLOW.md`
- [Safe large-file patches](https://github.com/jaabster-dev/u-gas/blob/main/ai/LARGE_FILE_PATCHING.md): `ai/LARGE_FILE_PATCHING.md`
- [Multi-agent coordination](https://github.com/jaabster-dev/u-gas/blob/main/ai/MULTI_AGENT_COLLABORATION.md): `ai/MULTI_AGENT_COLLABORATION.md`
- [Repository structure guidance](https://github.com/jaabster-dev/u-gas/blob/main/ai/REPOSITORY_STRUCTURE.md): `ai/REPOSITORY_STRUCTURE.md`
- [Compliance guidance](https://github.com/jaabster-dev/u-gas/blob/main/ai/COMPLIANCE.md): `ai/COMPLIANCE.md`
- [Operational skills](https://github.com/jaabster-dev/u-gas/tree/main/skills): `skills`

### Local checks

- [PICA contract helpers](https://github.com/jaabster-dev/u-gas/blob/main/scripts/pica_contract.py): `scripts/pica_contract.py`
- [U-GAS self-check](https://github.com/jaabster-dev/u-gas/blob/main/scripts/check_u_gas.py): `scripts/check_u_gas.py`
- [Handoff contract checker](https://github.com/jaabster-dev/u-gas/blob/main/scripts/check_handoff.py): `scripts/check_handoff.py`
- [Git branch health](https://github.com/jaabster-dev/u-gas/blob/main/scripts/check_repository_health.py): `scripts/check_repository_health.py`

### Other components

- **Project owner**
- **AI coding agent**

## Connections

- Project owner → Project Starter: chooses mode (evidence: `README.md`)
- Project Starter → AI coding agent: generates prompt (evidence: `README.md`)
- AI coding agent → Project workspace: creates or continues (evidence: `README.md`)
- AI coding agent → PICA controls: reads and updates (evidence: `README.md`)
- AI coding agent → Resume guidance: follows continuity (evidence: `README.md`)
- AI coding agent → Agent governance: follows guidance
- AI coding agent → GitHub workflow: follows guidance
- AI coding agent → Safe large-file patches: follows guidance
- AI coding agent → Multi-agent coordination: follows guidance
- AI coding agent → Repository structure guidance: follows guidance
- AI coding agent → Compliance guidance: follows guidance
- AI coding agent → Operational skills: uses skills
- U-GAS self-check → PICA contract helpers: uses helpers (evidence: `scripts/check_u_gas.py`)
- PICA contract helpers → PICA controls: loads templates (evidence: `scripts/pica_contract.py`)
