Stack Plugin

Untap, Upkeep, Draw, Deploy

Stack is an agentic DevOps workflow plugin for Claude Code. It manages your project's planning, development, testing, and review through a file-based board (.stack/BOARD.md): you describe what you want built, and an orchestrator dispatches five specialized agent roles — product owner, architect, developer, tester, and a four-angle review panel — one task at a time, in strict depends-on order.

Blocked work never silently retries; it waits for your decision. Small fixes can jump the queue. Sessions pick up exactly where the last one ended, and everything ever completed or dropped is preserved in a browsable graveyard archive. An optional MTG-flavored naming mode (stack:theme) reskins the board's labels — tasks become Spells, the backlog becomes The Stack — without changing any underlying data.

New to this kind of tool? GUIDE.md walks through the whole workflow in plain language — no technical background needed.

Installation Guide

Plugins load at session start — install first, then open a session in the project you want Stack to manage (.stack/ is created there on your first "start turn").

Option 1 — Try it without installing (local development):

claude --plugin-dir D:\path\to\stack

Loads the plugin for that session only. While iterating on the plugin's files, apply changes mid-session with /reload-plugins — no restart needed.

Option 2 — Install from a local clone (persistent):

Inside any Claude Code session:

/plugin marketplace add D:\path\to\stack
/plugin install stack@stack-marketplace

The plugin is then available in every future session.

Option 3 — Install straight from GitHub:

/plugin marketplace add kinojms/stack
/plugin install stack@stack-marketplace

No setup needed — the repo is public.

Staying up to date: enable auto-update once — /plugin → Marketplaces tab → stack-marketplace → Enable auto-update — and new versions are fetched in the background after each session starts (you'll be prompted to /reload-plugins when one lands). Or update manually anytime with /plugin marketplace update stack-marketplace.

Then say start turn in your project and answer two questions (naming mode, review mode) — the board takes it from there.

Using another AI tool? Stack's core is platform-neutral. A ready-made OpenAI Codex CLI adapter lives in codex/ (skills install natively — Codex reads the same SKILL.md standard — plus TOML role agents and an AGENTS.md snippet). Platform bindings for other tools: skills/cast/references/platforms.md.

Quick Start

# Begin your first work session — initializes .stack/ and asks your
# naming mode (default/mtg) and review mode (parallel/sequential)
start turn

# Add something to build
stack:new "User authentication"

# The work cycle dispatches the chain: product-owner → architect →
# developers → tester → reviewers. Continue until done or say no.

# End the session — prints a copy-paste-ready EoD report
end turn

Two Workflows

On a fresh project, start turn asks which workflow you want:

Prototype mode is for hackathons, spikes, and "will this even work?" — you expect to throw the code away, so the gates that check for correctness are the wrong trade. It still uses the board, the graveyard, and the session log, and blocked still blocks — nothing auto-retries.

When the prototype proves out, stack:promote switches to standard one-way and asks what to do with the code: keep it (every recorded shortcut becomes a Harden prototype requirement, planned and reviewed like any other work) or start clean (the board history is archived; your code files are never touched).

Existing projects always get standard mode, without being asked — say start turn the same way. The first time you add a requirement (stack:new) in a project that already has code Stack didn't build, stack:analyst scans the codebase first and shows you a plain-language report (tech stack, structure, conventions, notable risks) before anything is created. The report is saved to .stack/docs/CODEBASE-ANALYSIS.md and read by the product-owner and architect on every requirement after that. Runs once per project — later stack:new calls skip straight to the usual flow.

The Agent Chain

[standard mode]
User input
  └→ product-owner: interviews you, writes REQ with acceptance criteria
      └→ architect: explores codebase, writes PLAN (per-task subsections),
         declares the task chain with depends-on links + cost estimates
          └→ developer ×N: implement, strictly one at a time, in dependency order
              └→ tester: Playwright (UI/E2E work) or unit framework (logic work)
                  └→ assessed + confirmed reviewer subset (parallel or sequential,
                     per review-mode), from:
                      ├── reviewer-security
                      ├── reviewer-architecture
                      ├── reviewer-business-logic
                      └── reviewer-edge-case
                          ├→ [selected PASS] requirement complete
                          └→ [issues] Fix tasks → re-review (max 2 rounds, then ask)

[prototype mode]
User input
  └→ builder: decides its own approach, writes the code, runs it,
     records the shortcuts it took → requirement complete
      └→ (when it proves out) stack:promote → standard mode

Commands

Command names are fixed — they never change with naming mode.

Blocked/suspended-task triage lives inside stack:cast's routing menu; the dependency graph lives inside stack:status — by design, no extra commands.

Naming Modes

.stack/config.yml (naming: default | mtg) is the single source of truth. Labels are a display layer only — status values, field names, file formats, and commands are identical in both modes. Switch anytime with stack:theme.

The Board

BOARD.md has emoji-coded sections (emoji map to the status concept, so they're the same in both naming modes):

Task rules:

• Dependency rule: a task is only dispatched when every ID in its depends-on has status: done. Enforced every cycle, no exceptions.
• Quick tasks (quick: true): fast lane for small fixes — checked before normal backlog order, still dependency-gated.
• Cost (cost: 1-5): effort estimate per task; stack:status shows the backlog breakdown. Advisory only — never affects ordering.
• Blocked vs Suspended: blocked = something's wrong, needs review; suspended = nothing's wrong, you parked it. Neither ever auto-progresses.

The Graveyard

Two ways in:

1. Release (stack:release): done requirements + their tasks are archived to .stack/graveyard/{date}/ and summarized in GRAVEYARD.md.
2. Drop: dropping a blocked/suspended task appends to GRAVEYARD.md immediately, tagged dropped with the reason — no release wait.

Browse it all with stack:graveyard.

Session Continuity

• start turn reads only the latest SESSION-LOG.md entry (token discipline) and weaves it into the status report: "Last session you were mid-way through TASK-004…"
• end turn appends two records to SESSION-LOG.md — a technical summary (for the tool's memory) and a plain-language EoD report (for your standup) — and prints only the latter. The log file is never trimmed.

State Structure

.stack/
  config.yml               # naming + review-mode (single source of truth)
  BOARD.md                 # the board (orchestrator-only writes)
  SESSION-LOG.md           # full session history
  requirements/REQ-NNN.md
  tasks/TASK-NNN.md
  plans/PLAN-NNN.md        # one per requirement, per-task subsections
  docs/                    # evergreen research/notes — survives releases
  graveyard/
    {release-date}/        # archived REQs/tasks/plans per release
    GRAVEYARD.md           # running index of everything resolved or dropped

Agents

role: reviewer on a task is a trigger alias — dispatching it spawns all 4 specialists (concurrently with review-mode: parallel, one at a time with sequential); the task passes only on 4/4 PASS verdicts.

License

MIT — Justin Sacdalan