Architecture

This repo's architecture keeps bundled runtime free of dependency install steps. The runtime files that provider manifests, docs, and users execute are committed, dependency-free Node ESM that use only the standard library. Provider-backed workflows invoke configured peers through the owned provider CLI; they still require those external provider tools.

The instruction-only seshtk-cli skill uses the external @tkstang/session-toolkit CLI for execution. That prerequisite is installed separately and checked before use; the skill does not automatically install it.

To keep those committed runtime files maintainable, every skill has one canonical authored owner under src/skills/. Shared and plugin code lives under explicit src/shared/ and src/plugins/ owners. A distribution catalog renders complete standalone and plugin-local payloads, including compiled .mjs where needed. TypeScript, Vitest, and bundling never become runtime dependencies of a shipped skill.

The architecture favors one editable source with generated consumers because manually maintained copies drift. Explicit targets avoid two opposite errors: forcing every user to install a whole plugin when a standalone unit is enough, and advertising every skill as standalone without boundary evidence. Runtime dependencies are bundled into an installation unit; workflow prerequisites stay explicit instead of growing into a universal installer. See Decisions for the accepted rationale.

One skill, every installation form

A skill is authored once under src/skills/; the build emits every declared installation form, and provider manifests and marketplace catalogs are release-owned rather than generated. session-retro is the worked example: standalone session-retro, Session plugin member retro.

Why this strategy

The source tree is organized by ownership, not by installation layout:

This is one source of truth for product skills and runtime, not a claim that every authored file belongs in src/. Documentation, developer tooling, provider manifests, and marketplace catalogs have their own maintained homes.

The tradeoffs are deliberate:

• TypeScript for contributors, JavaScript for consumers. Type checking and tests improve feedback while committed Node ESM keeps TypeScript, a bundler, and an npm install out of the user's runtime requirements.
• One authored owner, several generated forms. Fix a skill once and render each installation form from that source. The cost is a rebuild and generated diff that contributors must review.
• Self-contained installation units. Bundle or materialize shared runtime inside the unit instead of importing a sibling installed skill or this checkout. This duplicates generated bytes, not source ownership, and avoids coupling separately installed skills to each other's filesystem layout.
• Explicit distribution declarations. Being authored here does not make a skill standalone automatically. Each target needs a declared shape and packaging evidence; plugin membership is not inferred from code sharing.
• Checks instead of manual synchronization. build:check compares generated inventories, bytes, and executable modes against canonical inputs. Committed outputs stay useful only if drift is caught.

See TypeScript & Build Tooling for the contributor workflow and Decisions for the rationale and alternatives behind the architecture.

Deeper references

• Build & Distribution — the build contract that maps canonical skill, shared, and plugin sources to complete standalone/plugin payloads, and the rule that those outputs are never hand-edited.

• Consensus Runtime — how wrappers, the deliberation loop, and provider subprocesses exchange verdicts and persist resumable state.

• Shared transcript-core — per-provider transcript knowledge has one source of truth, and each consuming skill ships a committed generated copy rather than importing across skills.

• Cursor collaboration reliability — exact identity, physical-frame observation, isolated continuity state, and lease-scoped completion keep availability separate from automatic continuation.

• Agent Messaging — durable external mail and immutable logs stay separate from finite host attention, while one activation/controller owns any composed continuation route.

Contents

• Repository Layout — Find authored source, generated installation units, manifests, and developer tooling.
• Build & Distribution — The canonical-owner → complete standalone/plugin payload build contract and the never-hand-edit rule.
• Consensus Runtime — Execution boundaries, structured verdicts, durable state, and mode-dependent outcomes.
• Agent Messaging — Durable mailbox state, finite delivery activation, observer composition, and evidence boundaries.
• Shared transcript-core — One source of truth for per-provider transcript knowledge, with a committed generated copy per consuming skill.
• Native session schemas — What Codex, Claude Code, and Cursor actually write to their transcripts, observed from recorded sessions.
• Cursor collaboration reliability — Exact identity, content-first observation, state continuity, and lease-scoped completion for Cursor collaboration.