# neurophysica/claude-workflow-template architecture

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

- Interactive diagram: https://gitdiagram.com/neurophysica/claude-workflow-template
- Repository: https://github.com/neurophysica/claude-workflow-template

## Overview

This repository is a documentation template for coordinating Claude Chat, which designs and reviews, with Claude Code, which executes work. The human carries specs and changed files between them; repository files provide durable shared context. The documented loop runs from design to saved spec, execution, review, and progress updates. The graph reflects README-documented relationships only; no source excerpts were provided.

Main entry points: [`docs/dev/specs`](https://github.com/neurophysica/claude-workflow-template/tree/main/docs/dev/specs) (Project Specs), [`CLAUDE.md`](https://github.com/neurophysica/claude-workflow-template/blob/main/CLAUDE.md) (Session Instructions), [`docs/ROADMAP.md`](https://github.com/neurophysica/claude-workflow-template/blob/main/docs/ROADMAP.md) (Progress Tracker), [`docs/dev/DECISIONS.md`](https://github.com/neurophysica/claude-workflow-template/blob/main/docs/dev/DECISIONS.md) (Decision Log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guidance["Session Guidance"]
  node_readme["Template Guide<br/>[README.md]"]
  node_claude_md["Session Instructions<br/>[CLAUDE.md]"]
end

subgraph group_coordination["Shared Coordination"]
  node_workflow["Surface Workflow<br/>[WORKFLOW.md]"]
  node_roadmap["Progress Tracker<br/>[ROADMAP.md]"]
  node_decisions["Decision Log<br/>[DECISIONS.md]"]
end

subgraph group_specs["Specification"]
  node_specs["Project Specs"]
  node_spec_template["Spec Template<br/>[SPEC_TEMPLATE.md]"]
end

node_human(("Project Owner"))
node_chat(("Claude Chat"))
node_code(("Claude Code"))

node_human -->|"starts from"| node_readme
node_code -->|"reads each session"| node_claude_md
node_chat -->|"receives context"| node_claude_md
node_chat -->|"receives context"| node_workflow
node_chat -->|"receives context"| node_decisions
node_chat -->|"receives context"| node_roadmap
node_chat -->|"follows format"| node_spec_template
node_chat -->|"authors specs"| node_specs
node_human -->|"saves specs"| node_specs
node_human -->|"assigns spec"| node_code
node_code -->|"executes by reference"| node_specs
node_code -->|"reports changes"| node_human
node_human -->|"shares changes"| node_chat
node_human -->|"updates progress"| node_roadmap
node_human -->|"records decisions"| node_decisions

click node_readme "https://github.com/neurophysica/claude-workflow-template/blob/main/README.md"
click node_claude_md "https://github.com/neurophysica/claude-workflow-template/blob/main/CLAUDE.md"
click node_workflow "https://github.com/neurophysica/claude-workflow-template/blob/main/docs/dev/WORKFLOW.md"
click node_roadmap "https://github.com/neurophysica/claude-workflow-template/blob/main/docs/ROADMAP.md"
click node_decisions "https://github.com/neurophysica/claude-workflow-template/blob/main/docs/dev/DECISIONS.md"
click node_specs "https://github.com/neurophysica/claude-workflow-template/tree/main/docs/dev/specs"
click node_spec_template "https://github.com/neurophysica/claude-workflow-template/blob/main/docs/dev/specs/SPEC_TEMPLATE.md"

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_readme,node_claude_md toneBlue
class node_workflow,node_roadmap,node_decisions toneAmber
class node_specs,node_spec_template toneMint
class node_human,node_chat,node_code toneIndigo
```

## Components

### Session Guidance

- [Template Guide](https://github.com/neurophysica/claude-workflow-template/blob/main/README.md): `README.md`
- [Session Instructions](https://github.com/neurophysica/claude-workflow-template/blob/main/CLAUDE.md): `CLAUDE.md`

### Shared Coordination

- [Surface Workflow](https://github.com/neurophysica/claude-workflow-template/blob/main/docs/dev/WORKFLOW.md): `docs/dev/WORKFLOW.md`
- [Progress Tracker](https://github.com/neurophysica/claude-workflow-template/blob/main/docs/ROADMAP.md): `docs/ROADMAP.md`
- [Decision Log](https://github.com/neurophysica/claude-workflow-template/blob/main/docs/dev/DECISIONS.md): `docs/dev/DECISIONS.md`

### Specification

- [Project Specs](https://github.com/neurophysica/claude-workflow-template/tree/main/docs/dev/specs): `docs/dev/specs`
- [Spec Template](https://github.com/neurophysica/claude-workflow-template/blob/main/docs/dev/specs/SPEC_TEMPLATE.md): `docs/dev/specs/SPEC_TEMPLATE.md`

### Other components

- **Project Owner**
- **Claude Chat**
- **Claude Code**

## Connections

- Project Owner → Template Guide: starts from (evidence: `README.md`)
- Claude Code → Session Instructions: reads each session (evidence: `README.md`)
- Claude Chat → Session Instructions: receives context (evidence: `README.md`)
- Claude Chat → Surface Workflow: receives context (evidence: `README.md`)
- Claude Chat → Decision Log: receives context (evidence: `README.md`)
- Claude Chat → Progress Tracker: receives context (evidence: `README.md`)
- Claude Chat → Spec Template: follows format (evidence: `README.md`)
- Claude Chat → Project Specs: authors specs (evidence: `README.md`)
- Project Owner → Project Specs: saves specs (evidence: `README.md`)
- Project Owner → Claude Code: assigns spec (evidence: `README.md`)
- Claude Code → Project Specs: executes by reference (evidence: `README.md`)
- Claude Code → Project Owner: reports changes (evidence: `README.md`)
- Project Owner → Claude Chat: shares changes (evidence: `README.md`)
- Project Owner → Progress Tracker: updates progress (evidence: `README.md`)
- Project Owner → Decision Log: records decisions (evidence: `README.md`)
