# lvninety9/soulmate-4 architecture

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

- Interactive diagram: https://gitdiagram.com/lvninety9/soulmate-4
- Repository: https://github.com/lvninety9/soulmate-4

## Overview

Soulmate 4 is a Kilo Code harness for guiding local-model work through small sub-tasks and enforcing handoffs. The principal workflow starts with a user request: Kilo loads project rules, the agent follows the matching protocol, and the sub-task gate blocks further mutations after a handoff unless the user deliberately waives the standing checkpoint. Separate capabilities support bootstrapping, cap enforcement, and two-layer sub-task review. Relationships below follow README statements only; source excerpts were not available, so implementation details beyond those documented are omitted.

Main entry points: [`AGENTS.md`](https://github.com/lvninety9/soulmate-4/blob/master/AGENTS.md) (Project instructions), [`.kilo/plugins/subtask-gate.ts`](https://github.com/lvninety9/soulmate-4/blob/master/.kilo/plugins/subtask-gate.ts) (Sub-task gate), [`scripts/post-commit-subtask-report`](https://github.com/lvninety9/soulmate-4/blob/master/scripts/post-commit-subtask-report) (Post-commit hook), [`scripts/subtask-report.sh`](https://github.com/lvninety9/soulmate-4/blob/master/scripts/subtask-report.sh) (Evidence report)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Work workflow"]
  node_agents["Project instructions<br/>[AGENTS.md]"]
  node_protocols["Workflow protocols"]
  node_primer["Session handoff<br/>[SESSION_PRIMER.md]"]
  node_knowledge["Project knowledge"]
  node_archive["Rules and evidence<br/>[rule-archive.md]"]
end

subgraph group_enforcement["Guardrails"]
  node_gate["Sub-task gate<br/>[subtask-gate.ts]"]
  node_capcheck["Cap enforcement<br/>[check-caps.sh]"]
  node_precommit["Pre-commit check"]
end

subgraph group_review["Sub-task review"]
  node_report["Evidence report<br/>[subtask-report.sh]"]
  node_llmreview["Local-model review"]
  node_range["Boundary resolver<br/>[subtask-range.sh]"]
  node_postcommit["Post-commit hook"]
end

subgraph group_adoption["Project adoption"]
  node_bootstrap["Project bootstrap<br/>[bootstrap.sh]"]
  node_templates["Adoption templates"]
end

node_user(("User"))
node_kilo["Kilo Code"]

node_user -->|"requests work"| node_kilo
node_kilo -->|"loads instructions"| node_agents
node_agents -->|"directs agent"| node_protocols
node_kilo -->|"reads matching step"| node_protocols
node_gate -->|"checks handoff boundary"| node_primer
node_gate -->|"blocks mutation"| node_kilo
node_precommit -->|"enforces caps"| node_capcheck
node_postcommit -->|"runs layer one"| node_report
node_postcommit -->|"runs layer two"| node_llmreview
node_report -->|"resolves boundary"| node_range
node_llmreview -->|"resolves boundary"| node_range
node_bootstrap -->|"copies templates"| node_templates
node_agents -->|"maps project context"| node_knowledge
node_agents -->|"records rule evidence"| node_archive

click node_agents "https://github.com/lvninety9/soulmate-4/blob/master/AGENTS.md"
click node_protocols "https://github.com/lvninety9/soulmate-4/tree/master/wiki/protocols"
click node_primer "https://github.com/lvninety9/soulmate-4/blob/master/wiki/handoffs/SESSION_PRIMER.md"
click node_gate "https://github.com/lvninety9/soulmate-4/blob/master/.kilo/plugins/subtask-gate.ts"
click node_capcheck "https://github.com/lvninety9/soulmate-4/blob/master/scripts/check-caps.sh"
click node_precommit "https://github.com/lvninety9/soulmate-4/blob/master/scripts/pre-commit-check-caps"
click node_report "https://github.com/lvninety9/soulmate-4/blob/master/scripts/subtask-report.sh"
click node_llmreview "https://github.com/lvninety9/soulmate-4/blob/master/scripts/subtask-review-llm.sh"
click node_range "https://github.com/lvninety9/soulmate-4/blob/master/scripts/lib/subtask-range.sh"
click node_postcommit "https://github.com/lvninety9/soulmate-4/blob/master/scripts/post-commit-subtask-report"
click node_bootstrap "https://github.com/lvninety9/soulmate-4/blob/master/scripts/bootstrap.sh"
click node_templates "https://github.com/lvninety9/soulmate-4/tree/master/templates"
click node_knowledge "https://github.com/lvninety9/soulmate-4/blob/master/wiki/PROJECT_BACKGROUND.md"
click node_archive "https://github.com/lvninety9/soulmate-4/blob/master/wiki/rule-archive.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_agents,node_protocols,node_primer,node_knowledge,node_archive,node_user toneBlue
class node_gate,node_capcheck,node_precommit toneAmber
class node_report,node_llmreview,node_range,node_postcommit toneMint
class node_bootstrap,node_templates toneRose
class node_kilo toneIndigo
```

## Components

### Work workflow

- [Project instructions](https://github.com/lvninety9/soulmate-4/blob/master/AGENTS.md): `AGENTS.md`
- [Workflow protocols](https://github.com/lvninety9/soulmate-4/tree/master/wiki/protocols): `wiki/protocols`
- [Session handoff](https://github.com/lvninety9/soulmate-4/blob/master/wiki/handoffs/SESSION_PRIMER.md): `wiki/handoffs/SESSION_PRIMER.md`
- [Project knowledge](https://github.com/lvninety9/soulmate-4/blob/master/wiki/PROJECT_BACKGROUND.md): `wiki/PROJECT_BACKGROUND.md`
- [Rules and evidence](https://github.com/lvninety9/soulmate-4/blob/master/wiki/rule-archive.md): `wiki/rule-archive.md`

### Guardrails

- [Sub-task gate](https://github.com/lvninety9/soulmate-4/blob/master/.kilo/plugins/subtask-gate.ts): `.kilo/plugins/subtask-gate.ts`
- [Cap enforcement](https://github.com/lvninety9/soulmate-4/blob/master/scripts/check-caps.sh): `scripts/check-caps.sh`
- [Pre-commit check](https://github.com/lvninety9/soulmate-4/blob/master/scripts/pre-commit-check-caps): `scripts/pre-commit-check-caps`

### Sub-task review

- [Evidence report](https://github.com/lvninety9/soulmate-4/blob/master/scripts/subtask-report.sh): `scripts/subtask-report.sh`
- [Local-model review](https://github.com/lvninety9/soulmate-4/blob/master/scripts/subtask-review-llm.sh): `scripts/subtask-review-llm.sh`
- [Boundary resolver](https://github.com/lvninety9/soulmate-4/blob/master/scripts/lib/subtask-range.sh): `scripts/lib/subtask-range.sh`
- [Post-commit hook](https://github.com/lvninety9/soulmate-4/blob/master/scripts/post-commit-subtask-report): `scripts/post-commit-subtask-report`

### Project adoption

- [Project bootstrap](https://github.com/lvninety9/soulmate-4/blob/master/scripts/bootstrap.sh): `scripts/bootstrap.sh`
- [Adoption templates](https://github.com/lvninety9/soulmate-4/tree/master/templates): `templates`

### Other components

- **User**
- **Kilo Code**

## Connections

- User → Kilo Code: requests work (evidence: `README.md`)
- Kilo Code → Project instructions: loads instructions (evidence: `README.md`)
- Project instructions → Workflow protocols: directs agent (evidence: `README.md`)
- Kilo Code → Workflow protocols: reads matching step (evidence: `README.md`)
- Sub-task gate → Session handoff: checks handoff boundary (evidence: `README.md`)
- Sub-task gate → Kilo Code: blocks mutation (evidence: `README.md`)
- Pre-commit check → Cap enforcement: enforces caps (evidence: `README.md`)
- Post-commit hook → Evidence report: runs layer one (evidence: `README.md`)
- Post-commit hook → Local-model review: runs layer two (evidence: `README.md`)
- Evidence report → Boundary resolver: resolves boundary (evidence: `README.md`)
- Local-model review → Boundary resolver: resolves boundary (evidence: `README.md`)
- Project bootstrap → Adoption templates: copies templates (evidence: `README.md`)
- Project instructions → Project knowledge: maps project context (evidence: `README.md`)
- Project instructions → Rules and evidence: records rule evidence (evidence: `README.md`)
