# samykabu/sanduq architecture

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

- Interactive diagram: https://gitdiagram.com/samykabu/sanduq
- Repository: https://github.com/samykabu/sanduq

## Overview

Sanduq packages portable agent skills and Spec Kit extensions, with the managed workflow as its central product path: an issue is scoped, implemented by an orchestrator and workers, verified, documented, and delivered through a pull request. Separate capabilities include lifecycle QA, audience-specific manuals, diagrams, project synchronization, and background task delegation. The README documents these product branches, but the supplied tree and source excerpts do not expose every extension or dispatcher detail; uncertain internal connections are therefore omitted.

Main entry points: [`extensions/workflow/scripts/workflow.py`](https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/workflow.py) (Workflow dispatcher), [`extensions/scope/scripts/scope.py`](https://github.com/samykabu/sanduq/blob/main/extensions/scope/scripts/scope.py) (Issue scoping), [`extensions/workflow/scripts/delegate_dispatch.py`](https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/delegate_dispatch.py) (Agent delegation), [`extensions/user-manual/scripts/init_manual.py`](https://github.com/samykabu/sanduq/blob/main/extensions/user-manual/scripts/init_manual.py) (Manual setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_managed["Managed workflow"]
  node_workflow["Workflow dispatcher<br/>[workflow.py]"]
  node_scope["Issue scoping<br/>[scope.py]"]
  node_clarification["Clarification<br/>[clarification.py]"]
  node_accept_plan["Plan acceptance<br/>[accept_plan.py]"]
  node_delegation["Agent delegation"]
  node_progress["Progress reporting<br/>[progress.py]"]
  node_task_issues["Task issues<br/>[task_issues.py]"]
end

subgraph group_governance["Project governance"]
  node_assure["QA lifecycle<br/>[assure_init.py]"]
end

subgraph group_skills["Portable skills"]
  node_delegate_skill["Task delegation skill<br/>[delegate.mjs]"]
  node_manual_init["Manual setup<br/>[init_manual.py]"]
  node_manual_audit["Manual audit<br/>[audit_manual.py]"]
  node_manual_build["Manual editions<br/>[build_manual.py]"]
  node_illustrate["Diagram export<br/>[export_diagram.py]"]
end

subgraph group_delivery["Verification and delivery"]
  node_ci_gate["Evidence CI gate<br/>[ci_gate.py]"]
end

node_developer(("Engineer"))
node_github_issue(("GitHub issue"))
node_github{{"GitHub"}}
node_github_project[("GitHub Projects")]
node_pull_request(("Pull request"))
node_ci{{"Project CI"}}

node_developer -->|"files issue"| node_github_issue
node_github_issue -->|"starts scoping"| node_scope
node_scope -->|"reads issue"| node_github
node_scope -->|"syncs project"| node_github_project
node_scope -->|"provides scope"| node_workflow
node_workflow -->|"requests answers"| node_clarification
node_workflow -->|"accepts plan"| node_accept_plan
node_workflow -->|"dispatches work"| node_delegation
node_delegation -.->|"starts delegated task"| node_delegate_skill
node_workflow -->|"tracks tasks"| node_task_issues
node_workflow -->|"reports progress"| node_progress
node_workflow -->|"coordinates QA"| node_assure
node_workflow -->|"checks evidence"| node_ci_gate
node_ci -->|"supplies run evidence"| node_ci_gate
node_workflow -->|"checks documentation"| node_manual_audit
node_manual_init -->|"prepares build inputs"| node_manual_build
node_manual_build -.->|"publishes PR preview"| node_github
node_developer -->|"requests manual"| node_manual_init
node_developer -->|"requests diagram"| node_illustrate
node_workflow -->|"opens delivery PR"| node_pull_request
node_pull_request -->|"enters review and merge"| node_github

click node_workflow "https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/workflow.py"
click node_scope "https://github.com/samykabu/sanduq/blob/main/extensions/scope/scripts/scope.py"
click node_clarification "https://github.com/samykabu/sanduq/blob/main/extensions/scope/scripts/clarification.py"
click node_accept_plan "https://github.com/samykabu/sanduq/blob/main/extensions/scope/scripts/accept_plan.py"
click node_delegation "https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/delegate_dispatch.py"
click node_delegate_skill "https://github.com/samykabu/sanduq/blob/main/skills/agent-tools/skills/delegate-task/delegate.mjs"
click node_progress "https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/progress.py"
click node_task_issues "https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/task_issues.py"
click node_assure "https://github.com/samykabu/sanduq/blob/main/extensions/assure/scripts/assure_init.py"
click node_ci_gate "https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/ci_gate.py"
click node_manual_init "https://github.com/samykabu/sanduq/blob/main/extensions/user-manual/scripts/init_manual.py"
click node_manual_audit "https://github.com/samykabu/sanduq/blob/main/extensions/user-manual/scripts/audit_manual.py"
click node_manual_build "https://github.com/samykabu/sanduq/blob/main/extensions/user-manual/scripts/build_manual.py"
click node_illustrate "https://github.com/samykabu/sanduq/blob/main/extensions/illustrate/skill/scripts/export_diagram.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_workflow,node_scope,node_clarification,node_accept_plan,node_delegation,node_progress,node_task_issues toneBlue
class node_assure,node_github_project toneAmber
class node_delegate_skill,node_manual_init,node_manual_audit,node_manual_build,node_illustrate,node_pull_request toneMint
class node_ci_gate toneRose
class node_developer,node_github_issue,node_github,node_ci toneIndigo
```

## Components

### Managed workflow

- [Workflow dispatcher](https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/workflow.py): `extensions/workflow/scripts/workflow.py`
- [Issue scoping](https://github.com/samykabu/sanduq/blob/main/extensions/scope/scripts/scope.py): `extensions/scope/scripts/scope.py`
- [Clarification](https://github.com/samykabu/sanduq/blob/main/extensions/scope/scripts/clarification.py): `extensions/scope/scripts/clarification.py`
- [Plan acceptance](https://github.com/samykabu/sanduq/blob/main/extensions/scope/scripts/accept_plan.py): `extensions/scope/scripts/accept_plan.py`
- [Agent delegation](https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/delegate_dispatch.py): `extensions/workflow/scripts/delegate_dispatch.py`
- [Progress reporting](https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/progress.py): `extensions/workflow/scripts/progress.py`
- [Task issues](https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/task_issues.py): `extensions/workflow/scripts/task_issues.py`

### Project governance

- [QA lifecycle](https://github.com/samykabu/sanduq/blob/main/extensions/assure/scripts/assure_init.py): `extensions/assure/scripts/assure_init.py`

### Portable skills

- [Task delegation skill](https://github.com/samykabu/sanduq/blob/main/skills/agent-tools/skills/delegate-task/delegate.mjs): `skills/agent-tools/skills/delegate-task/delegate.mjs`
- [Manual setup](https://github.com/samykabu/sanduq/blob/main/extensions/user-manual/scripts/init_manual.py): `extensions/user-manual/scripts/init_manual.py`
- [Manual audit](https://github.com/samykabu/sanduq/blob/main/extensions/user-manual/scripts/audit_manual.py): `extensions/user-manual/scripts/audit_manual.py`
- [Manual editions](https://github.com/samykabu/sanduq/blob/main/extensions/user-manual/scripts/build_manual.py): `extensions/user-manual/scripts/build_manual.py`
- [Diagram export](https://github.com/samykabu/sanduq/blob/main/extensions/illustrate/skill/scripts/export_diagram.py): `extensions/illustrate/skill/scripts/export_diagram.py`

### Verification and delivery

- [Evidence CI gate](https://github.com/samykabu/sanduq/blob/main/extensions/workflow/scripts/ci_gate.py): `extensions/workflow/scripts/ci_gate.py`

### Other components

- **Engineer**
- **GitHub issue**
- **GitHub**
- **GitHub Projects**
- **Pull request**
- **Project CI**

## Connections

- Engineer → GitHub issue: files issue
- GitHub issue → Issue scoping: starts scoping
- Issue scoping → GitHub: reads issue
- Issue scoping → GitHub Projects: syncs project
- Issue scoping → Workflow dispatcher: provides scope
- Workflow dispatcher → Clarification: requests answers
- Workflow dispatcher → Plan acceptance: accepts plan
- Workflow dispatcher → Agent delegation: dispatches work
- Agent delegation → Task delegation skill: starts delegated task
- Workflow dispatcher → Task issues: tracks tasks
- Workflow dispatcher → Progress reporting: reports progress
- Workflow dispatcher → QA lifecycle: coordinates QA
- Workflow dispatcher → Evidence CI gate: checks evidence
- Project CI → Evidence CI gate: supplies run evidence
- Workflow dispatcher → Manual audit: checks documentation
- Manual setup → Manual editions: prepares build inputs
- Manual editions → GitHub: publishes PR preview
- Engineer → Manual setup: requests manual
- Engineer → Diagram export: requests diagram
- Workflow dispatcher → Pull request: opens delivery PR
- Pull request → GitHub: enters review and merge