From ConnectRPC to Pure HTTP

The initial plan specified ConnectRPC for the kernel’s external interface. The proto schema was already scaffolded. But as Objective #2 planning progressed, the mismatch became clear: ConnectRPC is a framework that imposes its own conventions for service definition, code generation, and transport. The kernel’s design principle — simple, composable patterns over complex frameworks — argues against adopting a framework at the integration boundary.

The decision: standard net/http with JSON request/response for synchronous operations and Server-Sent Events for streaming. The interface should be designed from the kernel architecture, not from a proto schema.

Streaming Tools Protocol

The kernel’s tool calling wire format went through a significant alignment as part of adding ToolsStream to the Agent interface (PR #30).

The Problem

The original ToolCall type used a flat internal structure:

type ToolCall struct {
    ID        string
    Name      string
    Arguments string
}

Custom MarshalJSON/UnmarshalJSON methods translated between this format and the nested format that LLM providers actually send:

{
    "id": "call_abc123",
    "type": "function",
    "function": {
        "name": "read_file",
        "arguments": "{\"path\": \"main.go\"}"
    }
}

This created friction at every serialization boundary. Worse, the custom unmarshal logic had a bug: streaming continuation chunks carry only partial function.arguments without a function.name, and these were silently dropped.

The Decision

Align with the external standard. The new ToolCall mirrors the native LLM API format directly:

type ToolFunction struct {
    Name      string `json:"name,omitempty"`
    Arguments string `json:"arguments,omitempty"`
}

type ToolCall struct {
    ID       string       `json:"id,omitempty"`
    Type     string       `json:"type"`
    Function ToolFunction `json:"function"`
}

A NewToolCall(id, name, arguments) constructor handles the boilerplate. The custom JSON methods were deleted entirely — standard encoding/json handles everything. This touched 16 files across the codebase, but the result is cleaner: no translation layer, no serialization bugs, and streaming tool call data flows through naturally.

ToolsStream

The ToolsStream method follows the established ChatStream/VisionStream pattern:

1. initMessages — convert messages to provider format
2. mergeOptions — apply model-level defaults
3. Set stream: true
4. ExecuteStream — return a channel of StreamingChunk

The StreamingChunk type was extended with a ToolCalls field in its Delta struct and a ToolCalls() accessor mirroring the existing Content() pattern. Tool call accumulation — reassembling partial streaming arguments into complete calls — is deferred to the multi-session kernel refactor where the streaming-first loop is built.

Agent Registry

The kernel’s agent registry (PR #31) introduces named agent registration with capability-aware lookup.

Design

Instead of the kernel being hardwired to a single agent, callers register agents by name — model-aligned names like qwen3-8b, llava-13b, gpt-5 — and query their capabilities without instantiating them.

registry := agent.NewRegistry()
registry.Register("qwen3-8b", qwenConfig)
registry.Register("llava-13b", llavaConfig)

// Query capabilities without instantiation
caps := registry.Capabilities("llava-13b")
// → [Chat, Vision, Tools]

// First Get() triggers agent.New()
agent, err := registry.Get("qwen3-8b")

Instance Ownership

The registry is an instance-owned type, not a global. The kernel creates and owns the instance, same pattern as session.Session. This was a deliberate divergence from the tools registry (which is global) — instance ownership gives test isolation and avoids shared state between kernel instances.

Lazy Instantiation

Register() stores a config. The actual Agent is only created via agent.New() on the first Get() call. This means a fleet of agents can be registered at startup without paying initialization cost for ones that never get used. Capabilities are derived directly from config keys, so querying them never triggers instantiation.

Concurrency

The initial design used a read-lock fast path with double-checked locking for Get(), but we simplified to a single write lock. The TOCTOU race between releasing the read lock and acquiring the write lock would have required the double-check, but for agent access patterns the contention difference is negligible. Simpler code won.

Multi-Session Architecture

The kernel is not one-per-session — it’s a singleton managing multiple concurrent sessions. This is the central architectural insight driving Objective #2.

Every subsystem integration is scoped to a session. When a session starts, it selects an agent from the registry by name or capability. Memory is loaded per-session. Tool execution is scoped to session context. This sets the stage for child sessions when subagent orchestration arrives — a parent session spawns a child with a different agent selection, its own message history, and its own memory scope.

Dependency Graph

The objective decomposes into 6 sub-issues with explicit dependencies:

Issues #23 and #24 are complete. The observer (#25) is the remaining foundation piece before the multi-session refactor can begin.

Key Principles

• Align with external standards — the kernel’s internal types should mirror the formats they exchange with, not invent their own. Translation layers accumulate bugs at serialization boundaries.
• Lazy over eager — register capabilities at startup, instantiate on demand. The cost of deferred initialization is negligible; the cost of eager initialization scales with the number of registered agents.
• Instance over global — registries that the kernel owns should be instance-scoped for test isolation. Global registries are appropriate only for truly static registrations (like tool definitions).
• Streaming-first — retrofitting streaming onto a blocking interface is always harder than building streaming from the start. The kernel loop should consume ToolsStream natively.
• Stdlib over frameworks — at the integration boundary, the simplest correct abstraction is net/http. Frameworks earn their complexity budget in application code, not infrastructure code.

Kernel Runtime Loop

The core agentic cycle landed in PR #21: observe, think, act, repeat. kernel.New composes all subsystems from configuration, and kernel.Run executes the loop — inject the user prompt into the session, build system content from memory, call the agent with full conversation history, execute any tool calls, and repeat until the agent produces a final response or the iteration budget runs out.

The implementation surfaced several cross-cutting changes. The Agent interface evolved so conversation methods accept full message history instead of a bare prompt string, enabling the kernel to pass session context on each iteration. A duplicate ToolCall type was consolidated — format concerns pushed to the deserialization boundary where they belong. Each subsystem gained its own config lifecycle with DefaultConfig(), Merge(), and config-driven constructors, so kernel.Config composes them declaratively.

The package shipped at 93.8% test coverage with 14 tests exercising multi-step tool call chains, iteration limits, context cancellation, memory injection, and error propagation.

Runtime as the Integration Test

With the runtime loop merged, the next planned task was formal integration tests — mock-based tests exercising the composed system through deterministic agent sequences. Technically sound, but the wrong next step.

We’d established a principle in a previous project: when you have the runtime itself as a validation surface, formal integration tests are redundant at the early stage. In that project, the OpenAPI/Scalar UI served that role. Here, it’s a CLI entry point against a real LLM. So issue #15 was refactored from integration tests to a runnable kernel CLI with three built-in tools — datetime, read_file, and list_directory.

The result: when asked to “list the files in cmd/kernel and read main.go,” Qwen3 chains list_directory → read_file → summarize across three iterations, each tool call visible in the output. Every kernel subsystem is validated at runtime rather than through mocks alone. The CLI becomes both the validation mechanism and the first demonstrable artifact for stakeholders. This closed all sub-issues under Objective #1 (Kernel Core Loop).

Dev-Workflow Transitions

After completing the kernel’s first objective, an immediate workflow gap surfaced: the dev-workflow skill had no mechanism to transition between objectives. Finishing an objective meant manually closing GitHub issues, clearing planning documents, and figuring out what to do with incomplete sub-issues — all outside the structured workflow that handled everything else.

The fix split the monolithic planning command into dedicated phase and objective sub-commands, each with a transition closeout step. The closeout assesses completion status on GitHub, presents a summary, and asks the user to disposition any incomplete work — carry it forward or move it to the backlog. The core principle: no orphaned issues. Carry-forward items get atomically re-parented to the new objective after it’s created, and only then is the old objective closed.

This shipped as tau-marketplace v0.1.0 — the first minor release of the dev-workflow skill set.

Objective #2: Kernel Interface

With the core loop complete, we turned to the kernel’s next objective: its HTTP interface, the sole extensibility boundary through which external services connect. What started as “wire up ConnectRPC” became a deeper architecture session that surfaced foundational decisions:

• Agent registry — callers shouldn’t pass full agent configs. The kernel needs named agent registration with capability awareness, similar to how Claude exposes Opus, Sonnet, and Haiku as named models.
• Sessions as context boundary — the kernel isn’t one-per-session. It’s a singleton managing multiple sessions, with every subsystem integration scoped to a session.
• Streaming-first — rather than building around blocking calls and retrofitting streaming later, the kernel loop should use ToolsStream from the start. The plumbing already exists in the agent subsystem.
• Pure HTTP + SSE over ConnectRPC — following the kernel’s own principle of simple, composable patterns over complex frameworks.

The objective decomposed into 6 sub-issues with a clean dependency graph: three independent foundations (streaming tools, agent registry, observer), a central integration piece (multi-session kernel refactor), and the HTTP layer on top.

First Interface Foundations

Two of those three foundations shipped this week. The streaming tools protocol (PR #30) aligned the kernel’s ToolCall type directly with the LLM API wire format, eliminating a custom serialization layer that was dropping streaming continuation chunks. The agent registry (PR #31) introduced named agent registration with lazy instantiation — register a fleet of agents at startup without paying the initialization cost for ones that never get used.

Looking Ahead

The observer subsystem is the remaining foundation piece. Once it’s in place, the multi-session kernel refactor can begin — the central integration work that composes streaming, registry, and observer into a kernel that manages concurrent sessions with named agent selection. The HTTP layer sits on top of that. The kernel is starting to look like a service.

TAU Plugin Ecosystem

The tau plugin is distributed through the tau-marketplace and provides seven skills organized by operational domain. Each skill follows a consistent directory structure:

skills/<skill-name>/
├── SKILL.md          # Main instructions and trigger definitions
├── commands/         # Invocable subcommands (actionable workflows)
├── references/       # Pure reference material (loaded contextually)
└── dev-types/        # Development type conventions (optional)

Skills Inventory

Cross-Skill Integration

The dev-workflow skill acts as the orchestrator. It contextually loads other skills based on the session type:

• Concept and planning sessions load project-management and github-cli for project board and issue operations
• Task execution sessions load domain-specific skills (e.g., kernel for kernel development, go-patterns for Go code)
• Release sessions load github-cli for tag and release operations

This layered loading means a skill only enters context when the session actually needs it, keeping the working context focused.

Context Documents

The dev-workflow skill produces structured context documents that persist across sessions:

Each path has an .archive/ subdirectory for completed work, maintaining a clean separation between active and historical context.

CI/CD Release Pipeline

The marketplace uses a tag-triggered release workflow that automates GitHub Release creation.

Tag Convention

{prefix}-v{version}

The prefix identifies the plugin (e.g., tau), and the version follows semver. Example: tau-v0.0.7.

Workflow

The release workflow triggers on tag push:

1. Checkout — full history (fetch-depth: 0) for changelog extraction
2. Extract prefix — parse the tag to identify the plugin being released
3. Create GitHub Release — extract release notes from CHANGELOG.md using the tag prefix as a filter, publish automatically

The workflow uses the taiki-e/create-gh-release-action for changelog parsing and release creation. The entire pipeline requires no manual steps beyond pushing the tag.

Versioning

The kernel and marketplace share a versioning convention:

Dev releases track individual issue completions within an objective. The dev-workflow release command handles tagging and integrates with the CI pipeline.

Kernel Foundation Subsystems

Three Level 0 subsystems received their initial implementations this week. All three depend exclusively on core/protocol — they are independent of each other and composable by design.

Level 0 (Foundation — depend only on core/protocol):
  ├── memory   (Store, FileStore, Cache, Entry)
  ├── tools    (Registry, Handler, Execute, List)
  └── session  (Session interface, in-memory implementation)

Session Interface

The session subsystem manages conversation history. The core contract:

type Session interface {
    ID() string
    AddMessage(msg protocol.Message)
    Messages() []protocol.Message
    Clear()
}

Messages() returns a defensive copy — callers cannot mutate session state through the returned slice. The in-memory implementation is concurrent-safe with sync.RWMutex.

This work also evolved protocol.Message to support multi-turn agentic conversations:

• Role — typed string enum (RoleSystem, RoleUser, RoleAssistant, RoleTool) replacing raw strings
• ToolCall — struct with ID, Name, and Arguments fields for tool invocations
• ToolCallID and ToolCalls fields on Message — linking tool results back to their invocations

The protocol evolution means session history natively captures the full agentic conversation flow — user messages, assistant responses, tool calls, and tool results — without lossy serialization.

Tool Registry

The tool registry consolidates tool definitions into a single canonical type and provides global tool orchestration.

Unified type. protocol.Tool is the single source of truth for tool metadata, replacing the separate agent.Tool and providers.ToolDefinition types that existed previously.

Global registry. The registry follows the existing providers registry pattern:

tools.Register(tool, handler)  // Add (rejects duplicates)
tools.Replace(tool, handler)   // Update existing
tools.Get(name)                // Retrieve by name
tools.List()                   // All registered tools
tools.Execute(ctx, name, args) // Run with JSON-encoded arguments

Handler pattern. Each tool registers a handler function:

type Handler func(ctx context.Context, args json.RawMessage) (Result, error)

type Result struct {
    Content string
    IsError bool  // signals to the LLM that invocation failed
}

Built-in tools register via init() in sub-packages. External tools extend the catalog by calling tools.Register(). The registry is thread-safe with sync.RWMutex.

Memory Store

The memory subsystem provides a pluggable persistence abstraction with a session-scoped caching layer.

Store interface. The persistence contract:

type Store interface {
    List(ctx context.Context) ([]string, error)
    Load(ctx context.Context, keys ...string) ([]Entry, error)
    Save(ctx context.Context, entries ...Entry) error
    Delete(ctx context.Context, keys ...string) error
}

FileStore. The initial implementation uses the filesystem as a hierarchical key-value namespace. Keys map to file paths, entries carry their content as byte slices. Writes are atomic for durability. Hidden files (dotfiles) are filtered from listings.

Cache. The session-scoped cache wraps a Store to provide progressive on-demand loading:

1. Bootstrap — load the index (all available keys) and optionally warm specific prefixes
2. Resolve — lazy-load requested keys on demand as the session needs them
3. Flush — persist dirty entries back to the store

The cache tracks dirty and removed entries, so Flush() only writes what actually changed. It’s concurrent-safe and separates concerns cleanly: the Store is stateless (every call hits persistence), while the Cache provides session-level performance optimization.

Namespace convention. Memory is organized into namespaces:

Key Principles

1. Protocol-first design — core/protocol defines the canonical types. Subsystems consume them natively rather than defining their own representations.
2. Foundation orthogonality — session, tools, and memory are independent. None imports the other. This makes them composable without coupling.
3. Defensive boundaries — defensive copies in session, atomic writes in memory, duplicate rejection in the tool registry. Correctness at the interface level.
4. Registry pattern — both tools and providers follow the same global registry pattern: register, replace, get, list, execute. One pattern, applied consistently.
5. Store/Cache separation — stateless persistence (Store) composed with stateful session optimization (Cache). Each layer has one job.

TAU Skills Marketplace

The TAU skills marketplace is a centralized distribution point for Claude Code skills — reusable, structured workflows that standardize how the team interacts with Claude Code across all TAU repositories. This week I focused on cleaning up the marketplace plugin and onboarding team members and leadership to its usage.

For details on Claude Skills, see: Extend Claude with skills.

What the Plugin Provides

The tau plugin ships seven skills, each covering a distinct operational domain:

The dev-workflow skill is the orchestrator. It drives the full development lifecycle — from concept through release — and loads project-management and github-cli contextually when a session needs them. What this means in practice: a developer starts a session with /dev-workflow task 42, and the skill loads the relevant issue context, creates an implementation guide, and structures the work into a branch-per-issue, PR-per-task workflow.

Marketplace Changes This Week

The plugin went through several rounds of refinement:

• Restructured dev-workflow — moved actionable subcommands from references/ to commands/, separating invocable workflows from pure reference material
• Introduced issue type conventions — standardized Bug, Task, and Objective as organization-level issue types across github-cli, project-management, and dev-workflow
• Added _project/ convention — established _project/README.md, _project/phase.md, and _project/objective.md as the standard project documentation structure
• Refined the development pipeline — split validation into separate testing and validation phases, strengthened implementation guide conventions

CI/CD Release Cycle

The marketplace uses a tag-triggered release pipeline. When a tag matching the pattern {prefix}-v{version} is pushed (e.g., tau-v0.0.7), the release workflow automatically creates a GitHub Release with notes extracted from the CHANGELOG. The process is fully automated — tag and push, and the release appears on GitHub within seconds.

Why This Matters

Standardizing how the team uses Claude Code is a force multiplier. Instead of each developer learning their own patterns for issue management, project planning, and development workflow, the plugin provides a shared vocabulary and shared processes. Every project that installs the tau plugin gets the same structured workflows, the same issue conventions, and the same release process. The investment in cleaning up and onboarding pays dividends every time someone starts a new development session.

Kernel Foundation Subsystems

On the kernel side, three foundation subsystems received their initial implementations this week — each addressing a core capability that the kernel runtime loop will compose.

Session Interface

The session subsystem establishes conversation history management as a first-class kernel primitive. It defines a Session interface for adding messages, retrieving history, and clearing state — with a concurrent-safe in-memory implementation that uses defensive copies to prevent external mutation. This work also evolved protocol.Message with a Role enum and ToolCall struct, laying the groundwork for multi-turn agentic conversations.

Tool Registry

The tool registry unifies tool definitions into a single canonical protocol.Tool type and provides a global registry for tool registration and execution. Tools register with a handler function, and the registry provides lookup, listing, and execution by name. The pattern follows the existing providers registry — thread-safe, duplicate-aware, and extensible through init() functions in sub-packages.

Memory Store

The memory store implements a pluggable persistence abstraction with a Store interface for listing, loading, saving, and deleting entries. The filesystem-backed FileStore provides the initial implementation with atomic writes and hierarchical key-value namespaces. On top of the store sits a session-scoped Cache that provides progressive on-demand loading — it knows what keys are available without loading their content, resolving entries lazily as the session needs them.

What These Enable

All three subsystems sit at Level 0 in the kernel’s dependency hierarchy — they depend only on core/protocol and nothing else. They are independent and composable, which means the kernel runtime loop can compose them together without any of them needing to know about the others. That’s the next step.

Looking Ahead

The foundation is in place. The next objective tasks are the kernel runtime loop and integration tests — composing session, tools, and memory into the agentic loop that will drive the kernel. Once we get this infrastructure in place, we’ll be able to see the kernel start to come to life.

Vision

The kernel is designed around a single architectural metaphor: a closed-loop processing system — analogous to the Linux kernel — where internal subsystems compose into a complete runtime and external capabilities connect through a well-defined interface boundary.

Each subsystem handles one responsibility. Subsystems compose through explicit Go interfaces. The kernel has zero awareness of what connects to it from the outside. This separation means the same kernel binary works whether extensions run locally on the host or as networked services in containers.

The design philosophy is deliberately simple: composable patterns over complex frameworks, following Anthropic’s guidance on building effective agents.

Subsystem Topology

Nine subsystems organized by domain, each implemented as a top-level Go package within the module:

Each subsystem is a Go package with explicit imports. The compiler enforces that dependencies only flow in one direction — there are no circular imports, no runtime discovery, and no interface-based indirection to work around dependency constraints.

Dependency Hierarchy

The subsystems are organized into four layers by dependency depth:

• Layer 0 — core has no internal dependencies. It provides the shared type vocabulary (protocols, messages, responses, configuration) that every other subsystem builds on.
• Layer 1 — agent, memory, tools, and session each depend on core and nothing else. These are the foundational subsystems that can be built and tested independently.
• Layer 2 — skills depends on memory for filesystem patterns. mcp depends on tools for the ToolExecutor interface. orchestrate depends on agent for the Agent interface. Each builds on exactly one Layer 1 subsystem.
• Layer 3 — kernel composes all subsystems above into the agent runtime. It is the only package that depends on the full dependency graph.

The hierarchy is strict and acyclic with a maximum depth of three. Go’s import rules enforce this at compile time — a package at a given layer may depend on packages below it but never on packages at the same layer or above. What this means in practice: any subsystem can be tested in isolation with only its declared dependencies, and breaking changes are caught immediately by go test ./... across the entire module.

Build Order

The dependency hierarchy translates directly into a phased implementation plan:

Each phase builds exclusively on the previous phase. Phase 1 subsystems depend only on Phase 0. Phase 2 subsystems depend on Phase 0 and Phase 1. This ordering is not a scheduling preference — it reflects actual dependency constraints that the compiler enforces.

Extension Architecture

The kernel is a closed-loop system. It composes its nine subsystems into a complete agent runtime without external dependencies. Extensions — persistence backends, identity and access management, container sandboxes, MCP gateways, observability pipelines, user interfaces — connect through the kernel’s interface rather than being compiled into it.

The interface is exposed via ConnectRPC, which provides gRPC-compatible service definitions over standard HTTP. ConnectRPC was chosen because it is Go-native (standard net/http handlers), supports multiple protocols simultaneously (gRPC, gRPC-Web, and Connect), and generates type-safe client and server code from Protobuf schemas.

What this means in practice: instead of forking the kernel to add a custom tool provider or a different memory backend, you implement the service interface and connect over the network. The kernel does not need to know — or care — what connects to it. A local development setup might use filesystem persistence and an Ollama instance on the host. A production deployment might use cloud-hosted persistence and Azure AI Foundry. The kernel binary is the same in both cases.

Versioning

The monorepo uses a single version scheme for the entire module:

• Phase target: v<major>.<minor>.<patch> (e.g., v0.1.0)
• Dev releases: v<target>-dev.<objective>.<issue> (e.g., v0.1.0-dev.3.7)

All subsystems share one version tag and one release. Pre-1.0 signals that APIs are still stabilizing. When the kernel reaches 1.0, all subsystems share that stability guarantee — a single version for a single product.

Key Principles

1. One module, one version — all subsystems share a single Go module and release tag
2. Dependency hierarchy enforced by the compiler — imports only flow downward through the subsystem layers
3. Closed-loop kernel, open extension boundary — the runtime is self-contained; external capabilities connect through ConnectRPC service interfaces
4. Build order reflects dependency order — implementation phases follow the natural dependency graph from core upward
5. Packages that change together live together — repository structure aligns with how the code actually evolves

What Changed

The original TAU architecture distributed the agent runtime across nine separate repositories, each with its own Go module and version:

• tau-core — foundational types (protocols, messages, responses, configuration)
• tau-agent — LLM client (agent interface, providers, request pipeline)
• tau-orchestrate — multi-agent coordination (hub, state, workflows, observer)
• tau-tools — tool execution (registry, permissions, built-ins)
• tau-memory — persistent memory (bootstrap, working memory, notes)
• tau-session — conversation management (history, compaction)
• tau-skills — progressive disclosure (SKILL.md discovery, loading)
• tau-mcp — MCP client (transport, tool discovery)
• tau-runtime — agent runtime (agentic loop, plan mode, hooks)

All nine now live as packages within a single Go module. Import paths changed accordingly:

tau-core/pkg/protocol     →  kernel/core/protocol
tau-agent/pkg/agent       →  kernel/agent
tau-orchestrate/pkg/hub   →  kernel/orchestrate/hub

The module path is github.com/tailored-agentic-units/kernel, and the repository follows the kernel architectural metaphor — a single codebase with internal subsystems, each responsible for a distinct domain.

Why a Monorepo

The multi-repo strategy introduced friction that was disproportionate to the project’s scale. Three categories of overhead made the case for consolidation.

Version cascade. A change to tau-core required cascading commits and tags through tau-agent and tau-orchestrate — three or more commits and three or more tags for what was conceptually a single atomic change. Complex release procedures for identifying changed modules, determining version numbers, and tagging in the correct dependency order compounded the effort of every release.

Diamond dependency risk. Multiple libraries depending on different versions of tau-core during rapid iteration created version skew. The go.work workspace file coordinated the nine modules during development, but it was a workaround for a structural mismatch — the code was split across repository boundaries that did not reflect actual dependency boundaries.

Organizational overhead. Nine repositories meant nine CI configurations, nine CLAUDE.md files, nine settings.json files, nine release workflows, and nine label taxonomies to keep in sync. Each new repository required its own infrastructure bootstrapping, and each repository carried operational surface area that had to be maintained independently — even though the libraries changed together.

The Go team’s own guidance reinforces the decision: “Packages that change together should live together.” The Go standard library is a monorepo precisely because its packages have deep interdependencies and need atomic updates. The TAU kernel has the same property.

Why Now

The timing was ideal. Only three of nine repositories had any code — tau-core, tau-agent, and tau-orchestrate. The remaining six were skeleton-only. The project is pre-release with zero external consumers, no published tags, and no downstream dependencies. The cost of migration was near zero; the cost of waiting would have compounded with every subsystem implementation and every release tag.

What This Means in Practice

The monorepo gives the kernel five immediate structural advantages:

• Atomic commits — changes that span subsystem boundaries are a single commit, not a coordinated cascade across repositories
• Single version — one tag, one release, no dependency ordering to manage
• One CI pipeline — go test ./... validates the entire kernel in a single run
• Compiler-enforced boundaries — Go’s import rules prevent inappropriate cross-dependencies between packages, providing the same isolation that separate repositories offered but without the operational overhead
• Full context — every contributor and every tool (including Claude Code) has the complete codebase available, with no context switching between repositories

The Kernel Architecture — Overview covers the subsystem topology, dependency hierarchy, and build order in detail.

The monorepo provides the structural foundation for the next phase of development — defining the subsystem interfaces and implementing the build order that will compose the kernel into a unified agent runtime.

Core Principles

• Start at the lowest level using latest supported features, expand complexity as needed
• Vanilla CSS from scratch — no frameworks, no preprocessors
• Jekyll without a theme gem — raw Liquid layouts, full control
• Deterministic operations separated from non-deterministic (style inference runs once, not per-post)
• Single skill with sub-command routing, not multiple independent skills
• Media stored outside git history via GitHub Releases (one release per post)

Technology Stack

Repository Structure

jaime/
├── .github/
│   └── workflows/
│       └── pages.yml              # Jekyll build + deploy to Pages
├── .claude/
│   ├── CLAUDE.md                  # Project-level Claude Code instructions
│   ├── context/
│   │   └── style-profile.md       # Generated writing voice calibration
│   └── skills/                    # Skill plugins (dev-blog, theme-design)
├── _config.yml
├── _layouts/
│   ├── default.html               # Base HTML5 shell (head, nav, footer)
│   ├── home.html                  # Index page with post listing
│   ├── post.html                  # Individual blog entry (all content types)
│   └── category.html              # Category index with pagination
├── _includes/
│   ├── head.html                  # Meta, CSS, SEO, feed
│   ├── nav.html                   # Site navigation with category dropdown
│   ├── post-card.html             # Reusable post listing card
│   ├── pagination.html            # Prev/next page controls
│   └── video.html                 # Reusable video tag partial
├── _posts/                        # Published markdown (date-prefixed)
├── _drafts/                       # Authoring target, excluded from production
├── _capture/                      # Capture buckets (excluded from Jekyll build)
├── assets/
│   └── css/
│       ├── index.css              # Layer order declaration + imports
│       ├── reset.css              # Modern CSS reset
│       ├── tokens.css             # Design tokens (colors, spacing, type scale)
│       ├── typography.css         # Font assignments, heading scale, code
│       ├── colors.css             # Semantic color mapping + syntax highlighting
│       ├── layout.css             # Page structure, vertical rhythm, spacing
│       ├── borders.css            # Border styles for tables, dividers, code
│       ├── transitions.css        # Link and interactive element transitions
│       └── components.css         # Nav, post cards, tags, pagination
├── 404.html                       # Custom 404 page
├── Gemfile
└── index.md                       # Home page

Key Structural Decisions

• _drafts/ is the default authoring target. Jekyll ignores drafts in production, creating a review gate before publish.
• _capture/ is excluded from the Jekyll build via _config.yml. Capture buckets live in the repo for traceability but never render.
• assets/media/ is gitignored entirely. It exists only as a local staging area — on publish, media is uploaded to a GitHub Release and the directory is created on demand.
• One post layout handles all content types. Differentiation is expressed through frontmatter tags and categories, not separate templates. Category index pages are auto-generated via jekyll-paginate-v2 autopages.

CSS Architecture

The stylesheet is organized into cascade layers, with each layer defined in its own file and imported through a single entry point:

/* index.css */
@layer reset, tokens, typography, colors, layout, borders, transitions, components;

@import url("./reset.css");
@import url("./tokens.css");
@import url("./typography.css");
@import url("./colors.css");
@import url("./layout.css");
@import url("./borders.css");
@import url("./transitions.css");
@import url("./components.css");

Layer Responsibilities

Light and Dark Mode

The color system follows a “theme colors as source of truth” architecture. Three role-based theme colors are defined as direct hex values, and Base16 accent slots derive from them where applicable:

:root {
  /* Theme colors — source of truth */
  --color-chrome: #4cd48a;
  --color-interactive: #5e8ef0;
  --color-emphasis: #e464a0;

  /* Base16 accents — derived from theme where applicable */
  --base0B: var(--color-chrome);
  --base0D: var(--color-interactive);
  --base0E: var(--color-emphasis);
  /* ... remaining accents use independent values */
}

Light mode overrides the theme colors and freely remaps Base16 accent slots without conditional logic:

@media (prefers-color-scheme: light) {
  :root {
    --color-chrome: #0e8848;
    --color-interactive: #1858d0;
    --color-emphasis: #d02878;

    /* Accents remapped for light mode balance */
    --base0A: var(--color-emphasis);  /* pink — types */
    --base0E: #5a38c0;               /* indigo — keywords */
  }
}

Syntax highlighting maps Rouge token classes to Base16 slots in colors.css, so both dark and light modes receive appropriate highlighting from the same set of rules.

Media Strategy

Problem

Git history bloats with binary files. GitHub Pages does not serve Git LFS-tracked files (resolves to pointer files).

Solution

GitHub Releases as a per-post CDN.

• Tag pattern: post/{slug} (e.g., post/introducing-the-dev-blog)
• All media for a post uploaded as release assets
• Stable download URLs: https://github.com/tailored-agentic-units/jaime/releases/download/post/{slug}/{filename}

Video Support

Raw HTML passes through kramdown unchanged. A reusable include handles the common case:

{% include video.html src="https://github.com/.../demo.mp4" %}

Resolved by _includes/video.html:

<video controls width="100%">
  <source src="" type="video/mp4">
</video>

Capture / Draft / Publish Workflow

A three-stage authoring pipeline that captures development progress incrementally rather than reconstructing it at the end of the week.

Capture

As noteworthy work is completed, a brief entry is staged into a named bucket:

_capture/
└── 2026-02-07-introducing-the-dev-blog/
    ├── 01-blog-scaffold.md
    ├── 02-css-architecture.md
    └── media/
        └── screenshot.png

Each bucket follows the naming convention [date]-[slug]. Entries within are ordered by sequence number and include a description with optional media references.

Draft

When it’s time to write, the draft command reads all entries from a specified bucket and generates a rough draft in _drafts/ with validated frontmatter. The style profile calibrates the voice. Media references point to local staging paths.

Publish

The publish command finalizes the draft:

1. Promotes the post from _drafts/ to _posts/ with the current date prefix
2. Creates a GitHub Release tagged post/{slug}
3. Uploads all associated media as release assets
4. Rewrites media paths in the post to release download URLs
5. Commits and pushes

Skill Plugin Design

The blog is managed through a single Claude Code skill with sub-command routing. The skill is distributed as a plugin — the blog-specific content (posts, captures, style profile) is generated at runtime, not shipped with the skill.

Command Routing

Context Layer

The style profile lives at the project level, not within the skill — each user generates their own via the calibrate command. If the profile doesn’t exist when draft or publish runs, the skill triggers calibration first.

Deployment

The site deploys automatically via a GitHub Actions workflow triggered on push to main:

jobs:
  build:
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "4.0"
          bundler-cache: true
      - run: bundle exec jekyll build
        env:
          JEKYLL_ENV: production
      - uses: actions/upload-pages-artifact@v3

  deploy:
    needs: build
    steps:
      - uses: actions/deploy-pages@v4

The workflow requires pages: write and id-token: write permissions. The repository’s Pages settings must be configured to deploy from GitHub Actions rather than a branch.

Key Principles

1. Push markdown, get HTML — the entire publishing pipeline is git-native
2. Media outside git — GitHub Releases serve binary assets without bloating history
3. System-responsive design — light and dark modes follow user preference with zero JavaScript
4. Capture incrementally, publish periodically — the authoring workflow matches how development actually happens
5. Skill automates, user owns — the plugin manages process; content, voice, and style belong to the author

Why a Blog

A static blog built on GitHub Pages brings several advantages over email-based communication:

• Accessible without authentication — posts are public web pages that can be shared by link with anyone, without requiring access to an email client or organizational inbox
• Shareable to a broader audience — stakeholders, collaborators, and anyone interested can follow development progress without needing to be on a distribution list
• Integrated into the development workflow — the blog lives in a git repository and deploys automatically via GitHub Actions, so publishing is as natural as pushing code
• Proper technical formatting — syntax-highlighted code blocks, tables, markdown links, and structured layouts render the way they should
• Establishes a repeatable standard — the same approach can be adopted by other developers to provide leadership a consistent format for staying informed on development progress

The net result is that communication around development progress becomes more accessible, more shareable, and more tightly integrated with the work itself.

The Capture Workflow

Beyond just hosting posts, the blog introduces a structured capture workflow designed around how development actually happens. Instead of sitting down at the end of the week and trying to reconstruct what was accomplished, the workflow encourages capturing noteworthy developments as they occur.

The process works in three stages:

1. Capture — as something worth communicating is completed during the week, a brief entry is staged into a date-stamped bucket directory. Each entry includes a description and optional media references.
2. Draft — when it’s time to write the update, the captured entries are organized into a rough draft that provides the structural foundation for the post.
3. Publish — the draft is finalized, any media assets are uploaded to a GitHub Release for hosting, and the post goes live on the site.

This approach ensures that nothing significant falls through the cracks, and the weekly writing process starts from a foundation of structured notes rather than a blank page.

What to Expect

The blog will primarily feature two categories of content:

• Progress — regular posts covering development progress, new capabilities, and strategic direction across the TAU ecosystem. These are the successor to the weekly email updates.
• Engineering — technical architecture and design documents that capture the thinking behind significant decisions. These serve as both communication artifacts and living references for implementation.

This may evolve as my workflow evolves, but this is the state it’s starting out in for now. Looking forward to making the most of this new format.