Composition Stack

Why externalize expertise

An LLM agent session has a fixed context window. A monolithic agent that holds all operational and domain knowledge in its persona will context-collapse on long workflows.

The composition stack externalizes expertise procedurally:

• load minimum harness contract at session start
• provision domain expertise on demand
• delegate vertical slices to isolated agent contexts
• enforce transitions deterministically outside agent control

Each layer has one responsibility. Higher layers orchestrate. Lower layers store or execute procedural knowledge.

---

The stack

Playbook (.pb.yaml)           atomic domain procedure
    ↑ composes into
Skill (SKILL.md)              SDLC orchestration composition
    ↑ invoked by
Command                       orchestration entry point
    ↑ executes
Workflow stage (YAML)         stage contract bound to DSL
    ↑ delegates to
Agent (.md persona)           isolated cognitive execution context
    ↑ coordinated by
Runtime harness               lifecycle, hooks, gates, memory, trace

The agent sits inside the harness — not at the top of the stack.

---

Playbooks — procedural operational specifications

Location: .sdlc/playbooks/domains/{domain}/{name}.pb.yaml

A playbook is not documentation, not a long prompt, not informal instructions. It is an executable procedural specification:

• what must be done
• how to do it
• how to measure and validate
• completion criteria
• constraints and fallbacks

Lazy-loaded via sdlc_playbook.py provision — never at sessionStart.

Acquisition: /sdlc:learn (research → synthesis → materialize → deliver).

See Playbooks.

---

Skills — procedural composition structures

Location: {specialization_layer}/skills/{name}/SKILL.md

Skills organize SDLC operations. They may compose multiple playbooks for a task class:

Skill	Composes
worktree	Git isolation protocol
spec-writer	Intent → structured spec
{provider}-ticket	Work-items API (generated per integration)
handoff	Session continuity recording
qa-recording	Multi-resolution browser evidence
browser-user	Authenticated browser via user MCP

A skill is not required to be atomic. It coordinates capabilities and playbooks as needed.

---

Commands — orchestration entry points

Location: {specialization_layer}/commands/{name}.md

Commands represent high-level intent. They do not execute procedures directly. They trigger:

• workflow stage graph from DSL binding
• skill invocations at stage boundaries
• playbook provision when playbooks_when: matches
• gate checks before stage transitions

The command is the operator interface. The harness executes the chain.

---

Workflows — DSL stage contracts

Location: .sdlc/workflows/*.yaml

Machine-readable stage graphs: agents, inputs, outputs, blocking behavior, success criteria.

Workflows are runtime-neutral. They bind to commands via sdlc.yaml:

workflows:
  feature:
    definition: .sdlc/workflows/feature-flow.yaml
    trigger: /implement-feature

See Workflows.

---

Agents — isolated cognitive contexts

Location: {specialization_layer}/agents/{name}.md

One stage, one persona, one scope. Subagents dispatch in isolated worktrees/threads.

Agent	Stage
planner	Decomposition, interfaces, E2E scenarios
implementer	Production code from plan
reviewer	Architecture rule gate
qa	Browser-native validation
deployer	Staged release pipeline
incident-resolver	Production triage → fix PR

Separation prevents the same context from writing and certifying the same code.

---

Macro composition: /sdlc:e2e

The orchestrator is a composer — manifest owner, wave orderer, gate enforcer. It composes feature-flow executions; it does not reimplement them.

Stage	Delegates to
decomposition	planner
work-items-hierarchy	/spec:create per slice
execution	/implement-feature per ticket (subagent, worktree)
deploy	/deploy-release
reflect	/sdlc:reflect + /handoff

Forbidden: implement {target_root}/** in main session; mark stages complete without gate passage; consolidate tickets into one worktree.

---

Inference inside governed bounds

Layer	Nature
Playbook constraints	Deterministic bounds on procedure
Workflow success criteria	Deterministic completion definition
Gate scripts	Deterministic transition enforcement
Agent reasoning within stage	Adaptive inference

The stack separates what must be true to proceed (deterministic) from how to accomplish the stage (adaptive).

---

Mental model

Think of the harness as an operating system:

• Playbooks = specialized drivers (loaded on demand)
• Skills = system calls (orchestration primitives)
• Commands = shell entry points
• Workflows = process definitions
• Agents = processes (isolated address spaces)
• Gates = kernel enforcement — no process marks itself done
• DSL = system configuration

The LLM is compute inside a process — not the OS.

---

Worked example: docs-artistry learn run

The /sdlc:learn pipeline that produced architecture doc review capability:

/sdlc:learn "architecture documentation artistry"
    → pb.engineering.pedagogical-profiles
    → pb.docs.architecture-review
    → pb.docs.visual-enrichment-gate
    → pb.docs.architecture-artistry (orchestrator)
    → /sdlc:e2e docs-artistry-20260530
        → gpt-image-2 light-blueprint illustrations
        → Starlight content elevation

This is the meta-pattern: learn adds playbooks to the catalog; e2e implements vertical outcomes; gates verify assets on disk.

See Playbooks and Architecture.

See Architecture.