Program map

Every module of the CLI, every file it reads and writes, scanned out of the shell sources rather than drawn by hand.

Nobody drew this. scripts/lib/architecture-scan.awk reads bin/majordomus and lib/*.sh on every build and reports what it can prove: which module sources which, and which file under .ai/ each module names. A module that stops touching a file loses its edge the same day. A diagram that cannot go stale is worth more than a prettier one that can.

What an edge means

Direction comes from the line the reference sits on — the redirection it is behind, or the command word that introduces it. A path handed straight to a helper is drawn as uses, not guessed at, because a wrong arrow here would be a claim the sources do not support. Read the scanner if you want the exact rule; it is forty lines.

static reference scan of bin/majordomus and lib/*.sh

reads sources uses writes

Select a node to see what it is and what it touches.

Modules of the CLI and the files under .ai/ they touch. Solid arrows are reads and writes the scan could place; dashed arrows are references it would not claim a direction for.

The same graph as text — 78 nodes, 213 edges

majordomus entry
- sources lib/adr.sh
- sources lib/bench.sh
- sources lib/capture.sh
- sources lib/check.sh
- sources lib/checkpoint.sh
- sources lib/common.sh
- sources lib/context.sh
- sources lib/decision.sh
- sources lib/doctor.sh
- sources lib/doctrine.sh
- sources lib/evidence.sh
- sources lib/finish.sh
- sources lib/handover.sh
- sources lib/history.sh
- sources lib/init.sh
- sources lib/knowledge.sh
- sources lib/migrate.sh
- sources lib/plan.sh
- sources lib/prompt.sh
- sources lib/question.sh
- sources lib/rules.sh
- sources lib/search.sh
- sources lib/session.sh
- sources lib/skills.sh
- sources lib/start.sh
- sources lib/update.sh
- sources lib/usecase.sh
- sources lib/watch.sh
common module
- reads .ai/local/state/current.yaml
- reads .ai/local/state/session-current.yaml
- reads .ai/repo/policy.yaml
- reads .ai/repo/providers
- writes .ai/local/state/ledger.jsonl
adr module
the repository's architecture decisions: list, show, propose, check
- sources lib/knowledge.sh
- sources lib/rules.sh
- uses .ai/repo/adrs/.id.lock
knowledge module
the compiled index over what this repository states
- uses .ai/repo/knowledge/sources.yaml
rules module
the effective rule set: vendored baseline plus project rules (read-only, except vendor update)
- reads .ai/repo/rules/vendor
repo/adrs/.id.lock artifact
bench module
time every public command, cold and warm, against the baseline
- sources lib/commands.sh
commands module
capture module
record the person's raw prompts from a provider hook, and prove it
- sources lib/checkpoint.sh
- sources lib/derive.sh
- sources lib/handover.sh
- sources lib/session.sh
session module
open, inspect and close one execution episode
- reads .ai/local/state/ledger.jsonl
- sources lib/project.sh
- sources lib/session_context.sh
- uses .ai/local/state/sessions
- writes .ai/local/state/session-current.yaml
derive module
- reads .ai/local/state/decisions.md
- reads .ai/local/state/ledger.jsonl
- sources lib/decision.sh
- sources lib/question.sh
- sources lib/session.sh
- uses .ai/local/state/checkpoints
- uses .ai/local/state/handovers
checkpoint module
record compact progress inside the active task
- sources lib/derive.sh
- sources lib/handover.sh
- uses .ai/local/state/checkpoints
- writes .ai/local/state/current.yaml
handover module
write an append-only continuation record (body on stdin)
- sources lib/derive.sh
- uses .ai/local/state/handovers
- writes .ai/local/state/current.yaml
check module
is the current task consistent with policy, scope, state?
- sources lib/commands.sh
- sources lib/decision.sh
- sources lib/doctrine.sh
- sources lib/evidence.sh
- sources lib/question.sh
- sources lib/start.sh
- sources lib/usecase.sh
- uses .ai/local/state/checkpoints
- uses .ai/local/state/decisions.md
- uses .ai/local/state/ledger.jsonl
- uses .ai/local/state/open-questions.md
- writes .ai/local/state/current.yaml
doctrine module
what rules are enforced, by what, and whether they are wired
- sources lib/rules.sh
local/state/current.yaml artifact
local/state/checkpoints artifact
local/state/open-questions.md artifact
local/state/ledger.jsonl artifact
local/state/decisions.md artifact
start module
begin a scoped task under a profile
- sources lib/check.sh
- sources lib/handover.sh
- uses .ai/local/state/handovers
- writes .ai/local/state/archive
- writes .ai/local/state/current.yaml
question module
open, resolve and list questions that block acceptance
- uses .ai/local/state/open-questions.md
decision module
record or read durable decisions
- uses .ai/local/state/decisions.md
usecase module
the executable use cases: list, show, validate, run, coverage, impact, scaffold
- sources lib/commands.sh
- sources lib/rules.sh
- writes .ai/local/evidence/use-cases
evidence module
record that one obligation the task declared has been discharged
- reads .ai/local/state/ledger.jsonl
repo/policy.yaml artifact
repo/providers artifact
local/state/session-current.yaml artifact
context module
what the next worker needs to know now, within budget
- reads .ai/local/state/decisions.md
- reads .ai/local/state/ledger.jsonl
- reads .ai/local/state/mcp/server.json
- reads .ai/local/state/open-questions.md
- sources lib/context_docs.sh
- sources lib/decision.sh
- sources lib/handover.sh
- sources lib/history.sh
- sources lib/prompt.sh
- uses .ai/local/state/checkpoints
- uses .ai/local/state/handovers
history module
read the append-only ledger back
- writes .ai/local/state/ledger.jsonl
prompt module
list, show and render repository-local prompt assets
- reads .ai/local/state/decisions.md
- reads .ai/local/state/open-questions.md
- sources lib/context.sh
- sources lib/decision.sh
- sources lib/handover.sh
- uses .ai/local/state/checkpoints
- uses .ai/local/state/handovers
context_docs module
- uses .ai/repo/policy.yaml
local/state/handovers artifact
local/state/mcp/server.json artifact
deployment module
doctor module
is Majordomus itself healthy and actually wired here?
- reads .ai/README.md
- reads .ai/local/state/checkpoints
- reads .ai/local/state/handovers
- reads .ai/local/state/ledger.jsonl
- reads .ai/repo/scope.yaml
- sources lib/adr.sh
- sources lib/capture.sh
- sources lib/check.sh
- sources lib/commands.sh
- sources lib/context.sh
- sources lib/decision.sh
- sources lib/deployment.sh
- sources lib/doctrine.sh
- sources lib/project.sh
- sources lib/prompt.sh
- sources lib/question.sh
- sources lib/session.sh
- sources lib/skills.sh
- sources lib/usecase.sh
- uses .ai/local/state/open-questions.md
- uses .ai/repo/policy.yaml
- uses .ai/repo/providers
- uses .ai/repo/rules/vendor
skills module
the repository's skills: list, show and check them
- reads .ai/repo/skills
- sources lib/knowledge.sh
project module
- reads .ai/repo/project/project.yaml
- uses .ai/repo/project/issues
- writes .ai/repo/project/milestones
repo/scope.yaml artifact
README.md artifact
repo/rules/vendor artifact
finish module
evaluate the finish contract; refuse if unmet
- reads .ai/local/state/checkpoints
- sources lib/check.sh
- sources lib/handover.sh
- uses .ai/local/state/decisions.md
- uses .ai/local/state/handovers
- writes .ai/local/state/completed
- writes .ai/local/state/current.yaml
local/state/completed artifact
init module
create the .ai/ layer in this repository (refuses to overwrite)
- reads .ai/local/state/decisions.md
- reads .ai/local/state/open-questions.md
- reads .ai/repo/rules/vendor
- reads .ai/repo/scope.yaml
- sources lib/rules.sh
- uses .ai/README.md
- uses .ai/local/cache
- uses .ai/local/prompts
- uses .ai/local/session-contexts
- uses .ai/local/state/checkpoints
- uses .ai/repo/README.md
- uses .ai/repo/applications
- uses .ai/repo/deployments}
- uses .ai/repo/features
- uses .ai/repo/knowledge/curated/README.md
- uses .ai/repo/policy.yaml
- uses .ai/repo/profiles/README.md
- uses .ai/repo/project/README.md
- uses .ai/repo/prompts/README.md
- uses .ai/repo/rules/README.md
- uses .ai/repo/rules/project/README.md
- uses .ai/repo/sessions}
- uses .ai/repo/skills
- uses .ai/repo/use-cases
- uses .ai/repo/why
- uses .ai/repo/workflows
- writes .ai/local/state/handovers
repo/README.md artifact
repo/profiles/README.md artifact
repo/prompts/README.md artifact
repo/rules/README.md artifact
repo/rules/project/README.md artifact
repo/knowledge/curated/README.md artifact
repo/workflows artifact
repo/skills artifact
repo/use-cases artifact
repo/applications artifact
repo/why artifact
repo/features artifact
repo/sessions} artifact
repo/deployments} artifact
repo/project/README.md artifact
local/prompts artifact
local/cache artifact
local/session-contexts artifact
repo/knowledge/sources.yaml artifact
migrate module
move pre-.ai project data from .majordomus/ into .ai/ (explicit, backed up)
- reads .ai/local/state/decisions.md
- reads .ai/local/state/open-questions.md
- reads .ai/repo/rules/vendor
- sources lib/init.sh
- uses .ai/local/cache
- uses .ai/local/prompts
- uses .ai/local/session-contexts
- uses .ai/local/state/checkpoints
- uses .ai/repo/README.md
- uses .ai/repo/knowledge/curated/README.md
- uses .ai/repo/policy.yaml
- uses .ai/repo/profiles/README.md
- uses .ai/repo/project/README.md
- uses .ai/repo/prompts/README.md
- uses .ai/repo/providers
- uses .ai/repo/rules/README.md
- uses .ai/repo/rules/project/README.md
- uses .ai/repo/scope.yaml
- uses .ai/repo/sessions/README.md
- uses .ai/repo/skills
- uses .ai/repo/templates/README.md
- uses .ai/repo/workflows
- writes .ai/local/state/handovers
repo/sessions/README.md artifact
repo/templates/README.md artifact
plan module
the milestone and issue model: validate, read, and move an issue
- sources lib/project.sh
- uses .ai/repo/project/issues
- writes .ai/repo/project/milestones
repo/project/milestones artifact
repo/project/issues artifact
repo/project/project.yaml artifact
rust_bin module
search module
find durable records without reading all of them
- uses .ai/local/state/checkpoints
- uses .ai/local/state/decisions.md
- uses .ai/local/state/handovers
- uses .ai/local/state/ledger.jsonl
- uses .ai/local/state/open-questions.md
session_context module
- sources lib/context.sh
local/state/sessions artifact
local/state/archive artifact
update module
regenerate provider projections from policy
- uses .ai/local/state/checkpoints
- uses .ai/local/state/handovers
- uses .ai/repo/providers
local/evidence/use-cases artifact
watch module
what has drifted: state, policy, projections, retention
- sources lib/check.sh
- sources lib/context.sh
- sources lib/decision.sh
- sources lib/doctor.sh
- sources lib/handover.sh
- sources lib/prompt.sh
- sources lib/question.sh
- uses .ai/local/state/checkpoints
- uses .ai/local/state/handovers
- uses .ai/local/state/ledger.jsonl

35modules

42state files

15write paths

Every number above is counted from the scan at build time. The scanner is scripts/lib/architecture-scan.awk; the data it produced for this build is architecture.json.