Thoughtware System

Someone asks: "Is our dinner planner an agent?" The team answers with model names, prompt length, and a demo video. Nobody can draw the boundary: what owns the goal, what owns each judgment, where allergies are enforced, what happens when the household rejects Tuesday, or how quality is measured after a model upgrade. Each component demos well alone. Combined behaviour contradicts itself.

Without a system view, parts accumulate. Prompt templates multiply. Retrieval indexes ingest chat. A purchase button appears without approval wiring. Graders exist in a spreadsheet production never runs. That pile amounts to capable fragments without coherence.

This page is the capstone map: what belongs in one governed architecture before you zoom into primers on cognitive units, memory forms, or libraries. Use it as the wall diagram for workshops, and use the Thoughtware Map and Grammar when shared notation is needed.

Helpful context: Thoughtware at a glance orients vocabulary. The ecosystem around cognition names supporting services. Cognitive orchestration covers composition patterns.

Parts and what each owns

Part	Owns
Agents	Goals, loops, working state, strategy, stopping conditions
Skills	Known procedures performing named capabilities
cognitive units	One bounded open judgment each
Deterministic code	Exactness, validation, permissions, transactions
Tools	Reach outside cognition, not how reach is used
Memory	Typed forms: context through evaluation memory
Libraries	Published, evaluated, searchable packages
Behaviour	Posture and collaboration contract
Evaluation	Suites, trajectories, behavioural checks, gates
Human authority	Grants, approval, escalation
Improvement	Governed change versus drift

An agent owns the larger goal, and it is not a digital person. A Skill packages settled procedure so the system does not rediscover ordering and seams each sprint. cognitive units give judgment a location that can be specified, evaluated, and substituted. Code keeps exact work exact. Tools extend reach, and orchestration decides when and why. Together these parts produce outcomes, but only when they align to the same boundary, authority, and evaluation discipline.

One household system, assembled

The Weekly Meal Companion grounding scenario assembles the parts toward one outcome: help a household produce an accepted weekly dinner plan under constraints.

Outcome and boundary: Practical plan for the current week, confirmed constraints respected, sensible ingredient use, local correction supported, accurate shopping list prepared. The system does not diagnose medical conditions, set dietary policy, or purchase without approval.

Goal owner: Meal Planning Agent, running a minimum sufficient loop until plan accepted or escalated. See the agent loop.

Judgments as cognitive units: GenerateCandidates, AssessMealPracticality, JudgeWeekdayPracticality, CritiquePlan, and others, each one bounded judgment with contract and suite.

Procedures as Skills: Compose weekly plan capability where procedure shape is known, judgment stays inside cognitive units.

Deterministic shell: Allergy enforcement, plan versioning, shopping list assembly, purchase approval gate, audit trail.

Memory: Context for this week, endorsed knowledge for allergies and rules, working state for acceptance and gaps, expertise for Busy Week Pattern when applicability guard passes. See memory as architecture.

Library placement: Domain cognitive units shared across products, organisational AskTargetedQuestion, agent-private strategy where reuse is not yet earned. See libraries of cognition.

Evaluation: Exact allergy checks plus graders on named cognitive units, regression on known busy-week failures.

Authority: Provisional planning allowed, purchase and knowledge merge require human gates.

This is one architecture, not a pile of model calls. Every row in the judgment terrain table from the grounding reference maps to a part above: leadership allocation, not accidental prompt stacking.

Coherence across parts

Failure includes wrong judgment and also contradiction: posture promises challenge while UI hides alternatives, memory retrieves what authority forbids, agents loop without evaluation or stopping discipline, libraries publish packages orchestration bypasses in ad-hoc prompts, and endorsed knowledge exists while deterministic shell never enforces it. Coherence across parts is the architectural goal. The ecosystem layers of stores, catalogs, pipelines, and approval keep honesty over time when models, vendors, and teams change.

A single pursuit typically moves through a recognisable sequence: household request, context assembly, agent loop reading working state, cognitive units called with typed inputs and source classification, deterministic shell validating and patching, critique and repair locally, acceptance updating working state, shopping list and approval prompts, and audit and eval artifacts recorded. The architecture does not require a microservice for every box on day one. It does require explicit ownership: which component writes which memory form, which gate blocks purchase, which suite blocks library publish.

High-volume invoice processing uses the same part boundaries: extraction Skill, field-level cognitive units, deterministic totals and schema checks, posting approval, shared cognitive units library, regression on posting failures. Domain terrain differs. System shape rhymes. That transfer is why Thoughtware insists on naming parts before naming models. Use the Thoughtware Map and Grammar to draw this system in workshops: outcome at centre, judgment chains, cognitive units, memory forms, eval routes, before Intent Compilation turns commitments into contracts. See making the specification executable.

The judgment terrain table from the grounding reference serves as an integration test for system coherence. Each row maps to exactly one primary owner in the parts table:

Terrain row	Primary owner
Interpret the current week	Agent strategy + InterpretWeek
Identify confirmed allergies	Deterministic shell on endorsed knowledge
Decide meal fits busy evening	AssessMealPracticality cognitive unit
Compose weekly plan	Agent-led + ComposeWeek
Clarify ambiguous preference	AskTargetedQuestion + household
Calculate portions	Deterministic code
Repair rejected meal	cognitive unit proposes, code patches
Purchase groceries	Human approval + deterministic execution

When two rows collapse into one prompt, the system diagram is lying. Refactoring then means splitting ownership, not tuning temperature.

Common mistakes and failure isolation

The most common diagram mistake is a model-centred view with one box labelled "LLM" instead of agents, cognitive units, and shell. A close relative is agent everything, where pipelines with known procedure masquerade as goal loops. Treating memory as an afterthought, added when UX complains about "forgetting," produces undifferentiated stores. Libraries reduced to prompt folders, without contracts, substitution, or eval bind, are libraries in name only. Eval disconnected from release, where graders exist as research rather than gates, means quality evidence never blocks shipping.

Behaviour is not copywriting layered on top at the end. Posture, including proactive planning, targeted questions, challenge of impractical weeks, and preservation of accepted work during repair, must agree with memory discipline, authority grants, and eval evidence. A system that promises challenge in behaviour architecture but hides alternatives in UI fails coherence even when individual cognitive units score well. Reviewing behaviour statements against three tests reveals alignment gaps: does memory conduct match preference store versus context rules, does authority match approval wiring, and does eval cover the claimed behaviours?

When the system contradicts itself in production, tracing across parts before blaming the model reveals the actual failure. Did endorsed knowledge match shell enforcement? Did working state reflect acceptance? Did library version pins match deployed orchestration? Did eval gates run on the release that shipped? Did source kinds at seams allow unaccountable override? Most "model got worse" incidents are coherence breaks discoverable with a system checklist. Documenting that checklist in runbooks linked from on-call playbooks lets new responders perform first-pass isolation without a Thoughtware expert on the phone.

A new engineer traces one pursuit in documentation and logs: originating request, context assembly, working state checkpoints, cognitive unit calls with version pins, shell enforcement events, acceptance update, eval artifacts written. If that trace is impossible, the Thoughtware system exists in slides only. Providing the map, one spec, one regression failure replay, and one approval audit entry teaches more than a model API workshop. Scheduling an annual cross-part review covering agents, libraries, memory, shell, eval, and authority, and diffing the whiteboard against the map, turns gaps into engineering work rather than documentation debt.

What to do next

The outcome and boundary come first, before naming models or vendors. Agents, cognitive units, Skills, code, memory, libraries, and eval locate for that outcome on one page. Coherence follows from checking whether posture, authority, and memory discipline agree in copy and code. Tracing one failure incident across parts reveals whether the weakest link is memory, source classification, eval, or authority. The map belongs where sprint planning starts, and feature pitches that cannot point to an outcome node lack architectural grounding.

See what Thoughtware is for category definition and Thoughtware in practice for team operating model.

Read next: The Thoughtware Map and Grammar.