# jamillazarev/opsinist architecture

> Architecture diagram of the GitHub repository jamillazarev/opsinist, 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/jamillazarev/opsinist
- Repository: https://github.com/jamillazarev/opsinist

## Overview

Opsinist is a repository-based operating system for AI-agent teams: its skills and Markdown corpus describe company operations, while scripts and hooks provide selected enforcement and project-management functions. The documented user workflow starts with a natural-language request routed through the advisor, then enters an appropriate flow such as project initiation, takeover audit, backlog mapping, or task work. The graph preserves major documented capabilities as domain branches. Source excerpts are partial, so links between unsampled skill chapters and runtime helpers are omitted unless the README or excerpts support them.

Main entry points: [`skills/advisor/SKILL.md`](https://github.com/jamillazarev/opsinist/blob/main/skills/advisor/SKILL.md) (Advisor skill), [`skills`](https://github.com/jamillazarev/opsinist/tree/main/skills) (Agent skills), [`scripts/new-task.py`](https://github.com/jamillazarev/opsinist/blob/main/scripts/new-task.py) (Task creation), [`scripts/check-structure.py`](https://github.com/jamillazarev/opsinist/blob/main/scripts/check-structure.py) (Project validators)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontdoor["Skills and entrypoints"]
  node_advisor["Advisor skill<br/>[SKILL.md]"]
  node_agent_skills["Agent skills"]
  node_claude_plugin["Claude plugin<br/>[plugin.json]"]
  node_opencode_plugin["OpenCode plugin<br/>[opsinist.js]"]
  node_pi_extension["Pi extension<br/>[opsinist.ts]"]
end

subgraph group_work["Work lifecycle"]
  node_operations_corpus["Operations chapters<br/>[starting.md]"]
  node_task_authoring["Task creation<br/>[new-task.py]"]
  node_task_records["Task records"]
  node_task_board["Task board<br/>[board.py]"]
  node_stage_transition["Stage transition<br/>[transition.py]"]
end

subgraph group_governance["Governance and evidence"]
  node_takeover_gate["Takeover audit<br/>[audit-gate.py]"]
  node_dependency_review["Dependency review<br/>[deps-report.py]"]
  node_source_register["Source intake<br/>[fetch-source.py]"]
  node_cost_management["Cost management<br/>[cost.md]"]
  node_release_and_shipping["Release practice<br/>[shipping.md]"]
  node_migration["Layout migration<br/>[migrate-layout.py]"]
end

subgraph group_runtime["Runtime enforcement"]
  node_commit_guard["Audit hook<br/>[audit-gate.py]"]
  node_project_validators["Project validators<br/>[check-structure.py]"]
  node_coverage_map["Enforcement map<br/>[coverage-map.py]"]
end

node_user(("Operator"))
node_git_repository[("Project repository")]

node_user -->|"asks for work"| node_advisor
node_advisor -->|"routes requests"| node_agent_skills
node_agent_skills -.->|"loads guidance"| node_operations_corpus
node_user -.->|"requests a task"| node_task_authoring
node_task_authoring -->|"writes task"| node_task_records
node_task_board -->|"reads tasks"| node_task_records
node_stage_transition -->|"updates stage"| node_task_records
node_user -.->|"starts takeover"| node_takeover_gate
node_dependency_review -->|"inspects dependencies"| node_git_repository
node_source_register -->|"maintains sources"| node_git_repository
node_migration -->|"moves project files"| node_git_repository
node_commit_guard -.->|"checks run state"| node_git_repository
node_project_validators -->|"checks structure"| node_git_repository
node_coverage_map -->|"catalogues holders"| node_project_validators
node_user -.->|"plans spending"| node_cost_management
node_user -.->|"plans release"| node_release_and_shipping
node_user -->|"installs plugin"| node_claude_plugin
node_user -->|"uses runtime"| node_opencode_plugin
node_user -->|"uses runtime"| node_pi_extension

click node_advisor "https://github.com/jamillazarev/opsinist/blob/main/skills/advisor/SKILL.md"
click node_agent_skills "https://github.com/jamillazarev/opsinist/tree/main/skills"
click node_claude_plugin "https://github.com/jamillazarev/opsinist/blob/main/.claude-plugin/plugin.json"
click node_opencode_plugin "https://github.com/jamillazarev/opsinist/blob/main/.opencode/plugins/opsinist.js"
click node_pi_extension "https://github.com/jamillazarev/opsinist/blob/main/.pi/extensions/opsinist.ts"
click node_operations_corpus "https://github.com/jamillazarev/opsinist/blob/main/starting.md"
click node_task_authoring "https://github.com/jamillazarev/opsinist/blob/main/scripts/new-task.py"
click node_task_board "https://github.com/jamillazarev/opsinist/blob/main/scripts/board.py"
click node_stage_transition "https://github.com/jamillazarev/opsinist/blob/main/scripts/transition.py"
click node_takeover_gate "https://github.com/jamillazarev/opsinist/blob/main/hooks/audit-gate.py"
click node_dependency_review "https://github.com/jamillazarev/opsinist/blob/main/scripts/deps-report.py"
click node_source_register "https://github.com/jamillazarev/opsinist/blob/main/scripts/fetch-source.py"
click node_cost_management "https://github.com/jamillazarev/opsinist/blob/main/cost.md"
click node_release_and_shipping "https://github.com/jamillazarev/opsinist/blob/main/shipping.md"
click node_migration "https://github.com/jamillazarev/opsinist/blob/main/scripts/migrate-layout.py"
click node_commit_guard "https://github.com/jamillazarev/opsinist/blob/main/hooks/audit-gate.py"
click node_project_validators "https://github.com/jamillazarev/opsinist/blob/main/scripts/check-structure.py"
click node_coverage_map "https://github.com/jamillazarev/opsinist/blob/main/scripts/coverage-map.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_advisor,node_agent_skills,node_claude_plugin,node_opencode_plugin,node_pi_extension toneBlue
class node_operations_corpus,node_task_authoring,node_task_records,node_task_board,node_stage_transition,node_git_repository toneAmber
class node_takeover_gate,node_dependency_review,node_source_register,node_cost_management,node_release_and_shipping,node_migration toneMint
class node_commit_guard,node_project_validators,node_coverage_map toneRose
class node_user toneIndigo
```

## Components

### Skills and entrypoints

- [Advisor skill](https://github.com/jamillazarev/opsinist/blob/main/skills/advisor/SKILL.md): `skills/advisor/SKILL.md`
- [Agent skills](https://github.com/jamillazarev/opsinist/tree/main/skills): `skills`
- [Claude plugin](https://github.com/jamillazarev/opsinist/blob/main/.claude-plugin/plugin.json): `.claude-plugin/plugin.json`
- [OpenCode plugin](https://github.com/jamillazarev/opsinist/blob/main/.opencode/plugins/opsinist.js): `.opencode/plugins/opsinist.js`
- [Pi extension](https://github.com/jamillazarev/opsinist/blob/main/.pi/extensions/opsinist.ts): `.pi/extensions/opsinist.ts`

### Work lifecycle

- [Operations chapters](https://github.com/jamillazarev/opsinist/blob/main/starting.md): `starting.md`
- [Task creation](https://github.com/jamillazarev/opsinist/blob/main/scripts/new-task.py): `scripts/new-task.py`
- **Task records**
- [Task board](https://github.com/jamillazarev/opsinist/blob/main/scripts/board.py): `scripts/board.py`
- [Stage transition](https://github.com/jamillazarev/opsinist/blob/main/scripts/transition.py): `scripts/transition.py`

### Governance and evidence

- [Takeover audit](https://github.com/jamillazarev/opsinist/blob/main/hooks/audit-gate.py): `hooks/audit-gate.py`
- [Dependency review](https://github.com/jamillazarev/opsinist/blob/main/scripts/deps-report.py): `scripts/deps-report.py`
- [Source intake](https://github.com/jamillazarev/opsinist/blob/main/scripts/fetch-source.py): `scripts/fetch-source.py`
- [Cost management](https://github.com/jamillazarev/opsinist/blob/main/cost.md): `cost.md`
- [Release practice](https://github.com/jamillazarev/opsinist/blob/main/shipping.md): `shipping.md`
- [Layout migration](https://github.com/jamillazarev/opsinist/blob/main/scripts/migrate-layout.py): `scripts/migrate-layout.py`

### Runtime enforcement

- [Audit hook](https://github.com/jamillazarev/opsinist/blob/main/hooks/audit-gate.py): `hooks/audit-gate.py`
- [Project validators](https://github.com/jamillazarev/opsinist/blob/main/scripts/check-structure.py): `scripts/check-structure.py`
- [Enforcement map](https://github.com/jamillazarev/opsinist/blob/main/scripts/coverage-map.py): `scripts/coverage-map.py`

### Other components

- **Operator**
- **Project repository**

## Connections

- Operator → Advisor skill: asks for work (evidence: `README.md`)
- Advisor skill → Agent skills: routes requests (evidence: `README.md`)
- Agent skills → Operations chapters: loads guidance
- Operator → Task creation: requests a task
- Task creation → Task records: writes task (evidence: `scripts/new-task.py`)
- Task board → Task records: reads tasks (evidence: `scripts/board.py`)
- Stage transition → Task records: updates stage (evidence: `scripts/transition.py`)
- Operator → Takeover audit: starts takeover
- Dependency review → Project repository: inspects dependencies (evidence: `scripts/deps-report.py`)
- Source intake → Project repository: maintains sources (evidence: `scripts/fetch-source.py`)
- Layout migration → Project repository: moves project files (evidence: `scripts/migrate-layout.py`)
- Audit hook → Project repository: checks run state
- Project validators → Project repository: checks structure (evidence: `scripts/check-structure.py`)
- Enforcement map → Project validators: catalogues holders (evidence: `scripts/coverage-map.py`)
- Operator → Cost management: plans spending
- Operator → Release practice: plans release
- Operator → Claude plugin: installs plugin (evidence: `README.md`)
- Operator → OpenCode plugin: uses runtime (evidence: `README.md`)
- Operator → Pi extension: uses runtime (evidence: `README.md`)
