0x00vb/vstack

flowchart LR
    A(["Agent"]):::agent
    V{{"vstack CLI"}}:::cli
    G{"All gates<br/>pass?"}:::gate
    N["Save the evidence<br/>Print the next step"]:::step
    F["Print the error output<br/>Keep the same step"]:::fail

    A -- "vstack done + evidence" --> V
    V -- "types · lint · test · slop" --> G
    G -- yes --> N
    G -- no --> F
    N -- "next step" --> A
    F -- "fix and try again" --> A

    classDef agent fill:#fef3c7,stroke:#d97706,color:#78350f
    classDef cli fill:#4f46e5,stroke:#3730a3,color:#ffffff
    classDef step fill:#eef2ff,stroke:#4f46e5,color:#1e1b4b
    classDef gate fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef fail fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
    classDef store fill:#f1f5f9,stroke:#64748b,color:#0f172a

$ vstack done "it should work now"
"verify" needs observed evidence, not predictions. Run it and say what you saw. Quote output or test names in backticks.

$ vstack done "ran \`curl -s localhost:3000/api/attendees.csv\` and saw 3 rows"
- types: not configured (vstack.json "checks")
- lint: not configured (vstack.json "checks")
✓ test (0.1s)
✗ slop: 2 fail, 1 warn, 5 added lines since cce02acf
  ✗ src/csv.ts:1 type-escape: type escape hatch. Model the type
      export function toCsv(rows: any[]) {
  ⚠ src/csv.ts:2 narrating-comment: comment narrates the code. Keep only a non-obvious why
      // Loop over the rows
  ✗ src/csv.ts:3 swallowed-error: error swallowed. Handle it or let it propagate
      try { return rows.map(r => r.name).join("\n") } catch (e) {}
gate failed, still on "verify". Fix and run vstack done again, or vstack back <step> "<why>".

stateDiagram-v2
    direction LR
    [*] --> frame
    frame --> understand: M, L
    frame --> build: S
    understand --> design
    design --> build
    build --> verify
    verify --> review: M, L
    verify --> ship: S
    review --> ship
    ship --> [*]
    build --> design: back
    review --> verify: back, code changed

    classDef must fill:#4f46e5,stroke:#3730a3,color:#ffffff
    classDef opt fill:#eef2ff,stroke:#4f46e5,color:#1e1b4b
    class frame, verify must
    class understand, design, build, review, ship opt

flowchart LR
    subgraph spike["spike · build a test version to decide"]
        direction LR
        s1["question"]:::must --> s2["sketch"]:::opt --> s3["observe"]:::must --> s4["decide"]:::must
    end
    subgraph investigate["investigate · a question, no code changes"]
        direction LR
        i1["question"]:::must --> i2["evidence"]:::opt --> i3["answer"]:::must
    end
    subgraph refactor["refactor · same behavior, new structure"]
        direction LR
        r1["baseline"]:::must --> r2["subtract"]:::opt --> r3["change"]:::opt --> r4["verify"]:::must --> r5["review"]:::opt --> r6["ship"]:::opt
    end
    subgraph bugfix["bugfix · a reported defect"]
        direction LR
        b1["reproduce"]:::must --> b2["root-cause"]:::must --> b3["regression-test"]:::opt --> b4["fix"]:::opt --> b5["verify"]:::must --> b6["review"]:::opt --> b7["ship"]:::opt
    end

    style bugfix fill:none,stroke:#94a3b8
    style refactor fill:none,stroke:#94a3b8
    style investigate fill:none,stroke:#94a3b8
    style spike fill:none,stroke:#94a3b8

    classDef must fill:#4f46e5,stroke:#3730a3,color:#ffffff
    classDef opt fill:#eef2ff,stroke:#4f46e5,color:#1e1b4b

sequenceDiagram
    autonumber
    actor A as Agent
    participant V as vstack
    participant P as Project checks

    A->>V: vstack done "evidence"
    Note over V: Examine the evidence
    alt Evidence is too short, or it predicts instead of observes
        V-->>A: Refuse. The step does not change.
    else The code changed after verify
        V-->>A: Refuse. Run vstack back verify.
    else The evidence is valid
        V->>P: Run types, lint, test
        P-->>V: Exit codes and output
        Note over V: Scan the diff for slop
        alt A gate fails
            V-->>A: Last 40 lines of output. The step does not change.
        else All gates pass
            Note over V: Save the evidence and a fingerprint of the diff
            V-->>A: The next step only
        end
    end

const legacy = payload as any; // vstack-ok: the vendor types are wrong, issue #412

flowchart LR
    GH[("github.com/0x00vb/vstack")]:::store
    CC["Claude Code<br/>skills · CLI on PATH · rules"]:::step
    CX["Codex<br/>skills · CLI in the skill folder"]:::step
    AN["Cursor and other agents<br/>skills · CLI in the skill folder"]:::step
    GL["All agents on this computer<br/>skills · CLI on PATH · rules"]:::step
    TM["One repository, for the team<br/>committed with the code"]:::step

    GH -- "claude plugin install" --> CC
    GH -- "codex plugin add" --> CX
    GH -- "npx skills add" --> AN
    GH -- "git clone + install.mjs" --> GL
    GH -- "install.mjs --project" --> TM

    classDef step fill:#eef2ff,stroke:#4f46e5,color:#1e1b4b
    classDef store fill:#f1f5f9,stroke:#64748b,color:#0f172a

flowchart TB
    subgraph repo["One repository"]
        direction LR
        W1["../app-csv<br/>branch csv"]:::store --> A1(["Agent 1<br/>feature · build"]):::agent
        W2["../app-login<br/>branch login"]:::store --> A2(["Agent 2<br/>bugfix · verify"]):::agent
        W3["../app-cache<br/>branch cache"]:::store --> A3(["Agent 3<br/>refactor · review"]):::agent
    end
    T[(".git/vstack/tasks<br/>one file for each task")]:::store
    B{{"vstack board"}}:::cli

    A1 -- "writes its file" --> T
    A2 -- "writes its file" --> T
    A3 -- "writes its file" --> T
    B -- "reads all files" --> T

    style repo fill:none,stroke:#94a3b8
    classDef agent fill:#fef3c7,stroke:#d97706,color:#78350f
    classDef cli fill:#4f46e5,stroke:#3730a3,color:#ffffff
    classDef store fill:#f1f5f9,stroke:#64748b,color:#0f172a

$ git worktree add ../app-csv -b csv
$ vstack board
task                          flow      size  step        updated  branch  worktree
fix-login-redirect            bugfix    S     4/5 verify  0m       login   ../app-login
add-csv-export-attendee-list  feature   M     4/7 build   0m       csv     ../app-csv
split-cache-module            refactor  M     5/6 review  2h!      cache   ../app-cache

sequenceDiagram
    actor L as Lead agent
    participant V as vstack
    participant R1 as Reviewer 1 (subagent)
    participant R2 as Reviewer 2 (other model)

    L->>V: vstack brief --review
    V-->>L: Goal, criteria, review rules, diff
    par
        L->>R1: Review prompt
    and
        L->>R2: Review prompt through a pipe
    end
    R1-->>L: Findings
    R2-->>L: Findings
    Note over L: Sort: act on, consider, noted, dismissed
    L->>V: vstack done "triage"

vstack brief --review | codex exec -
vstack brief --review | claude -p
vstack brief --review | cursor-agent -p

{
	"base": "main",
	"checks": {
		"test": "pnpm --filter web test",
		"types": "pnpm --filter web exec tsc --noEmit",
		"lint": null
	},
	"slop": {
		"off": ["todo"],
		"ignore": ["**/generated/**"],
		"budget": { "S": 200, "M": 800 }
	}
}

{
	"about": "Change a database schema.",
	"states": [
		{ "id": "plan", "must": true, "do": "Write the migration and its rollback.", "exit": "both SQL files" },
		{ "id": "verify", "must": true, "observed": true, "run": ["test", "migrate"], "do": "Run the migration on a copy of the data.", "exit": "row counts before and after" }
	]
}

- **Smallest diff** `build` - The least code that meets the criteria. No speculative options, layers, or config.

skills/
  vstack/            Main skill: SKILL.md, the CLI, flows, principles
  vstack-review/     Review with no shared context, and the triage rules
  vstack-parallel/   Rules for many agents at the same time
bin/vstack           Wrapper that the Claude Code plugin puts on the PATH
rules/kernel.md      The short rules that load in each session
hooks/hooks.json     Loads the rules when a Claude Code session starts
install.mjs          Installer for all agents or one repository
.claude-plugin/      Claude Code plugin and marketplace
.agents/plugins/     Codex marketplace
plugin.json          Agent Plugins manifest
test/                Tests for the CLI

npm test