How zstack fits together

zstack is an instruction library for your coding agent. It connects a goal to a workflow, the guidance needed for decisions, and checks of the result. The host—Codex or Claude Code—provides execution capabilities.

Use these maps to explore three different questions: what each component does, how a request moves through a workflow, and where installed files live. The controls only change the illustrations; they never execute commands.

The component map

Skills define processes. Playbooks sequence work. Principles guide decisions. z-mode connects them for an engineering task. You can also invoke a focused skill directly without using the mode.

Your requestGoal + scope + observable done condition

Choose a focused skill or invoke z-mode ↓

Shared libraryskills/

Expand a layer to see its responsibility.

Workflow skillsGive a named job a repeatable process+

Invoke a focused skill directly, or let the explicitly selected mode read a relevant companion. Each SKILL.md supplies instructions; references and scripts support that process.

how · why · architect · tdd · recall

Explore Workflow skills

z-modeRoute an engineering request+

The mode chooses the matching playbook and loads principle leaves when they affect a decision. Small work runs directly. The mode persists in conversation until you stop it; a handoff carries that context into another session.

One selected workflow, task-sized context

Explore z-mode

PlaybooksDescribe the steps for this kind of work+

A bug starts with reproduction; an investigation stays read-only; a feature starts with observable acceptance. Playbooks live under z-mode and are read as workflow instructions, not installed as separate commands.

investigation · bug-fix · feature · pause-safely

Explore Playbooks

PrinciplesGuide decisions inside the workflow+

Principle skills are decision guidance, loaded only when relevant. They do not add authority or require every task to run through every principle.

fix root causes · prove it works · boundary discipline

Explore Principles

References & helper scriptsResolve from the real skill directory. Run target commands in the target repository.

Instructions are read by the host ↓

Native hostCodex or Claude Code

The host supplies the model, tools, permissions, sessions, and available delegation.

Direct executionOne agent handles a scoped task and checks the result.

Delegation, when allowedz-agent owns an engineering slice. comment-sicko reports comment findings; the parent applies accepted edits.

Inspect artifacts and actual checks ↓

Result + evidence + limitsAn explanation, verified local change, or durable handoff.

Solid layers are instructions; the dashed boundary marks capabilities controlled by the host. Installing zstack does not grant permissions or start background services.

Reading the connections

• Request to instructions: $how asks for a focused behavior trace; $z-mode selects a workflow for a broader task. Claude Code uses /how and /z-mode.
• Mode to playbook: the mode reads the selected playbook, not every workflow. A playbook can call for companion skills and relevant principles.
• Instructions to execution: the host executes within its available tools and permissions. A native role is a scoped worker, not a second workflow engine. The parent waits for terminal results and inspects artifacts.
• Execution to evidence: a test exit, observed UI behavior, or cited source supports the result. Starting a worker or writing a test does not prove the outcome.

Explore the workflow skills, playbooks, and principles for the full contracts. If delegation is unavailable, the agent works directly and discloses missing independent coverage.

Follow a request

Choose a task to see its input, selected playbook, main steps, decision guidance, and output. These are representative examples; z-mode has other routes for performance, reviews, queues, and more.

A concrete behavior question$z-mode explain the retry path; no editsClaude Code uses /z-mode with the same request.

z-mode selects investigation↓

1. 1
   Trace

   Read entry points and callers with how. Use why when motivation matters.

2. 2
   Compare

   For a decision, compare relevant alternatives against the evidence.

3. 3
   Report

   Return a cited explanation and name any gaps.

Decision lens: Guard the context windowLoad only context that advances the question. Other relevant principles may be read as needed.

Return observed evidence ↓

Cited answer; product files unchanged.An investigation does not authorize a fix or an unsolicited prototype.

Illustrative routes, not an executing agent. Failed or inconclusive verification leads back to investigation; it is not a successful completion.

Evidence controls the next step

The path is not always linear. A failed repro sends a bug fix back to tracing. An unavailable tool leaves an explicit proof gap. A resumed session rechecks the current files and branch before trusting a saved handoff.

Publication is a separate requested action. Passing local checks does not grant permission to commit, push, open a PR, merge, or deploy. See build and verify and long work and handoffs.

From checkout to host

For linked installations, skills are linked and agents are copied. Switch hosts and installation scopes to see why the stable checkout, discovery directories, and ownership receipt all matter.

Host CodexClaude CodeScope PersonalProject

Stable library checkoutKeep this location available

skills/<name>/One canonical source for both hosts

Link↓

~/.agents/skills/<name>Resolves back to the checkout, including referenced resources

agents/codex/Standalone TOML roles

Copy↓

~/.codex/agents/Owned copies of z-agent and comment-sicko

Ownership receipt~/.codex/zstack-install.jsonRecords source and owned files for updates and safe removal.

Default paths shown. CODEX_HOME changes the native agent and receipt root; skills stay in ~/.agents/skills. Explicit --home uses an isolated root instead.

Preview from the library checkoutuv run scripts/install.py --host codexReview the plan, then repeat with --apply. Start a new host session.

What changes on update or removal?+

Linked skills reflect checkout changes. Rerun installation to create new links and update unchanged owned agent copies. Edited agent copies produce a collision.

Uninstall removes this checkout’s links and unchanged owned copies; modified or unowned files remain. Complete removal in every scope before moving the checkout.

Full update and removal procedure

This map explains file ownership. It does not install anything, grant project trust, enable agents, or change model and permission settings.

The native Codex plugin uses a different path: checkout → dist/zstack → Codex plugin cache. It packages skills and a session hook, with no installer receipt or bundled agent registration. Rebuild and refresh the plugin to apply checkout changes. The Claude Code plugin loads skills, the hook, and both agent roles in place from the checkout; changes apply at the next session or /reload-plugins.

The installed link leads back to the real skill directory for references and helpers. Commands that operate on your product still run in the target repository. The library checkout and the target project can live in entirely different places.

Follow install and route work for collision handling, updates, removal, and checkout relocation. The Codex and Claude Code pages cover native configuration and discovery limits.