# serenbeam/khwami architecture

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

- Interactive diagram: https://gitdiagram.com/serenbeam/khwami
- Repository: https://github.com/serenbeam/khwami

## Overview

KHWAMI is both a documentation-first collection of reusable engineering guidance and a small CLI for bounded CREATE and ADOPT workflows. The primary runtime path takes a request and target through context resolution, workflow-specific analysis and proposal, permission and approved-scope checks, execution, validation, and a terminal report. CREATE can write explicitly approved files; ADOPT is currently read-only. The README establishes the guidance and repository-intelligence branches. Edges reflect README statements or shown/indexed references; unsampled implementation details are not inferred.

Main entry points: [`src/core/workflow-controller.js`](https://github.com/serenbeam/khwami/blob/master/src/core/workflow-controller.js) (Workflow Controller), [`src/cli/index.js`](https://github.com/serenbeam/khwami/blob/master/src/cli/index.js) (CLI Entry), [`src/core/bootstrap.js`](https://github.com/serenbeam/khwami/blob/master/src/core/bootstrap.js) (Core Bootstrap), [`src/core/create-analysis.js`](https://github.com/serenbeam/khwami/blob/master/src/core/create-analysis.js) (CREATE Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Routing"]
  node_cli_entry["CLI Entry<br/>[index.js]"]
  node_bootstrap["Core Bootstrap<br/>[bootstrap.js]"]
  node_context["Context Resolution"]
  node_controller["Workflow Controller"]
  node_terminal_result["Terminal Result<br/>[index.js]"]
end

subgraph group_create["CREATE Lifecycle"]
  node_create_analysis["CREATE Analysis<br/>[create-analysis.js]"]
  node_project_shape["Project Shape"]
  node_create_proposal["CREATE Proposal<br/>[create-proposal.js]"]
  node_create_actions["CREATE Actions"]
  node_create_execution["CREATE Execution"]
  node_create_validation["CREATE Validation"]
end

subgraph group_adopt["ADOPT Lifecycle"]
  node_adopt_analysis["ADOPT Analysis<br/>[adopt-analysis.js]"]
  node_adopt_requirement["Objective Reconciliation"]
  node_adopt_proposal["ADOPT Proposal<br/>[adopt-proposal.js]"]
  node_adopt_actions["ADOPT Actions"]
  node_adopt_execution["ADOPT Execution<br/>[adopt-execution.js]"]
  node_adopt_validation["ADOPT Validation"]
end

subgraph group_safety["Scope and Validation"]
  node_approved_scope["Approved Scope<br/>[approved-scope.js]"]
  node_change_detection["Change Detection"]
end

subgraph group_knowledge["Guidance and Intelligence"]
  node_agent_standards["Collaboration Standards"]
  node_instructions["Reusable Instructions"]
  node_prompts["Engineering Prompts"]
  node_repo_intelligence["Repository Intelligence"]
  node_planning_state["Planning and State<br/>[WORKSPACE_STATE.md]"]
end

node_engineer(("Engineer"))

node_engineer -->|"submits request"| node_cli_entry
node_cli_entry -->|"initializes core"| node_bootstrap
node_bootstrap -->|"initializes"| node_context
node_bootstrap -->|"initializes"| node_controller
node_cli_entry -->|"routes workflow"| node_controller
node_controller -->|"resolves context"| node_context
node_controller -->|"analyzes CREATE"| node_create_analysis
node_create_analysis -->|"derives shape"| node_project_shape
node_controller -->|"analyzes ADOPT"| node_adopt_analysis
node_controller -->|"reconciles objective"| node_adopt_requirement
node_controller -->|"builds proposal"| node_create_proposal
node_create_proposal -->|"derives actions"| node_create_actions
node_controller -->|"builds proposal"| node_adopt_proposal
node_controller -->|"derives actions"| node_adopt_actions
node_controller -->|"captures baseline"| node_change_detection
node_controller -->|"prepares scope"| node_approved_scope
node_controller -->|"executes CREATE"| node_create_execution
node_controller -->|"executes ADOPT"| node_adopt_execution
node_controller -->|"validates CREATE"| node_create_validation
node_controller -->|"validates ADOPT"| node_adopt_validation
node_adopt_validation -->|"checks changes"| node_change_detection
node_controller -->|"returns result"| node_terminal_result
node_engineer -->|"uses standards"| node_agent_standards
node_engineer -->|"uses guidance"| node_instructions
node_engineer -->|"uses prompts"| node_prompts
node_engineer -->|"consults intelligence"| node_repo_intelligence
node_engineer -->|"reviews state"| node_planning_state

click node_cli_entry "https://github.com/serenbeam/khwami/blob/master/src/cli/index.js"
click node_bootstrap "https://github.com/serenbeam/khwami/blob/master/src/core/bootstrap.js"
click node_context "https://github.com/serenbeam/khwami/blob/master/src/core/context-resolution.js"
click node_controller "https://github.com/serenbeam/khwami/blob/master/src/core/workflow-controller.js"
click node_create_analysis "https://github.com/serenbeam/khwami/blob/master/src/core/create-analysis.js"
click node_project_shape "https://github.com/serenbeam/khwami/blob/master/src/core/create-project-shape.js"
click node_create_proposal "https://github.com/serenbeam/khwami/blob/master/src/core/create-proposal.js"
click node_create_actions "https://github.com/serenbeam/khwami/blob/master/src/core/create-action-derivation.js"
click node_create_execution "https://github.com/serenbeam/khwami/blob/master/src/core/create-execution.js"
click node_create_validation "https://github.com/serenbeam/khwami/blob/master/src/core/create-validation.js"
click node_adopt_analysis "https://github.com/serenbeam/khwami/blob/master/src/core/adopt-analysis.js"
click node_adopt_requirement "https://github.com/serenbeam/khwami/blob/master/src/core/adopt-requirement.js"
click node_adopt_proposal "https://github.com/serenbeam/khwami/blob/master/src/core/adopt-proposal.js"
click node_adopt_actions "https://github.com/serenbeam/khwami/blob/master/src/core/adopt-action-derivation.js"
click node_adopt_execution "https://github.com/serenbeam/khwami/blob/master/src/core/adopt-execution.js"
click node_adopt_validation "https://github.com/serenbeam/khwami/blob/master/src/core/adopt-validation.js"
click node_approved_scope "https://github.com/serenbeam/khwami/blob/master/src/core/approved-scope.js"
click node_change_detection "https://github.com/serenbeam/khwami/blob/master/src/core/change-detection.js"
click node_agent_standards "https://github.com/serenbeam/khwami/tree/master/agents"
click node_instructions "https://github.com/serenbeam/khwami/tree/master/instructions"
click node_prompts "https://github.com/serenbeam/khwami/tree/master/prompts"
click node_repo_intelligence "https://github.com/serenbeam/khwami/tree/master/docs"
click node_planning_state "https://github.com/serenbeam/khwami/blob/master/WORKSPACE_STATE.md"
click node_terminal_result "https://github.com/serenbeam/khwami/blob/master/src/cli/index.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_cli_entry,node_bootstrap,node_context,node_controller,node_terminal_result toneBlue
class node_create_analysis,node_project_shape,node_create_proposal,node_create_actions,node_create_execution,node_create_validation toneAmber
class node_adopt_analysis,node_adopt_requirement,node_adopt_proposal,node_adopt_actions,node_adopt_execution,node_adopt_validation toneMint
class node_approved_scope,node_change_detection toneRose
class node_agent_standards,node_instructions,node_prompts,node_repo_intelligence,node_planning_state,node_engineer toneIndigo
```

## Components

### CLI and Routing

- [CLI Entry](https://github.com/serenbeam/khwami/blob/master/src/cli/index.js): `src/cli/index.js`
- [Core Bootstrap](https://github.com/serenbeam/khwami/blob/master/src/core/bootstrap.js): `src/core/bootstrap.js`
- [Context Resolution](https://github.com/serenbeam/khwami/blob/master/src/core/context-resolution.js): `src/core/context-resolution.js`
- [Workflow Controller](https://github.com/serenbeam/khwami/blob/master/src/core/workflow-controller.js): `src/core/workflow-controller.js`
- [Terminal Result](https://github.com/serenbeam/khwami/blob/master/src/cli/index.js): `src/cli/index.js`

### CREATE Lifecycle

- [CREATE Analysis](https://github.com/serenbeam/khwami/blob/master/src/core/create-analysis.js): `src/core/create-analysis.js`
- [Project Shape](https://github.com/serenbeam/khwami/blob/master/src/core/create-project-shape.js): `src/core/create-project-shape.js`
- [CREATE Proposal](https://github.com/serenbeam/khwami/blob/master/src/core/create-proposal.js): `src/core/create-proposal.js`
- [CREATE Actions](https://github.com/serenbeam/khwami/blob/master/src/core/create-action-derivation.js): `src/core/create-action-derivation.js`
- [CREATE Execution](https://github.com/serenbeam/khwami/blob/master/src/core/create-execution.js): `src/core/create-execution.js`
- [CREATE Validation](https://github.com/serenbeam/khwami/blob/master/src/core/create-validation.js): `src/core/create-validation.js`

### ADOPT Lifecycle

- [ADOPT Analysis](https://github.com/serenbeam/khwami/blob/master/src/core/adopt-analysis.js): `src/core/adopt-analysis.js`
- [Objective Reconciliation](https://github.com/serenbeam/khwami/blob/master/src/core/adopt-requirement.js): `src/core/adopt-requirement.js`
- [ADOPT Proposal](https://github.com/serenbeam/khwami/blob/master/src/core/adopt-proposal.js): `src/core/adopt-proposal.js`
- [ADOPT Actions](https://github.com/serenbeam/khwami/blob/master/src/core/adopt-action-derivation.js): `src/core/adopt-action-derivation.js`
- [ADOPT Execution](https://github.com/serenbeam/khwami/blob/master/src/core/adopt-execution.js): `src/core/adopt-execution.js`
- [ADOPT Validation](https://github.com/serenbeam/khwami/blob/master/src/core/adopt-validation.js): `src/core/adopt-validation.js`

### Scope and Validation

- [Approved Scope](https://github.com/serenbeam/khwami/blob/master/src/core/approved-scope.js): `src/core/approved-scope.js`
- [Change Detection](https://github.com/serenbeam/khwami/blob/master/src/core/change-detection.js): `src/core/change-detection.js`

### Guidance and Intelligence

- [Collaboration Standards](https://github.com/serenbeam/khwami/tree/master/agents): `agents`
- [Reusable Instructions](https://github.com/serenbeam/khwami/tree/master/instructions): `instructions`
- [Engineering Prompts](https://github.com/serenbeam/khwami/tree/master/prompts): `prompts`
- [Repository Intelligence](https://github.com/serenbeam/khwami/tree/master/docs): `docs`
- [Planning and State](https://github.com/serenbeam/khwami/blob/master/WORKSPACE_STATE.md): `WORKSPACE_STATE.md`

### Other components

- **Engineer**

## Connections

- Engineer → CLI Entry: submits request (evidence: `README.md`)
- CLI Entry → Core Bootstrap: initializes core (evidence: `src/cli/index.js`)
- Core Bootstrap → Context Resolution: initializes (evidence: `src/core/bootstrap.js`)
- Core Bootstrap → Workflow Controller: initializes (evidence: `src/core/bootstrap.js`)
- CLI Entry → Workflow Controller: routes workflow (evidence: `src/cli/index.js`)
- Workflow Controller → Context Resolution: resolves context (evidence: `src/core/workflow-controller.js`)
- Workflow Controller → CREATE Analysis: analyzes CREATE (evidence: `src/core/workflow-controller.js`)
- CREATE Analysis → Project Shape: derives shape (evidence: `src/core/create-analysis.js`)
- Workflow Controller → ADOPT Analysis: analyzes ADOPT (evidence: `src/core/workflow-controller.js`)
- Workflow Controller → Objective Reconciliation: reconciles objective (evidence: `src/core/workflow-controller.js`)
- Workflow Controller → CREATE Proposal: builds proposal (evidence: `src/core/workflow-controller.js`)
- CREATE Proposal → CREATE Actions: derives actions (evidence: `src/core/create-proposal.js`)
- Workflow Controller → ADOPT Proposal: builds proposal (evidence: `src/core/workflow-controller.js`)
- Workflow Controller → ADOPT Actions: derives actions (evidence: `src/core/workflow-controller.js`)
- Workflow Controller → Change Detection: captures baseline (evidence: `src/core/workflow-controller.js`)
- Workflow Controller → Approved Scope: prepares scope (evidence: `src/core/workflow-controller.js`)
- Workflow Controller → CREATE Execution: executes CREATE (evidence: `src/core/workflow-controller.js`)
- Workflow Controller → ADOPT Execution: executes ADOPT (evidence: `src/core/workflow-controller.js`)
- Workflow Controller → CREATE Validation: validates CREATE (evidence: `src/core/workflow-controller.js`)
- Workflow Controller → ADOPT Validation: validates ADOPT (evidence: `src/core/workflow-controller.js`)
- ADOPT Validation → Change Detection: checks changes (evidence: `src/core/adopt-validation.js`)
- Workflow Controller → Terminal Result: returns result (evidence: `README.md`)
- Engineer → Collaboration Standards: uses standards (evidence: `README.md`)
- Engineer → Reusable Instructions: uses guidance (evidence: `README.md`)
- Engineer → Engineering Prompts: uses prompts (evidence: `README.md`)
- Engineer → Repository Intelligence: consults intelligence (evidence: `README.md`)
- Engineer → Planning and State: reviews state (evidence: `README.md`)
