Stack Guide

→ Documentation Index | Related: Glossary | Unified Stack Architecture

Purpose

This guide is the fast path for navigating the unified stack. Use it when you need to know where to start reading, which package owns a concern, and which docs are normative versus supporting context.

Start Here

If you are new to the stack, read these in order:

1. System Overview
2. Glossary
3. Unified Stack Architecture
4. V6 Architecture Specification
5. Package Specifications

Then branch into the area you are actually changing.

Before proposing a new seam, run the active validation cue for the first executable V6 slice:

• npm run verify:v6:seams

If You Need To Change Orchestration

Read:

• V6 Architecture Specification
• Package Specifications
• Testing Framework

Work mainly in:

• packages/sdk
• packages/babysitter
• packages/babysitter-agent
• library/
• project-local .a5c/processes/

If You Need To Change Harness Dispatch

Read:

• docs/agent-mux/README
• Agent-Mux Integration
• Unified Stack Architecture

Work mainly in:

• packages/agent-mux/core
• packages/agent-mux/adapters
• packages/agent-mux/cli
• packages/agent-mux/sdk
• packages/agent-mux/gateway

If You Need To Change Hook Behavior

Read:

• packages/hooks-mux/README.md
• packages/hooks-mux/ARCHITECTURE.md
• Agent-Mux Integration

Work mainly in:

• packages/hooks-mux/core
• packages/hooks-mux/cli
• packages/hooks-mux/adapter-*
• plugins/babysitter-unified/hooks/

If You Need To Change Plugin Packaging

Read:

• packages/agent-plugins-mux/unified_plugin_system_spec.md
• plugins/babysitter-unified/README.template.md
• per-harness plugin README files under plugins/babysitter-unified/per-harness/

Work mainly in:

• packages/agent-plugins-mux
• plugins/babysitter-unified
• concrete bundles under plugins/babysitter-*

If You Need To Change Human Approval Or Breakpoint Routing

Read:

• packages/breakpoints-mux/specs/architecture.md
• Testing Framework

Work mainly in:

• packages/breakpoints-mux
• packages/sdk breakpoint integration
• related hook and plugin surfaces if the transport changes

If You Need To Change UI Surfaces

Read:

• packages/agent-mux/README.md
• package README files under packages/agent-mux/*

Work mainly in:

• packages/agent-mux/ui
• packages/agent-mux/webui
• packages/agent-mux/tui
• packages/agent-mux/mobile-*
• packages/agent-mux/tv-*
• packages/agent-mux/watch-*
• docs-site/ or packages/atlas/webui where relevant

Source-Of-Truth Map

Use this rule of thumb:

Concern	Primary source of truth	Supporting references
V6 architecture scope	docs/v6-spec-and-roadmap/	package READMEs, adversarial analyses
Orchestration runtime behavior	packages/sdk, packages/babysitter, packages/babysitter-agent	V6 docs, CLI docs
Harness dispatch behavior	packages/agent-mux/* and docs/agent-mux/	V6 integration docs
Hook normalization	packages/hooks-mux/*	per-harness plugin docs
Unified plugin packaging	packages/agent-plugins-mux, plugins/babysitter-unified/	install READMEs for concrete bundles
Breakpoint routing	packages/breakpoints-mux	SDK integration docs

Practical Rules

• Start from the package that already owns the behavior before proposing a new layer.
• If a document describes a future package or layer, check whether V6 marks it as deferred.
• Treat installable plugin bundles as real compatibility surfaces even when the unified plugin source exists.
• Use package names and paths when discussing ownership; use architecture terms only when they map to a real current seam.
• Treat validation commands as part of the architecture surface. If a seam has no repo path and no active validation cue, it is still design exploration.

---

Related Documents: Current State | Glossary | Unified Stack Architecture