# ahamedumar15/crunchflow architecture

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

- Interactive diagram: https://gitdiagram.com/ahamedumar15/crunchflow
- Repository: https://github.com/ahamedumar15/crunchflow

## Overview

CrunchFlow is a Claude Code plugin for governed AI software development. Its main workflow turns a user’s idea into a brief, competing designs, a merged and scored spec, human approval, scoped implementation, adversarial QA, and a traceable release report. A separate governed-session workflow applies scoped write controls and auditing to existing-repository work. The graph reflects documented workflow stages and sampled module references; internal links for unsampled agent and command behavior are limited to README evidence.

Main entry points: [`crunchflow/scripts/cf_state.py`](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_state.py) (Run state), [`crunchflow/scripts/cf_common.py`](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_common.py) (Shared helpers), [`crunchflow/agents/qa.md`](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/qa.md) (QA), [`crunchflow/scripts/cf_trace.py`](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_trace.py) (Traceability)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Build workflow"]
  node_crunch["Pipeline command<br/>[crunch.md]"]
  node_analyst["Analyst<br/>[analyst.md]"]
  node_architects["Architects<br/>[architect.md]"]
  node_judge["Judge<br/>[judge.md]"]
  node_planner["Planner<br/>[planner.md]"]
  node_developer["Developer<br/>[developer.md]"]
  node_qa["QA<br/>[qa.md]"]
  node_release["Release<br/>[release.md]"]
end

subgraph group_governance["Governance"]
  node_approval["Approval command<br/>[crunch-approve.md]"]
  node_govern["Govern command<br/>[govern.md]"]
  node_govern_end["Session close<br/>[govern-end.md]"]
  node_gate["Write gate<br/>[gate.py]"]
  node_state[("Run state<br/>[cf_state.py]")]
end

subgraph group_analysis["Context and verification"]
  node_brief["Agent briefings<br/>[cf_brief.py]"]
  node_handoff["Structured handoffs<br/>[cf_handoff.py]"]
  node_index["Context index<br/>[cf_index.py]"]
  node_lint["Spec scoring<br/>[cf_lint.py]"]
  node_trace["Traceability<br/>[cf_trace.py]"]
  node_mutate["Mutation check<br/>[mutate.py]"]
  node_common["Shared helpers<br/>[cf_common.py]"]
end

subgraph group_reporting["Run reporting"]
  node_events["Audit event model<br/>[cf_events.py]"]
  node_center["Live storyboard<br/>[cf_center.py]"]
  node_dashboard["Run dashboard<br/>[dashboard.py]"]
  node_ui["Shared UI system<br/>[cf_ui.py]"]
end

node_user(("User"))

node_user -->|"starts pipeline"| node_crunch
node_crunch -->|"briefs idea"| node_analyst
node_analyst -->|"provides brief"| node_architects
node_architects -->|"compete for merge"| node_judge
node_judge -->|"scores spec"| node_lint
node_user -->|"reviews and approves"| node_approval
node_approval -->|"records spec hash"| node_state
node_approval -->|"unblocks planning"| node_planner
node_planner -->|"defines tasks and scope"| node_developer
node_developer -->|"submits implementation"| node_qa
node_qa -->|"spot-checks tests"| node_mutate
node_qa -->|"returns failures"| node_developer
node_qa -->|"provides QA evidence"| node_trace
node_trace -->|"provides trace results"| node_release
node_release -->|"writes run report"| node_dashboard
node_release -->|"writes storyboard"| node_center
node_user -->|"starts session"| node_govern
node_govern -->|"sets write scope"| node_gate
node_gate -->|"records decisions"| node_state
node_user -->|"closes session"| node_govern_end
node_govern_end -->|"summarizes session"| node_state
node_state -->|"supplies governance state"| node_gate
node_crunch -.->|"prepares agent context"| node_brief
node_brief -->|"uses indexed context"| node_index
node_state -->|"checks spec stage"| node_lint
node_state -.->|"supplies task state"| node_trace
node_state -->|"supplies run record"| node_events
node_events -->|"serves event views"| node_center
node_events -->|"supplies audit model"| node_dashboard
node_center -->|"imports styles"| node_ui
node_dashboard -->|"imports styles"| node_ui
node_state -->|"uses shared helpers"| node_common
node_brief -->|"uses shared helpers"| node_common
node_handoff -->|"uses shared helpers"| node_common
node_index -->|"uses shared helpers"| node_common
node_lint -->|"uses shared helpers"| node_common
node_trace -->|"uses symbol index"| node_index
node_mutate -->|"uses shared helpers"| node_common

click node_crunch "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/commands/crunch.md"
click node_analyst "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/analyst.md"
click node_architects "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/architect.md"
click node_judge "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/judge.md"
click node_approval "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/commands/crunch-approve.md"
click node_planner "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/planner.md"
click node_developer "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/developer.md"
click node_qa "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/qa.md"
click node_release "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/release.md"
click node_govern "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/commands/govern.md"
click node_govern_end "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/commands/govern-end.md"
click node_gate "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/hooks/gate.py"
click node_state "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_state.py"
click node_brief "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_brief.py"
click node_handoff "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_handoff.py"
click node_index "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_index.py"
click node_lint "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_lint.py"
click node_trace "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_trace.py"
click node_mutate "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/mutate.py"
click node_common "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_common.py"
click node_events "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_events.py"
click node_center "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_center.py"
click node_dashboard "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/dashboard.py"
click node_ui "https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_ui.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_crunch,node_analyst,node_architects,node_judge,node_planner,node_developer,node_qa,node_release,node_user toneBlue
class node_approval,node_govern,node_govern_end,node_gate,node_state toneAmber
class node_brief,node_handoff,node_index,node_lint,node_trace,node_mutate,node_common toneMint
class node_events,node_center,node_dashboard,node_ui toneRose
```

## Components

### Build workflow

- [Pipeline command](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/commands/crunch.md): `crunchflow/commands/crunch.md`
- [Analyst](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/analyst.md): `crunchflow/agents/analyst.md`
- [Architects](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/architect.md): `crunchflow/agents/architect.md`
- [Judge](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/judge.md): `crunchflow/agents/judge.md`
- [Planner](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/planner.md): `crunchflow/agents/planner.md`
- [Developer](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/developer.md): `crunchflow/agents/developer.md`
- [QA](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/qa.md): `crunchflow/agents/qa.md`
- [Release](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/agents/release.md): `crunchflow/agents/release.md`

### Governance

- [Approval command](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/commands/crunch-approve.md): `crunchflow/commands/crunch-approve.md`
- [Govern command](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/commands/govern.md): `crunchflow/commands/govern.md`
- [Session close](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/commands/govern-end.md): `crunchflow/commands/govern-end.md`
- [Write gate](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/hooks/gate.py): `crunchflow/hooks/gate.py`
- [Run state](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_state.py): `crunchflow/scripts/cf_state.py`

### Context and verification

- [Agent briefings](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_brief.py): `crunchflow/scripts/cf_brief.py`
- [Structured handoffs](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_handoff.py): `crunchflow/scripts/cf_handoff.py`
- [Context index](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_index.py): `crunchflow/scripts/cf_index.py`
- [Spec scoring](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_lint.py): `crunchflow/scripts/cf_lint.py`
- [Traceability](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_trace.py): `crunchflow/scripts/cf_trace.py`
- [Mutation check](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/mutate.py): `crunchflow/scripts/mutate.py`
- [Shared helpers](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_common.py): `crunchflow/scripts/cf_common.py`

### Run reporting

- [Audit event model](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_events.py): `crunchflow/scripts/cf_events.py`
- [Live storyboard](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_center.py): `crunchflow/scripts/cf_center.py`
- [Run dashboard](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/dashboard.py): `crunchflow/scripts/dashboard.py`
- [Shared UI system](https://github.com/ahamedumar15/crunchflow/blob/main/crunchflow/scripts/cf_ui.py): `crunchflow/scripts/cf_ui.py`

### Other components

- **User**

## Connections

- User → Pipeline command: starts pipeline (evidence: `README.md`)
- Pipeline command → Analyst: briefs idea (evidence: `README.md`)
- Analyst → Architects: provides brief (evidence: `README.md`)
- Architects → Judge: compete for merge (evidence: `README.md`)
- Judge → Spec scoring: scores spec (evidence: `README.md`)
- User → Approval command: reviews and approves (evidence: `README.md`)
- Approval command → Run state: records spec hash (evidence: `README.md`)
- Approval command → Planner: unblocks planning (evidence: `README.md`)
- Planner → Developer: defines tasks and scope (evidence: `README.md`)
- Developer → QA: submits implementation (evidence: `README.md`)
- QA → Mutation check: spot-checks tests (evidence: `README.md`)
- QA → Developer: returns failures (evidence: `README.md`)
- QA → Traceability: provides QA evidence (evidence: `README.md`)
- Traceability → Release: provides trace results (evidence: `README.md`)
- Release → Run dashboard: writes run report (evidence: `README.md`)
- Release → Live storyboard: writes storyboard (evidence: `README.md`)
- User → Govern command: starts session (evidence: `README.md`)
- Govern command → Write gate: sets write scope (evidence: `README.md`)
- Write gate → Run state: records decisions (evidence: `README.md`)
- User → Session close: closes session (evidence: `README.md`)
- Session close → Run state: summarizes session (evidence: `README.md`)
- Run state → Write gate: supplies governance state (evidence: `README.md`)
- Pipeline command → Agent briefings: prepares agent context
- Agent briefings → Context index: uses indexed context (evidence: `crunchflow/scripts/cf_brief.py`)
- Run state → Spec scoring: checks spec stage (evidence: `crunchflow/scripts/cf_state.py`)
- Run state → Traceability: supplies task state
- Run state → Audit event model: supplies run record (evidence: `crunchflow/scripts/cf_events.py`)
- Audit event model → Live storyboard: serves event views (evidence: `crunchflow/scripts/cf_center.py`)
- Audit event model → Run dashboard: supplies audit model (evidence: `crunchflow/scripts/dashboard.py`)
- Live storyboard → Shared UI system: imports styles (evidence: `crunchflow/scripts/cf_center.py`)
- Run dashboard → Shared UI system: imports styles (evidence: `crunchflow/scripts/dashboard.py`)
- Run state → Shared helpers: uses shared helpers (evidence: `crunchflow/scripts/cf_state.py`)
- Agent briefings → Shared helpers: uses shared helpers (evidence: `crunchflow/scripts/cf_brief.py`)
- Structured handoffs → Shared helpers: uses shared helpers (evidence: `crunchflow/scripts/cf_handoff.py`)
- Context index → Shared helpers: uses shared helpers (evidence: `crunchflow/scripts/cf_index.py`)
- Spec scoring → Shared helpers: uses shared helpers (evidence: `crunchflow/scripts/cf_lint.py`)
- Traceability → Context index: uses symbol index (evidence: `crunchflow/scripts/cf_trace.py`)
- Mutation check → Shared helpers: uses shared helpers (evidence: `crunchflow/scripts/mutate.py`)
