# funnel-futurist/ff-aios-starter architecture

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

- Interactive diagram: https://gitdiagram.com/funnel-futurist/ff-aios-starter
- Repository: https://github.com/funnel-futurist/ff-aios-starter
- Video tour (about a minute): https://gitdiagram.com/funnel-futurist/ff-aios-starter/video

## Overview

AIOS is a user-owned Claude Code operating system for a business: repository files retain context, decisions, procedures, and work products, while named skills guide recurring tasks. The main path is onboarding, building business context, then using a skill to act on a real task and review its output. The workspace, quality controls, and setup/maintenance tooling support that loop. The README documents capabilities whose source wiring was not sampled; those are shown as separate branches where their paths are supported, without assuming internal call chains.

Main entry points: [`scripts/aios/aios.py`](https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aios.py) (AIOS command line), [`.claude/skills`](https://github.com/funnel-futurist/ff-aios-starter/tree/main/.claude/skills) (Task skills), [`scripts/aios/aioslib/workspace.py`](https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aioslib/workspace.py) (Workspace Kit), [`.claude/skills/onboard_wizard/SKILL.md`](https://github.com/funnel-futurist/ff-aios-starter/blob/main/.claude/skills/onboard_wizard/SKILL.md) (Onboarding wizard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator workflow"]
  node_constitution["Session constitution<br/>[CLAUDE.md]"]
  node_onboard["Onboarding wizard<br/>[SKILL.md]"]
  node_skills["Task skills<br/>[skills]"]
  node_unstuck["Unstuck protocol"]
end

subgraph group_workspace["Business workspace"]
  node_foundations["Business foundations"]
  node_deliverables["Work deliverables"]
  node_journey["Customer journey"]
  node_communications["Operating records"]
  node_projects["Projects"]
end

subgraph group_quality["Quality and review"]
  node_quality_controls["QC preferences and rubric"]
  node_pr_review["PR static checks<br/>[static_checks.mjs]"]
  node_skill_contract["Skill contract checks<br/>[verify_skills.py]"]
end

subgraph group_runtime["Install and governance"]
  node_aios_cli["AIOS command line<br/>[aios.py]"]
  node_release["Release manifests<br/>[release.py]"]
  node_installer["Install lifecycle<br/>[install.py]"]
  node_workspace_kit["Workspace Kit<br/>[workspace.py]"]
  node_boundaries["Role boundaries<br/>[boundary.py]"]
end

subgraph group_integrations["External tools"]
  node_claude["Claude Code"]
  node_vault["Obsidian vault"]
  node_git_repos[("Git repositories")]
end

node_operator(("Business operator"))

node_operator -->|"works in"| node_claude
node_claude -->|"reads first"| node_constitution
node_operator -->|"starts with"| node_onboard
node_claude -->|"runs skill"| node_onboard
node_onboard -->|"loads context"| node_foundations
node_operator -->|"selects task"| node_skills
node_claude -->|"runs skill"| node_skills
node_skills -->|"uses context"| node_foundations
node_skills -->|"produces work"| node_deliverables
node_operator -->|"reviews against"| node_quality_controls
node_operator -->|"consults when stuck"| node_unstuck
node_operator -->|"tracks progress"| node_journey
node_operator -->|"records decisions"| node_communications
node_operator -->|"organizes work"| node_projects
node_pr_review -.->|"checks changes"| node_quality_controls
node_skill_contract -->|"validates structure"| node_skills
node_operator -->|"runs commands"| node_aios_cli
node_aios_cli -->|"checks release"| node_release
node_aios_cli -->|"installs or verifies"| node_installer
node_aios_cli -->|"manages workspace"| node_workspace_kit
node_aios_cli -->|"checks role"| node_boundaries
node_workspace_kit -->|"builds vault"| node_vault
node_workspace_kit -->|"syncs repositories"| node_git_repos

click node_constitution "https://github.com/funnel-futurist/ff-aios-starter/blob/main/CLAUDE.md"
click node_onboard "https://github.com/funnel-futurist/ff-aios-starter/blob/main/.claude/skills/onboard_wizard/SKILL.md"
click node_skills "https://github.com/funnel-futurist/ff-aios-starter/tree/main/.claude/skills"
click node_unstuck "https://github.com/funnel-futurist/ff-aios-starter/blob/main/docs/UNSTUCK_PROTOCOL.md"
click node_foundations "https://github.com/funnel-futurist/ff-aios-starter/tree/main/01_Foundations"
click node_deliverables "https://github.com/funnel-futurist/ff-aios-starter/tree/main/02_Deliverables"
click node_journey "https://github.com/funnel-futurist/ff-aios-starter/tree/main/04_Customer_Journey"
click node_communications "https://github.com/funnel-futurist/ff-aios-starter/tree/main/06_Communication"
click node_projects "https://github.com/funnel-futurist/ff-aios-starter/tree/main/11_Projects"
click node_quality_controls "https://github.com/funnel-futurist/ff-aios-starter/tree/main/03_Quality_Control"
click node_pr_review "https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/pr_review/static_checks.mjs"
click node_skill_contract "https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/verify_skills.py"
click node_aios_cli "https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aios.py"
click node_release "https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aioslib/release.py"
click node_installer "https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aioslib/install.py"
click node_workspace_kit "https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aioslib/workspace.py"
click node_boundaries "https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aioslib/boundary.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_constitution,node_onboard,node_skills,node_unstuck toneBlue
class node_foundations,node_deliverables,node_journey,node_communications,node_projects toneAmber
class node_quality_controls,node_pr_review,node_skill_contract toneMint
class node_aios_cli,node_release,node_installer,node_workspace_kit,node_boundaries toneRose
class node_claude,node_vault,node_git_repos,node_operator toneIndigo
```

## Components

### Operator workflow

- [Session constitution](https://github.com/funnel-futurist/ff-aios-starter/blob/main/CLAUDE.md): `CLAUDE.md`
- [Onboarding wizard](https://github.com/funnel-futurist/ff-aios-starter/blob/main/.claude/skills/onboard_wizard/SKILL.md): `.claude/skills/onboard_wizard/SKILL.md`
- [Task skills](https://github.com/funnel-futurist/ff-aios-starter/tree/main/.claude/skills): `.claude/skills`
- [Unstuck protocol](https://github.com/funnel-futurist/ff-aios-starter/blob/main/docs/UNSTUCK_PROTOCOL.md): `docs/UNSTUCK_PROTOCOL.md`

### Business workspace

- [Business foundations](https://github.com/funnel-futurist/ff-aios-starter/tree/main/01_Foundations): `01_Foundations`
- [Work deliverables](https://github.com/funnel-futurist/ff-aios-starter/tree/main/02_Deliverables): `02_Deliverables`
- [Customer journey](https://github.com/funnel-futurist/ff-aios-starter/tree/main/04_Customer_Journey): `04_Customer_Journey`
- [Operating records](https://github.com/funnel-futurist/ff-aios-starter/tree/main/06_Communication): `06_Communication`
- [Projects](https://github.com/funnel-futurist/ff-aios-starter/tree/main/11_Projects): `11_Projects`

### Quality and review

- [QC preferences and rubric](https://github.com/funnel-futurist/ff-aios-starter/tree/main/03_Quality_Control): `03_Quality_Control`
- [PR static checks](https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/pr_review/static_checks.mjs): `scripts/pr_review/static_checks.mjs`
- [Skill contract checks](https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/verify_skills.py): `scripts/verify_skills.py`

### Install and governance

- [AIOS command line](https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aios.py): `scripts/aios/aios.py`
- [Release manifests](https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aioslib/release.py): `scripts/aios/aioslib/release.py`
- [Install lifecycle](https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aioslib/install.py): `scripts/aios/aioslib/install.py`
- [Workspace Kit](https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aioslib/workspace.py): `scripts/aios/aioslib/workspace.py`
- [Role boundaries](https://github.com/funnel-futurist/ff-aios-starter/blob/main/scripts/aios/aioslib/boundary.py): `scripts/aios/aioslib/boundary.py`

### External tools

- **Claude Code**
- **Obsidian vault**
- **Git repositories**

### Other components

- **Business operator**

## Connections

- Business operator → Claude Code: works in
- Claude Code → Session constitution: reads first
- Business operator → Onboarding wizard: starts with
- Claude Code → Onboarding wizard: runs skill
- Onboarding wizard → Business foundations: loads context
- Business operator → Task skills: selects task
- Claude Code → Task skills: runs skill
- Task skills → Business foundations: uses context
- Task skills → Work deliverables: produces work
- Business operator → QC preferences and rubric: reviews against
- Business operator → Unstuck protocol: consults when stuck
- Business operator → Customer journey: tracks progress
- Business operator → Operating records: records decisions
- Business operator → Projects: organizes work
- PR static checks → QC preferences and rubric: checks changes
- Skill contract checks → Task skills: validates structure
- Business operator → AIOS command line: runs commands
- AIOS command line → Release manifests: checks release
- AIOS command line → Install lifecycle: installs or verifies
- AIOS command line → Workspace Kit: manages workspace
- AIOS command line → Role boundaries: checks role
- Workspace Kit → Obsidian vault: builds vault
- Workspace Kit → Git repositories: syncs repositories