| Guide ID | A-1 |
|---|---|
| Audience | Developers, Architects |
| Prerequisites | GS-2: Core Concepts, GS-3: How It Works |
| Time | 25 minutes |
| Difficulty | Advanced |
Chipset Architecture
In 1985, Commodore released the Amiga 1000. Its CPU, a Motorola 68000 running at 7.16 MHz, was unremarkable. What made the Amiga astonishing was everything around that CPU: three custom coprocessors named Agnus, Denise, and Paula, each handling a specialized domain — memory and timing, graphics rendering, and audio/IO respectively. While competitors threw faster CPUs at multimedia problems, the Amiga achieved superior results through architectural intelligence: the right processor for the right job at the right time.
gsd-skill-creator borrows this principle. Rather than treating every AI task as a single undifferentiated context window problem, it decomposes the skill management lifecycle into specialized execution paths. Each path is optimized for its specific workload. The result is a system that manages context budgets, routes intents, collects observations, and renders output through purpose-built subsystems rather than a monolithic processor.
The Amiga Principle
The Amiga Principle is the design thesis behind gsd-skill-creator: specialized coprocessors outperform general-purpose approaches when workloads have distinct computational profiles.
Consider what happens when an AI coding assistant loads skills into its context window. The system must simultaneously answer several questions that have nothing in common: Which skills are relevant right now? (scoring) How many tokens can we spend? (budgeting) What did the user do in previous sessions? (observation) Which GSD command should run next? (routing) How should the output be formatted for the current audience? (rendering). A general-purpose system processes all of these in the same way. A chipset-based system assigns each question to the subsystem built to answer it.
The original Amiga achieved 4,096 colors, four-channel stereo audio, and hardware scrolling on a 7 MHz processor because Denise handled pixel output, Paula handled audio DMA, and Agnus coordinated memory access so none of them collided. gsd-skill-creator achieves intelligent skill management on a finite context window because each chipset component handles its domain without interfering with the others.
Chipset Components
The four chipset components map directly to system modules. Each has a clear responsibility boundary, defined inputs and outputs, and a reason it exists as a separate concern rather than being folded into something else.
Agnus — The Context Manager
In the original Amiga, Agnus controlled the blitter and copper — the components responsible for memory access scheduling and display timing. In gsd-skill-creator, Agnus is the context manager: the subsystem that decides what occupies the context window at any given moment.
Agnus owns the 6-stage skill loading pipeline (Score, Resolve, ModelFilter, CacheOrder, Budget, Load). It takes the full set of installed skills, scores them against the current context, resolves conflicts between project-level and user-level skills, filters by agent profile, optimizes cache ordering, enforces the token budget, and injects the survivors into the active session. The pipeline is Agnus's blitter — a specialized engine that moves the right data into the right place at the right time.
The token budget allocation (default 15,500 characters, configurable via .planning/skill-creator.json) is Agnus's memory map. Just as the original Agnus divided chip RAM between the CPU and custom chips, this Agnus divides the context window between active skills, ensuring no single skill monopolizes the available space and critical skills always load before optional ones.
Source: src/application/stages/ (pipeline stages), src/application/ (skill application engine)
Denise — The Output Renderer
The original Denise converted bitplane data into pixel output, handling color palettes, sprites, and display modes. In gsd-skill-creator, Denise is the output renderer: the subsystem responsible for how skill content is presented to different audiences.
Denise handles progressive disclosure — the principle that information should be revealed in layers appropriate to the consumer. A skill's content might need to be presented as a brief summary for token-constrained contexts (~2K characters), as active guidance for the working session (~10K characters), or as a full reference for deep investigation. Denise manages these tiers, selecting the appropriate disclosure level based on the current context and audience profile.
Denise also manages multi-audience rendering. The same skill might be consumed by an executor agent (which needs actionable instructions), a planner agent (which needs constraints and dependencies), or a human developer (who needs explanatory context). Denise adapts the presentation without changing the underlying skill content, just as the original Denise could display the same bitplane data in different screen modes.
Source: src/disclosure/ (progressive disclosure), src/retrieval/ (tiered content retrieval)
Paula — The I/O Controller
The original Paula handled all audio output and serial/parallel I/O. In gsd-skill-creator, Paula is the I/O controller: the subsystem that handles all observation input and pattern storage output.
Paula collects observations during Claude Code sessions — commands executed, files touched, decisions made, skills activated, user corrections. These observations are stored as compact JSONL entries in .planning/patterns/sessions.jsonl (an append-only log that preserves complete session history). Paula also manages feedback.jsonl, which captures user corrections that drive the learning loop.
The pattern detection pipeline reads Paula's output. When the same command sequence, file access pattern, or workflow structure appears 3 or more times, the detection engine flags it as a skill candidate. Paula's role is to faithfully record without judgment — the detection engine decides what's significant. This separation matters: observation should never be influenced by what the system thinks is important, because the highest-value patterns are often the ones no one anticipated.
Source: src/observation/ (session observation), src/detection/ (pattern detection), src/learning/ (feedback learning)
Gary — The Address Router
In the original Amiga, Gary was the gate array that handled address decoding — routing memory requests to the correct chip or expansion bus. In gsd-skill-creator, Gary is the address router: the GSD Orchestrator that routes user intent to the correct GSD command.
Gary implements a 5-stage classification pipeline (Exact Match, Lifecycle Filtering, Bayesian Classification, Semantic Fallback, Confidence Resolution) that transforms natural language requests into specific GSD commands. When a user says "let's plan the next phase," Gary decodes that address and routes it to /gsd:plan-phase with the correct phase number. When the user says "what should I work on?", Gary reads the project lifecycle state and routes to /gsd:progress.
Gary also provides lifecycle awareness — reading the .planning/ directory to understand which milestone is active, which phases are complete, and what the logical next step should be. This is analogous to the original Gary's role in determining which address space a request belongs to: chip RAM, fast RAM, or expansion.
Source: src/orchestrator/ (GSD orchestrator with discovery, state, intent, lifecycle, verbosity, gates, and extension submodules)
Chipset Configuration
The chipset is configured declaratively through .chipset/chipset.yaml. This file defines the complete topology of a chipset deployment — which positions exist, what roles they serve, their token budgets, lifecycle modes, activation triggers, and skill requirements.
A chipset configuration contains three major sections:
Positions define the staff of the chipset. Each position has an identity (id), a role (orchestrator, planner, executor, verifier, etc.), an execution context (main for persistent positions, fork for task-scoped positions), a token budget allocation, a lifecycle mode (persistent or task-scoped), an activation trigger, and skill requirements (required and recommended skills). For example, the coordinator position runs in the main context with a persistent lifecycle, activates at session start, and requires workflow-orchestration and conflict-resolution skills.
Topology maps positions to their roles and contexts, establishing the routing graph. The topology type (e.g., squadron) determines how positions communicate. A fallback position handles requests that don't match any other position's activation trigger.
Trigger definitions specify the events that activate positions. session_start fires at initialization and activates persistent positions (coordinator, relay, monitor, dispatcher). on_phase_enter fires when a new GSD phase begins and activates the planner and configurator. on_execution, on_verification, on_phase_exit, and on_error activate the executor, verifier, chronicler, and sentinel respectively.
Observability configures monitoring: dashboard refresh intervals, JSONL log retention, and bus monitoring alert thresholds (queue depth warnings, dead letter limits, unacknowledged message age).
Data Flow
Data moves through the chipset in a defined sequence. Understanding this flow is essential for debugging, extending, or reasoning about the system's behavior.
1. User Action → Paula (Observe). The user works in Claude Code — running commands, editing files, making decisions. Paula's session observer captures these actions as structured observation records and appends them to sessions.jsonl.
2. Pattern Storage → Paula (Detect). The pattern detection engine reads accumulated observations. When recurring sequences emerge (3+ occurrences), it generates skill candidates and stores them in suggestions.json. User corrections flow into feedback.jsonl and trigger the bounded refinement process after 3+ corrections.
3. Gary (Classify). When the user expresses intent — either through a direct GSD command or natural language — Gary's orchestrator classifies the request through its 5-stage pipeline and determines which GSD command (and which phase/milestone) to invoke.
4. Agnus (Load Skills). Before executing the routed command, Agnus runs the 6-stage skill loading pipeline. It scores all installed skills against the current context, resolves scope conflicts, filters by agent profile, optimizes cache ordering, enforces the token budget, and loads the surviving skills into the session context.
5. Denise (Render). The loaded skills are rendered at the appropriate disclosure level for the current consumer. An executor agent receives concise, actionable content. A human developer receives explanatory context. The rendering adapts without altering the skill's source content.
Design Decisions
Every architectural decision reflects a tradeoff. Here are the ones that shaped the chipset model.
Why coprocessors instead of a monolithic pipeline? A single pipeline that observes, routes, loads, and renders would be simpler to implement but impossible to optimize independently. The observation subsystem needs to be always-on and low-overhead. The routing subsystem needs to be fast and context-aware. The loading pipeline needs to be budget-conscious and cache-friendly. The renderer needs to be audience-adaptive. These are fundamentally different computational profiles. Coupling them means optimizing one degrades another. The coprocessor model lets each subsystem evolve independently.
Why named after Amiga chips? The names are not cosmetic. They encode design intent. When a developer sees "Agnus," they should think "memory scheduling and resource allocation." When they see "Paula," they should think "I/O and data collection." The metaphor constrains the design: if a proposed feature doesn't fit the responsibility of its chipset component, it belongs somewhere else. The names prevent scope creep at the architectural level.
Why YAML configuration instead of code? The chipset topology should be declarative because it represents structure, not behavior. A YAML file can be validated against a schema, diffed in version control, and understood by non-programmers. It also enables tooling: the configurator position can modify the chipset definition without writing TypeScript. Code defines how each position behaves; YAML defines what positions exist and how they relate.
Why separate persistent and task-scoped positions? Persistent positions (coordinator, relay, monitor, dispatcher) run in the main context and survive across tasks. Task-scoped positions (planner, executor, verifier, chronicler, sentinel) run in forked contexts and exist only for the duration of their task. This mirrors the Amiga's distinction between chips that were always active (Agnus managing DMA) and operations that ran on demand (blitter operations). The separation prevents task-specific state from accumulating in the main context, which would accelerate context rot.
What's Next
- A-2: 6-Stage Pipeline — Deep dive into Agnus's skill loading mechanism
- A-3: GSD Orchestrator — How Gary routes user intent to GSD commands
- A-4: Agent Composition — How observations evolve into composite agents