This document bridges Minsky's theoretical foundations to its actual implementation. It answers the question: why is the system designed this way, and where does that design show up in the code?
This is not a reproduction of the theory — it is a map. For the full theoretical treatment, see
the Notion: Vision & theory page. For
implementation details, see docs/architecture.md.
The central insight behind Minsky's design is that alignment is achieved through environmental design, not individual discipline.
The same control structures that work for human teams work for AI agents. An engineer who cannot push unformatted code to main (because a pre-commit hook blocks it) never needs to remember to format. An agent working in an isolated session cannot accidentally overwrite a colleague's work (because it has its own git clone). The environment enforces the constraint; the actor — human or AI — is free to focus on the actual work.
Three concrete examples from the codebase:
-
Pre-commit hooks (
src/hooks/pre-commit.ts,.husky/) run format, lint, typecheck, and test checks before every commit. Neither humans nor AI agents can commit code that fails these checks. Quality is enforced at the boundary, not delegated to memory or discipline. -
Session isolation (
packages/domain/src/session/) gives each work unit its own git clone, branch, and lifecycle. Parallel agents cannot interfere with each other's in-progress work. The filesystem itself is the coordination mechanism. -
Quality gates (CI checks, pre-merge review hooks in
.claude/settings.json) make review and verification the path of least resistance. A PR cannot be merged without passing CI and posting a review — the workflow enforces this structurally.
This is Ashby's Law of Requisite Variety applied to software development infrastructure: each environmental constraint attenuates one dimension of possible failure.
Stafford Beer's Viable System Model identifies five functional organs that any self-sustaining system must possess. The table below maps each organ to Minsky's current implementation.
Role: The operational units that do the actual work — task execution, code changes, PR creation.
Implementation:
packages/domain/src/session/— isolated git workspaces where implementation happens. Each session is a git clone tied to a task, with its own branch and lifecycle fromstarttomerge.packages/domain/src/tasks/— task CRUD with pluggable backends (GitHub Issues, Minsky DB). Tasks are the units of work that sessions execute.src/adapters/shared/— dual CLI/MCP interface. The same operations are exposed throughminskyCLI andmcp__minsky__*tools without duplicating business logic.
Status: Built.
Role: Prevents the operational units from interfering with each other. Handles anti-oscillatory coordination — the signals that keep parallel workers in sync without requiring central direction.
Implementation:
- Pre-commit hooks (
src/hooks/pre-commit.ts,.husky/) enforce consistent code quality across all contributors — human and AI alike. Every commit passes the same 8-step validation pipeline. - Session isolation (
packages/domain/src/session/session-service.ts) prevents parallel sessions from conflicting at the filesystem level. Each session operates in~/.local/state/minsky/sessions/<UUID>/. - Workflow hooks (
.claude/settings.json) encode coordination rules for AI agents working inside the repo — what to check before committing, what to verify before merging. - Transcript substrate (
packages/domain/src/storage/schemas/agent-transcripts-schema.ts,agent-transcript-turns-schema.ts; ADR-017/018/019/025) durably captures each agent conversation's turns and makes them queryable (transcripts_search,transcripts_get,transcripts_listMCP tools). This is most of what a "reasoning stream" originally asked for: structured logs of agent decision-making that other agents or human reviewers can consult.
Status: Partial. Hooks and isolation exist, and the reasoning-stream half of this gap is now largely superseded by the transcript substrate above — decision-making is durably captured and queryable after the fact. What remains missing: a live cross-session coordination signal — a way for concurrent agents to know in real time what other agents are currently working on (the transcript substrate is queried after the fact, not a live channel).
Role: Monitors operations and feeds back to the operational units. Closes the loop between "what is happening" and "what should be happening." Includes an audit channel (System 3*) for spot-checking that reported behavior matches actual behavior.
Implementation:
- CI integration — GitHub Actions runs the full build and test suite on every PR. This is the primary feedback mechanism: operational output (a PR) is automatically verified against quality criteria.
- Session lifecycle (
packages/domain/src/session/) — thepr_create → pr_approve → pr_merge → frozenstate machine enforces an ordered workflow. Sessions cannot skip steps. - System 3* audit/probe channel (
packages/domain/src/detectors/, mt#1035) — Surface 1 (policy-coverage) was retired 2026-08-16 (mt#4197): it ran log-only for its whole life, blocked nothing, and classified 97.7% of actions "covered" on incidental keyword matches, against a target problem the design postulated rather than measured. Surface 4 (post-mortem,detectors/unasked-direction-analyzer.ts+unasked-direction-store.ts) runs on a post-merge hook (.minsky/hooks/post-merge-unasked-direction-scan.ts) and surfaces findings for human triage via theunasked-direction_*MCP tools (list,mark-real,mark-false-positive).
Status: Partial. CI feedback, session lifecycle enforcement, and the System 3* audit/probe
channel's starting set (Surfaces 1 and 4) are built. What remains missing: Surfaces 2
(diff-signature) and 3 (trajectory-probe) of the detector are still deferred (v0.2/v0.3 per the
research doc), and an automated maturity/quality score for System 3 as a whole — today, drift
monitoring is a per-detector dismissal-rate downgrade (severity-downgrade.ts) plus a manual,
periodic false-positive-rate review (calibration-review skill), not a continuous System 3
signal.
Role: Scans the environment for threats and opportunities. Looks outward and forward — patterns that are emerging, constraints that are approaching, changes in the wider context that the operational units cannot see from inside their work.
Implementation:
packages/domain/src/context/— workspace context detection. Generates structured descriptions of the current project's configuration, active rules, and session state for consumption by AI agents.packages/domain/src/rules/compile/(compile-service.ts) — compiles Minsky's operational rules into formats consumed by different AI coding assistants (AGENTS.md, CLAUDE.md, Cursor rules). This is orientation infrastructure: it shapes how agents understand the environment before they act.
Status: Mostly missing. Context generation and rules compilation exist as orientation infrastructure. What is absent: cross-project pattern detection (learning from patterns across multiple codebases), ecosystem scanning (detecting relevant changes in tools, dependencies, or practices), and any mechanism for feeding environmental intelligence back into operational decisions.
Role: Defines what the system is and what it will not compromise. Holds the identity, values, and policies that remain stable while the environment changes. Arbitrates between System 3 (operational efficiency) and System 4 (strategic adaptation) when they conflict.
Implementation:
packages/domain/src/configuration/— hierarchical configuration loading (defaults → project → user → environment). The configuration schema defines what a valid Minsky deployment looks like..minsky/config.yamlholds project-level policy: which task backend, which repository backend, which rules presets are active.- Rules system (
packages/domain/src/rules/) — Markdown files with YAML frontmatter that encode operational policy. Rules markedalwaysApply: trueare included in every AI context. The rules compilation pipeline propagates policy into agent behavior across all supported AI assistants. Which rules a project receives is its own decision: each rule carries a tier (base/opinionated/style) and a minimum adoption rung, and the project'srules:block adds to or subtracts from the resulting default set.baseis the tier a project may not decline. Selection is honored by both readers of.minsky/rules/— the compile pipeline and the context assembler — so a deselected rule reaches the agent through neither (mt#573).
Status: Built.
Four thinkers shaped Minsky's architecture. This section names the core contribution of each, written for engineers not academics. Follow the links for the full treatment.
Ashby — Law of Requisite Variety: A regulator cannot suppress disturbances it cannot match in informational complexity. The corollary for software: you cannot reliably produce quality code if your quality controls have fewer "channels" than your possible failure modes. Environmental design — hooks, gates, isolation — is variety attenuation. Each control reduces the space of possible bad states the system can enter.
Beer — Viable System Model: Any autonomous system needs five functional organs: operations, coordination, operational feedback, environmental intelligence, and identity/policy. Miss one and the system either oscillates, drifts, or loses coherence over time. Minsky implements these organs as infrastructure: the session model is System 1, the hook pipeline is System 2, CI is System 3.
Boyd — OODA Loop: The observe-orient-decide-act loop is Boyd's model of how agents navigate
uncertainty. Boyd's key insight is that orientation — making sense of incoming data — is the
decisive step, not action speed. Minsky's context generation (packages/domain/src/context/) and rules
compilation (packages/domain/src/rules/compile/) are orientation infrastructure: they shape how AI
agents understand the environment before they decide what to do.
Minsky (Marvin) — Society of Mind: Intelligence emerges from the coordination of many simple agents, not from a single complex one. Minsky (the tool) orchestrates simple, well-bounded dev tools (git, CI, linters, AI coding assistants) into workflows that exhibit intelligent behavior. No single component is smart; the coordination structure is.
Full treatment: Notion: Vision & theory
Four examples showing how a theoretical principle produced a specific implementation decision.
The pre-commit pipeline (src/hooks/pre-commit.ts) runs format, lint, typecheck, and test checks
before every commit. Each step attenuates one dimension of possible code quality failure. The
pipeline does not trust memory or intention — it enforces constraints at the moment of action.
The result: code that reaches git push has already passed 8 quality gates. Reviewers can focus
on logic and design rather than formatting or type errors. This is variety attenuation implemented
as infrastructure.
Sessions (packages/domain/src/session/session-service.ts) give each work unit its own git clone, branch,
and lifecycle directory. An agent working in a session can make any change it wants — the
environment provides maximum freedom to experiment. But the constraints still apply: pre-commit
hooks run inside the session, PRs require CI and review before merging. Freedom within structure.
The alternative — agents sharing a working directory — would produce coordination overhead that grows quadratically with the number of parallel agents. Session isolation is the engineering decision that falls directly out of Beer's System 2 design principle.
The rules compilation pipeline (packages/domain/src/rules/compile/compile-service.ts) compiles Minsky's
own operational rules into formats consumed by AI coding assistants: AGENTS.md (Codex), CLAUDE.md
(Claude Code), and Cursor rule files.
This is a recursive control loop: Minsky encodes its own operational policy as rules, then compiles those rules into instructions that shape the behavior of AI agents working inside Minsky. The tool shapes the agents that use the tool. This corresponds directly to Beer's recursive application of the VSM — each level of the hierarchy is itself a viable system.
Before an AI agent acts on a task, it needs to understand the environment: which rules are
active, what sessions are open, what the current project configuration is. Minsky's context
domain (packages/domain/src/context/) generates this structured orientation package.
This is Boyd's OODA loop applied to agent coordination: the system invests in orientation infrastructure so that individual decision cycles are faster and better-calibrated. The agent doesn't reconstruct context from scratch on every interaction — Minsky provides it.
The VSM mapping above identifies two significant gaps in the current architecture.
System 2 — The Mesh: Live cross-session coordination signals. Currently, parallel sessions are isolated from each other but cannot observe each other in real time. A complete System 2 would allow concurrent agents to know what other agents are working on — not to block each other, but to coordinate naturally (avoid editing the same file, recognize when work overlaps). (The reasoning-stream half of this gap — agent decision-making inspectable by other agents and human reviewers — is now largely covered by the transcript substrate; see the System 2 section above.)
System 4 — The Horizon: Cross-project pattern detection and ecosystem scanning. The current context generation looks inward (this project, this session). A complete System 4 would look outward: what patterns appear across multiple projects? What has changed in the ecosystem of tools and dependencies that Minsky projects depend on? This capability would allow Minsky to detect drift and opportunity before it becomes visible at the operational level.
Full gap analysis: Notion: Architecture map
Three cross-cutting principles govern how Minsky agents behave within the architecture above. They
are not implementation features — they are posture commitments that shape every design decision.
ADR-008 (Attention-Allocation Subsystem) names and consumes all three. The full position essay
lives in Notion (34a937f0-3cb4-814b-adba-f2e5cee38c08).
Minsky is, at its core, an attention-allocation system. Every human-in-the-loop mechanism —
BLOCKED states, PR approval gates, the 2-strikes escalation rule, the Agent Inbox, mesh
notifications — is routing a decision to the cheapest resolver available. The operator is the most
expensive resource and therefore the one to conserve. HITL mechanisms are not interruptions to be
minimized; they are routing decisions to be optimized. The right question is never "should we ask
a human?" but "what is the cheapest resolver that can answer this correctly?"
A Minsky agent knows its boundary of delegation and represents it structurally, rather than
collapsing uncertainty into confident action. Preference-bound decisions — naming, framework
choice, tradeoff resolution, scope change, architectural novelty — are not the agent's to make
alone; the system escalates them by construction rather than resolving them under its own
authority. VSM placement: System 5 is the delegate of the principal, not the principal itself.
The operational corollary in CLAUDE.md §Design Principle: Humility is an instance of this
principle, not a separate rule.
Agents cannot reliably introspect "I should ask here" — Sonnet-class loss rewards confident answers. Noticing — detecting that a decision belongs to a higher authority — must be built one recursion level above the agent's own execution loop, not inside it. VSM placement: System 3* (the audit/probe channel). This is why the System 3* detector (mt#1035) is a sibling to the Ask subsystem rather than a feature of the agent itself: the agent cannot be trusted to notice its own blind spots.
The cockpit (mt#1143) is the operator-facing surface for Minsky's own system state — a local web server externalizing, into infrastructure, the cognitive functions that otherwise live in operator working memory. It is the first concrete instantiation of a more general theoretical frame called Locus: the surface that holds and renders orientation for a one-person organization running many parallel agents.
VSM placement: the cockpit is the operator-facing externalization of Systems 2, 3, and 4. The Agents widget surfaces System 2 (parallel-worker coordination); the Workstreams and TaskGraph widgets surface System 3 (operational feedback over the task graph); and the Attention widget is the algedonic channel — the path by which signals routed to the principal bypass the normal feedback hierarchy and reach System 5 (the operator) directly. System 1 (the underlying work — sessions, tasks, code changes) is what the cockpit renders, not what it owns.
The cockpit is operator-facing, not agent-facing. Agents already have rich orientation infrastructure (context generation, rules compilation, MCP introspection); the cockpit's user is the human running the system, and its design decisions (web rendering, dark-mode density, low-latency polling) reflect operator ergonomics. Architecturally it is a shell + pluggable widgets: the shell is stable, the widgets are independent. Adding a new dial as Minsky gains observable capability is implementing a widget contract + registering in config — no shell rewrite.
For the full architectural treatment, see docs/architecture/cockpit.md.
For the philosophical motivation see the Notion essay
"The cockpit problem: from Locus theory to first instantiation".
docs/architecture.md— implementation architecture: command registry, domain model, persistence, session lifecycle, rules compilation, DI, configuration, repository backendsdocs/architecture/cockpit.md— cockpit subsystem architecture: Locus distinction, VSM placement, widget contract, subsystem map- Notion: Vision & theory — full theoretical treatment: Ashby, Beer, Boyd, Minsky; cybernetic foundations; design philosophy
- Notion: Architecture map — VSM organ analysis, capability inventory, gap analysis
- Notion: Mesh RFC — design proposal for System 2 (cross-session coordination signals and reasoning stream)
- Notion: The cockpit problem — founding essay on the cockpit / Locus distinction
packages/domain/src/concepts.md— formal definitions for Repository, Session, Workspace, and URI handling