# malekbig/taskquoin architecture

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

- Interactive diagram: https://gitdiagram.com/malekbig/taskquoin
- Repository: https://github.com/malekbig/taskquoin
- Video tour (about a minute): https://gitdiagram.com/malekbig/taskquoin/video

## Overview

Taskquoin governs coding-agent runs: the CLI configures and starts a persisted plan–challenge–approval–implementation–verification–review workflow, then requires hash-bound approval before committing. Runtime adapters enforce agent capabilities while running Claude, Codex, OpenCode, or API judges; Git, skills, and optional memory support the run. The README documents the major stages and integrations; sampled source confirms selected wiring, but several runtime and CLI connections are documented rather than inspected in full.

Main entry points: [`packages/application/src/workflow/feature-governed.ts`](https://github.com/malekbig/taskquoin/blob/main/packages/application/src/workflow/feature-governed.ts) (Run state machine), [`apps/cli/src/main.ts`](https://github.com/malekbig/taskquoin/blob/main/apps/cli/src/main.ts) (Taskquoin CLI), [`apps/cli/src/workflow-cli.ts`](https://github.com/malekbig/taskquoin/blob/main/apps/cli/src/workflow-cli.ts) (Workflow commands), [`packages/application/src/ports/runtime-executor.ts`](https://github.com/malekbig/taskquoin/blob/main/packages/application/src/ports/runtime-executor.ts) (Runtime contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and setup"]
  node_cli["Taskquoin CLI<br/>[main.ts]"]
  node_workflow_cli["Workflow commands<br/>[workflow-cli.ts]"]
  node_console["Interactive console<br/>[console.ts]"]
  node_config["Config and gates<br/>[config.ts]"]
end

subgraph group_workflow["Governed workflow"]
  node_governed["Run state machine"]
  node_prepare["Run preparation<br/>[prepare-run.ts]"]
  node_prompts["Workflow prompts<br/>[prompts.ts]"]
  node_git["Git operations<br/>[git.ts]"]
  node_verify["Sandbox and tools<br/>[sandboxed.ts]"]
end

subgraph group_runtime["Agent execution"]
  node_runtime_port["Runtime contract"]
  node_claude["Claude runtime<br/>[executor.ts]"]
  node_codex["Codex runtime<br/>[executor.ts]"]
  node_opencode["OpenCode runtime<br/>[executor.ts]"]
  node_api["API judge runtime<br/>[executor.ts]"]
end

subgraph group_controls["Policy and skills"]
  node_hooks["Claude safety hook<br/>[main.ts]"]
  node_rules["Capability rules<br/>[rules.ts]"]
  node_skills["Skill management<br/>[skills.ts]"]
  node_skill_store["Skill quarantine<br/>[skill-store.ts]"]
end

subgraph group_state["Run state"]
  node_store[("Filesystem run store<br/>[store.ts]")]
  node_memory["Run memory<br/>[claude-mem.ts]"]
end

node_user(("Engineer"))
node_human(("Human approver"))
node_provider(("AI provider"))

node_user -->|"runs commands"| node_cli
node_cli -->|"loads config"| node_config
node_cli -->|"routes workflow"| node_workflow_cli
node_cli -->|"opens console"| node_console
node_workflow_cli -->|"reads workflow"| node_config
node_workflow_cli -->|"starts run"| node_governed
node_workflow_cli -->|"resolves skills"| node_skills
node_workflow_cli -->|"configures memory"| node_memory
node_governed -->|"prepares run"| node_prepare
node_governed -->|"builds tasks"| node_prompts
node_governed -->|"dispatches agents"| node_runtime_port
node_governed -->|"checks and commits"| node_git
node_governed -->|"runs verification"| node_verify
node_human -->|"approves hashes"| node_governed
node_runtime_port -.->|"implemented by"| node_claude
node_runtime_port -.->|"implemented by"| node_codex
node_runtime_port -.->|"implemented by"| node_opencode
node_runtime_port -.->|"implemented by"| node_api
node_claude -->|"registers hook"| node_hooks
node_hooks -->|"evaluates policy"| node_rules
node_claude -->|"scans workspace"| node_verify
node_opencode -->|"runs sandboxed"| node_verify
node_api -.->|"sends judge request"| node_provider
node_skill_store -->|"audits skills"| node_skills
node_cli -->|"creates control store"| node_store
node_governed -.->|"persists run state"| node_store
node_governed -.->|"records summary"| node_memory

click node_cli "https://github.com/malekbig/taskquoin/blob/main/apps/cli/src/main.ts"
click node_workflow_cli "https://github.com/malekbig/taskquoin/blob/main/apps/cli/src/workflow-cli.ts"
click node_console "https://github.com/malekbig/taskquoin/blob/main/apps/cli/src/console.ts"
click node_config "https://github.com/malekbig/taskquoin/blob/main/packages/config/src/config.ts"
click node_governed "https://github.com/malekbig/taskquoin/blob/main/packages/application/src/workflow/feature-governed.ts"
click node_prepare "https://github.com/malekbig/taskquoin/blob/main/packages/application/src/use-cases/prepare-run.ts"
click node_prompts "https://github.com/malekbig/taskquoin/blob/main/packages/application/src/workflow/prompts.ts"
click node_git "https://github.com/malekbig/taskquoin/blob/main/adapters/git/src/git.ts"
click node_verify "https://github.com/malekbig/taskquoin/blob/main/adapters/local-tool/src/sandboxed.ts"
click node_runtime_port "https://github.com/malekbig/taskquoin/blob/main/packages/application/src/ports/runtime-executor.ts"
click node_claude "https://github.com/malekbig/taskquoin/blob/main/adapters/runtime-claude/src/executor.ts"
click node_codex "https://github.com/malekbig/taskquoin/blob/main/adapters/runtime-codex/src/executor.ts"
click node_opencode "https://github.com/malekbig/taskquoin/blob/main/adapters/runtime-opencode/src/executor.ts"
click node_api "https://github.com/malekbig/taskquoin/blob/main/adapters/runtime-api/src/executor.ts"
click node_hooks "https://github.com/malekbig/taskquoin/blob/main/adapters/hooks-claude/src/main.ts"
click node_rules "https://github.com/malekbig/taskquoin/blob/main/packages/rules/src/rules.ts"
click node_skills "https://github.com/malekbig/taskquoin/blob/main/packages/skills/src/skills.ts"
click node_skill_store "https://github.com/malekbig/taskquoin/blob/main/adapters/skill-store/src/skill-store.ts"
click node_store "https://github.com/malekbig/taskquoin/blob/main/adapters/store-fs/src/store.ts"
click node_memory "https://github.com/malekbig/taskquoin/blob/main/adapters/memory-claude-mem/src/claude-mem.ts"

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_cli,node_workflow_cli,node_console,node_config toneBlue
class node_governed,node_prepare,node_prompts,node_git,node_verify toneAmber
class node_runtime_port,node_claude,node_codex,node_opencode,node_api toneMint
class node_hooks,node_rules,node_skills,node_skill_store toneRose
class node_store,node_memory,node_user,node_human,node_provider toneIndigo
```

## Components

### CLI and setup

- [Taskquoin CLI](https://github.com/malekbig/taskquoin/blob/main/apps/cli/src/main.ts): `apps/cli/src/main.ts`
- [Workflow commands](https://github.com/malekbig/taskquoin/blob/main/apps/cli/src/workflow-cli.ts): `apps/cli/src/workflow-cli.ts`
- [Interactive console](https://github.com/malekbig/taskquoin/blob/main/apps/cli/src/console.ts): `apps/cli/src/console.ts`
- [Config and gates](https://github.com/malekbig/taskquoin/blob/main/packages/config/src/config.ts): `packages/config/src/config.ts`

### Governed workflow

- [Run state machine](https://github.com/malekbig/taskquoin/blob/main/packages/application/src/workflow/feature-governed.ts): `packages/application/src/workflow/feature-governed.ts`
- [Run preparation](https://github.com/malekbig/taskquoin/blob/main/packages/application/src/use-cases/prepare-run.ts): `packages/application/src/use-cases/prepare-run.ts`
- [Workflow prompts](https://github.com/malekbig/taskquoin/blob/main/packages/application/src/workflow/prompts.ts): `packages/application/src/workflow/prompts.ts`
- [Git operations](https://github.com/malekbig/taskquoin/blob/main/adapters/git/src/git.ts): `adapters/git/src/git.ts`
- [Sandbox and tools](https://github.com/malekbig/taskquoin/blob/main/adapters/local-tool/src/sandboxed.ts): `adapters/local-tool/src/sandboxed.ts`

### Agent execution

- [Runtime contract](https://github.com/malekbig/taskquoin/blob/main/packages/application/src/ports/runtime-executor.ts): `packages/application/src/ports/runtime-executor.ts`
- [Claude runtime](https://github.com/malekbig/taskquoin/blob/main/adapters/runtime-claude/src/executor.ts): `adapters/runtime-claude/src/executor.ts`
- [Codex runtime](https://github.com/malekbig/taskquoin/blob/main/adapters/runtime-codex/src/executor.ts): `adapters/runtime-codex/src/executor.ts`
- [OpenCode runtime](https://github.com/malekbig/taskquoin/blob/main/adapters/runtime-opencode/src/executor.ts): `adapters/runtime-opencode/src/executor.ts`
- [API judge runtime](https://github.com/malekbig/taskquoin/blob/main/adapters/runtime-api/src/executor.ts): `adapters/runtime-api/src/executor.ts`

### Policy and skills

- [Claude safety hook](https://github.com/malekbig/taskquoin/blob/main/adapters/hooks-claude/src/main.ts): `adapters/hooks-claude/src/main.ts`
- [Capability rules](https://github.com/malekbig/taskquoin/blob/main/packages/rules/src/rules.ts): `packages/rules/src/rules.ts`
- [Skill management](https://github.com/malekbig/taskquoin/blob/main/packages/skills/src/skills.ts): `packages/skills/src/skills.ts`
- [Skill quarantine](https://github.com/malekbig/taskquoin/blob/main/adapters/skill-store/src/skill-store.ts): `adapters/skill-store/src/skill-store.ts`

### Run state

- [Filesystem run store](https://github.com/malekbig/taskquoin/blob/main/adapters/store-fs/src/store.ts): `adapters/store-fs/src/store.ts`
- [Run memory](https://github.com/malekbig/taskquoin/blob/main/adapters/memory-claude-mem/src/claude-mem.ts): `adapters/memory-claude-mem/src/claude-mem.ts`

### Other components

- **Engineer**
- **Human approver**
- **AI provider**

## Connections

- Engineer → Taskquoin CLI: runs commands (evidence: `README.md`)
- Taskquoin CLI → Config and gates: loads config (evidence: `apps/cli/src/main.ts`)
- Taskquoin CLI → Workflow commands: routes workflow (evidence: `apps/cli/src/main.ts`)
- Taskquoin CLI → Interactive console: opens console (evidence: `apps/cli/src/main.ts`)
- Workflow commands → Config and gates: reads workflow (evidence: `apps/cli/src/workflow-cli.ts`)
- Workflow commands → Run state machine: starts run (evidence: `packages/application/src/workflow/feature-governed.ts`)
- Workflow commands → Skill management: resolves skills (evidence: `apps/cli/src/workflow-cli.ts`)
- Workflow commands → Run memory: configures memory (evidence: `apps/cli/src/workflow-cli.ts`)
- Run state machine → Run preparation: prepares run (evidence: `packages/application/src/workflow/feature-governed.ts`)
- Run state machine → Workflow prompts: builds tasks (evidence: `packages/application/src/workflow/feature-governed.ts`)
- Run state machine → Runtime contract: dispatches agents (evidence: `packages/application/src/workflow/feature-governed.ts`)
- Run state machine → Git operations: checks and commits (evidence: `README.md`)
- Run state machine → Sandbox and tools: runs verification (evidence: `README.md`)
- Human approver → Run state machine: approves hashes (evidence: `README.md`)
- Runtime contract → Claude runtime: implemented by
- Runtime contract → Codex runtime: implemented by
- Runtime contract → OpenCode runtime: implemented by
- Runtime contract → API judge runtime: implemented by
- Claude runtime → Claude safety hook: registers hook (evidence: `adapters/runtime-claude/src/executor.ts`)
- Claude safety hook → Capability rules: evaluates policy (evidence: `adapters/hooks-claude/src/main.ts`)
- Claude runtime → Sandbox and tools: scans workspace (evidence: `adapters/runtime-claude/src/executor.ts`)
- OpenCode runtime → Sandbox and tools: runs sandboxed (evidence: `adapters/runtime-opencode/src/executor.ts`)
- API judge runtime → AI provider: sends judge request (evidence: `README.md`)
- Skill quarantine → Skill management: audits skills (evidence: `adapters/skill-store/src/skill-store.ts`)
- Taskquoin CLI → Filesystem run store: creates control store (evidence: `apps/cli/src/main.ts`)
- Run state machine → Filesystem run store: persists run state
- Run state machine → Run memory: records summary (evidence: `README.md`)
