# alatachan/alataflow architecture

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

## Overview

AlataFlow is a structured AI workflow for Claude Code and Codex. Users move a task through planning, execution, verification, review, and finish, with optional experiments and reusable memories/capsules. Claude hooks automate session initialization, progress capture, and context preservation; Codex follows the same lifecycle manually. Runtime modules manage task spaces, checkpoints, memory, experiments, and capsule aging. The graph reflects documented capabilities and shown hook-to-runtime calls; several skill and runtime relationships are documented rather than source-verified.

Main entry points: [`hooks/session-start.js`](https://github.com/alatachan/alataflow/blob/main/hooks/session-start.js) (Session start), [`runtime/space-manager.js`](https://github.com/alatachan/alataflow/blob/main/runtime/space-manager.js) (Task Space), [`skills/workflow/executing/skill.md`](https://github.com/alatachan/alataflow/blob/main/skills/workflow/executing/skill.md) (Execute), [`skills/workflow/planning/skill.md`](https://github.com/alatachan/alataflow/blob/main/skills/workflow/planning/skill.md) (Plan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Task workflow"]
  node_plan["Plan<br/>[skill.md]"]
  node_execute["Execute<br/>[skill.md]"]
  node_verify["Verify<br/>[skill.md]"]
  node_review["Review<br/>[skill.md]"]
  node_finish["Finish<br/>[skill.md]"]
  node_experiment["Experiment loop"]
end

subgraph group_hooks["Claude hooks"]
  node_sessionhook["Session start<br/>[session-start.js]"]
  node_progresshook["Progress capture<br/>[progress-save.js]"]
  node_compacthook["Pre-compact<br/>[pre-compact.js]"]
  node_stophook["Stop verify<br/>[stop-verify.js]"]
  node_scrubber["Sensitive-data scan<br/>[scrubber-rules.js]"]
end

subgraph group_state["Task state"]
  node_taskspace["Task Space<br/>[space-manager.js]"]
  node_checkpoint["Checkpoint"]
  node_progress["Progress writer<br/>[progress-writer.js]"]
  node_init["State initialization<br/>[init.js]"]
end

subgraph group_learning["Memory and evolution"]
  node_memoryload["Memory recall<br/>[memory-loader.js]"]
  node_memorysearch["Memory search<br/>[memory-search.js]"]
  node_memorywrite["Memory writing<br/>[memory-writer.js]"]
  node_capsule["Capsule lifecycle<br/>[capsule-promote.js]"]
  node_decay["Capsule decay<br/>[capsule-decay.js]"]
end

node_user(("AI user"))

node_user -->|"defines task"| node_plan
node_plan -->|"starts work"| node_execute
node_execute -->|"optionally iterates"| node_experiment
node_execute -->|"runs checks"| node_verify
node_verify -->|"passes to"| node_review
node_review -->|"concludes with"| node_finish
node_plan -->|"creates task space"| node_taskspace
node_sessionhook -->|"initializes"| node_init
node_sessionhook -->|"checks spaces"| node_taskspace
node_sessionhook -->|"detects saved state"| node_checkpoint
node_sessionhook -->|"loads memories"| node_memoryload
node_sessionhook -->|"ages capsules"| node_decay
node_progresshook -->|"resolves state root"| node_taskspace
node_progresshook -->|"appends progress"| node_progress
node_compacthook -->|"resolves space"| node_taskspace
node_stophook -->|"resolves state root"| node_taskspace
node_execute -.->|"saves progress"| node_checkpoint
node_user -->|"recalls knowledge"| node_memorysearch
node_user -->|"records memory"| node_memorywrite
node_verify -->|"extracts solution"| node_capsule
node_experiment -.->|"records outcome"| node_memorywrite
node_scrubber -.->|"screens content"| node_memorywrite

click node_plan "https://github.com/alatachan/alataflow/blob/main/skills/workflow/planning/skill.md"
click node_execute "https://github.com/alatachan/alataflow/blob/main/skills/workflow/executing/skill.md"
click node_verify "https://github.com/alatachan/alataflow/blob/main/skills/quality/verification-loop/skill.md"
click node_review "https://github.com/alatachan/alataflow/blob/main/skills/workflow/reviewing/skill.md"
click node_finish "https://github.com/alatachan/alataflow/blob/main/skills/workflow/finishing/skill.md"
click node_taskspace "https://github.com/alatachan/alataflow/blob/main/runtime/space-manager.js"
click node_checkpoint "https://github.com/alatachan/alataflow/blob/main/runtime/checkpoint-manager.js"
click node_progress "https://github.com/alatachan/alataflow/blob/main/runtime/progress-writer.js"
click node_experiment "https://github.com/alatachan/alataflow/blob/main/runtime/experiment-tracker.js"
click node_sessionhook "https://github.com/alatachan/alataflow/blob/main/hooks/session-start.js"
click node_progresshook "https://github.com/alatachan/alataflow/blob/main/hooks/progress-save.js"
click node_compacthook "https://github.com/alatachan/alataflow/blob/main/hooks/pre-compact.js"
click node_stophook "https://github.com/alatachan/alataflow/blob/main/hooks/stop-verify.js"
click node_init "https://github.com/alatachan/alataflow/blob/main/runtime/init.js"
click node_memoryload "https://github.com/alatachan/alataflow/blob/main/runtime/memory-loader.js"
click node_memorysearch "https://github.com/alatachan/alataflow/blob/main/runtime/memory-search.js"
click node_memorywrite "https://github.com/alatachan/alataflow/blob/main/runtime/memory-writer.js"
click node_capsule "https://github.com/alatachan/alataflow/blob/main/runtime/capsule-promote.js"
click node_decay "https://github.com/alatachan/alataflow/blob/main/runtime/capsule-decay.js"
click node_scrubber "https://github.com/alatachan/alataflow/blob/main/runtime/scrubber-rules.js"

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_plan,node_execute,node_verify,node_review,node_finish,node_experiment,node_user toneBlue
class node_sessionhook,node_progresshook,node_compacthook,node_stophook,node_scrubber toneAmber
class node_taskspace,node_checkpoint,node_progress,node_init toneMint
class node_memoryload,node_memorysearch,node_memorywrite,node_capsule,node_decay toneRose
```

## Components

### Task workflow

- [Plan](https://github.com/alatachan/alataflow/blob/main/skills/workflow/planning/skill.md): `skills/workflow/planning/skill.md`
- [Execute](https://github.com/alatachan/alataflow/blob/main/skills/workflow/executing/skill.md): `skills/workflow/executing/skill.md`
- [Verify](https://github.com/alatachan/alataflow/blob/main/skills/quality/verification-loop/skill.md): `skills/quality/verification-loop/skill.md`
- [Review](https://github.com/alatachan/alataflow/blob/main/skills/workflow/reviewing/skill.md): `skills/workflow/reviewing/skill.md`
- [Finish](https://github.com/alatachan/alataflow/blob/main/skills/workflow/finishing/skill.md): `skills/workflow/finishing/skill.md`
- [Experiment loop](https://github.com/alatachan/alataflow/blob/main/runtime/experiment-tracker.js): `runtime/experiment-tracker.js`

### Claude hooks

- [Session start](https://github.com/alatachan/alataflow/blob/main/hooks/session-start.js): `hooks/session-start.js`
- [Progress capture](https://github.com/alatachan/alataflow/blob/main/hooks/progress-save.js): `hooks/progress-save.js`
- [Pre-compact](https://github.com/alatachan/alataflow/blob/main/hooks/pre-compact.js): `hooks/pre-compact.js`
- [Stop verify](https://github.com/alatachan/alataflow/blob/main/hooks/stop-verify.js): `hooks/stop-verify.js`
- [Sensitive-data scan](https://github.com/alatachan/alataflow/blob/main/runtime/scrubber-rules.js): `runtime/scrubber-rules.js`

### Task state

- [Task Space](https://github.com/alatachan/alataflow/blob/main/runtime/space-manager.js): `runtime/space-manager.js`
- [Checkpoint](https://github.com/alatachan/alataflow/blob/main/runtime/checkpoint-manager.js): `runtime/checkpoint-manager.js`
- [Progress writer](https://github.com/alatachan/alataflow/blob/main/runtime/progress-writer.js): `runtime/progress-writer.js`
- [State initialization](https://github.com/alatachan/alataflow/blob/main/runtime/init.js): `runtime/init.js`

### Memory and evolution

- [Memory recall](https://github.com/alatachan/alataflow/blob/main/runtime/memory-loader.js): `runtime/memory-loader.js`
- [Memory search](https://github.com/alatachan/alataflow/blob/main/runtime/memory-search.js): `runtime/memory-search.js`
- [Memory writing](https://github.com/alatachan/alataflow/blob/main/runtime/memory-writer.js): `runtime/memory-writer.js`
- [Capsule lifecycle](https://github.com/alatachan/alataflow/blob/main/runtime/capsule-promote.js): `runtime/capsule-promote.js`
- [Capsule decay](https://github.com/alatachan/alataflow/blob/main/runtime/capsule-decay.js): `runtime/capsule-decay.js`

### Other components

- **AI user**

## Connections

- AI user → Plan: defines task (evidence: `README.md`)
- Plan → Execute: starts work (evidence: `README.md`)
- Execute → Experiment loop: optionally iterates (evidence: `README.md`)
- Execute → Verify: runs checks (evidence: `README.md`)
- Verify → Review: passes to (evidence: `README.md`)
- Review → Finish: concludes with (evidence: `README.md`)
- Plan → Task Space: creates task space (evidence: `README.md`)
- Session start → State initialization: initializes (evidence: `hooks/session-start.js`)
- Session start → Task Space: checks spaces (evidence: `hooks/session-start.js`)
- Session start → Checkpoint: detects saved state (evidence: `hooks/session-start.js`)
- Session start → Memory recall: loads memories (evidence: `hooks/session-start.js`)
- Session start → Capsule decay: ages capsules (evidence: `hooks/session-start.js`)
- Progress capture → Task Space: resolves state root (evidence: `hooks/progress-save.js`)
- Progress capture → Progress writer: appends progress (evidence: `hooks/progress-save.js`)
- Pre-compact → Task Space: resolves space (evidence: `hooks/pre-compact.js`)
- Stop verify → Task Space: resolves state root (evidence: `hooks/stop-verify.js`)
- Execute → Checkpoint: saves progress
- AI user → Memory search: recalls knowledge (evidence: `README.md`)
- AI user → Memory writing: records memory (evidence: `README.md`)
- Verify → Capsule lifecycle: extracts solution (evidence: `README.md`)
- Experiment loop → Memory writing: records outcome
- Sensitive-data scan → Memory writing: screens content
