Run a manager's recurring writing work on any coding agent, with proof it was done right.
A weekly leadership update, a daily program status, a talent card, a work summary, a promotion document: each is the same job. Gather evidence from the systems that hold it, write in a fixed voice, check the draft against a checklist, put it where a human presses send, record what happened. vstack turns that job into a file (a workflow), runs it on the coding agent you already have (Claude Code, Codex, Kiro CLI or Kiro Crew), and refuses to call it done until the artifacts prove it.
Everything that names your company lives in a second, private repository called the instance. vstack reads it at run time and never contains it, and a check fails if the line is crossed.
| Word | Means |
|---|---|
| workflow | one recurring document as one JSON file: trigger, sources, writer, gate, sink, ledger. workflows/weekly-update.json is a workflow. Everything vstack does, it does to a workflow |
| instance | the private folder (and repository) that holds your company's facts: which tools, which documents, which channels, which people. vstack reads it, never contains it |
| connector | a capability name a workflow asks for ( chat.search ,docs.read ). The instance'sconnectors.json binds each connector to a real MCP server and tool, so workflows never name tools |
| harness | the coding agent that runs the prompt: Claude Code, Codex, Kiro CLI or Kiro Crew |
| run | one execution of one workflow: a directory of artifacts under ~/.local/state/vstack/runs/ and one ledger line |
Three more words appear once you are inside: a glossary is your company's vocabulary the writers substitute, context is the standing inputs a workflow reads every time (template contracts, rules, rubrics), and a brief is the three lines you read instead of the draft.
example/ is a complete instance for a made-up company. Copy it to start yours; the checks also
use it as the proof that the invariants hold on a real layout.
Everything in vstack is one of three kinds of thing, and the sections below follow that order: Define (what should happen every time, in the instance), Run (what happened this time, on disk), Check (what refuses a bad definition or a bad run, in the engine).
| Piece | What it does | Where |
|---|---|---|
| engine | one Python file, no dependencies. Renders a workflow into a prompt, runs it on a harness, verifies the run directory, keeps a ledger, prints schedules and agent templates | bin/vstack |
| skills | the writers (executive update, talent card, work summary, promotion doc), the critic ( validate-writing ), the rewriters, and two plumbing skills. Plain markdown in the openAgent Skills format |
skills/ |
| harness adapters | how each of the four agents is invoked non-interactively and where it reads skills from | harness/README.md ,harness_cmd in the engine |
| example instance | a complete instance for a made-up company: connectors, glossary, one workflow with its sample evidence. Copy it to start yours | example/ |
| evals and checks | a nine-group check script, a routing eval for the skills, sample evidence with expected outcomes | scripts/ ,evals/ |
your private instance vstack (this repository) your harness
───────────────────── ──────────────────────── ────────────
workflows/weekly-update.json ─┐
connectors.json ├─▶ vstack run <workflow> --harness claude ─▶ one prompt, absolute paths
glossary.md │ │ │
context/, *.sample.json ─┘ │ pre-flight: invariants, ▼
│ skill copies match the lock claude -p / codex exec /
│ kiro-cli chat / kirocrew cron
▼ │
~/.local/state/vstack/runs/<workflow>/<harness>-<id>/│
evidence.json diff.md draft.md gate.md brief.md result.json
│ │
│ contract check: are the files there and well-formed?
▼
ledger/runs.jsonl (one line per run, append-only)
│
▼
a DRAFT in a compose box or a [Draft] document. A human presses send.
The prompt the harness runs has eight stages. Every workflow is this loop:
| Stage | What happens | Leaves behind |
|---|---|---|
| 1 gather | call the tools the workflow's connectors bind to, cache-first. Read-only | evidence.json with asources list and a content hash |
| 2 diff | compare with the previous run's evidence | diff.md |
| 3 write | the writer skill turns evidence into a draft in the house voice. The first line says which sources were used and which were unavailable | draft.md |
| 4 gate | validate-writing scores the draft, the writer fixes every quoted failure, at least 2 and at most 5 passes |
gate.md , first linepasses: N |
| 5 land | the draft goes to the sink: a compose box, a [Draft] document. Never sent |
the landed path or id |
| 5b brief | three lines a busy reader decides from without opening the draft | brief.md |
| 6 record | one ledger line, one result file | result.json , a line inruns.jsonl |
| contract | the engine reads the run directory back. Anything missing or malformed marks the run contract_unmet , whatever the model claimed |
meta.json |
Two optional extras: --second-opinion <harness> runs an independent critic on another agent and
records its quoted findings (never edits, never blocks), and vstack retro reads the ledger back
weekly and lists what keeps going wrong.
You need Python 3.9 or newer, git, and at least one of: Claude Code, Codex CLI, Kiro CLI, Kiro Crew.
1. Clone and make every harness read the same skills.
git clone https://github.com/ivikash/vstack ~/github/vstack
V=~/github/vstack/bin/vstack
$V link-skills --canonical ~/github/vstack/skills \
--targets ~/.claude/skills ~/.codex/skills ~/.agents/skills ~/.kiro/skills ~/.kiro/crew/skills \
--skills leadership-writing write-exec-update write-talent-card write-work-summary write-promo-doc \
validate-writing rewrite rewrite-and-validate score-gate gather-evidence
Each harness directory now holds symlinks into this checkout. A git pull here updates all of
them; an existing real copy is moved aside, not deleted (~/.local/state/vstack/skill-backups).
Pass only the target directories for the harnesses you have.
2. Create your instance from the example. A private repository, committed with your work e-mail, hosted only on your company's git server.
cp -r ~/github/vstack/example ~/work/my-instance
cd ~/work/my-instance && git init && git config user.email you@your-company.example
export VSTACK_INSTANCE=~/work/my-instance # or pass --instance DIR on every command
Then edit, in this order:
| File | Change |
|---|---|
connectors.json |
bind each connector (docs.read ,chat.search ,chat.draft , ...) to the MCP server and tool your harness has. This is the only file that names real tools |
mcp-servers.json |
the servers those tools come from. vstack gen-mcp --servers mcp-servers.json --target claude prints the block for each harness's config |
glossary.md |
your company's words: what principles are called, the rating scale, level names. Only the keys you change |
workflows/program-update.json |
rename, set the config values (document id, channel, project), keep the connectors |
workflows/program-update.sample.json |
made-up evidence for dry runs. Real section names, invented values |
3. Prove the definition is sound. No model call, under a second.
$V check # invariants over workflows/
$V map # the estate derived from them: sources, writers, gates, sinks, ledgers, bots
cd ~/github/vstack && scripts/check.sh # the public repo's own checks, including that your instance is private
4. Dry run. Sample evidence in, files out, nothing published, on whichever harness you have.
$V run ~/work/my-instance/workflows/program-update.json --harness claude --dry-run
The command prints meta.json when the harness returns. Look for "status": "ok" or
"known_gaps" and "contract": {"met": true}. The run directory it names holds every artifact.
A workflow is one JSON file. This is the example instance's workflow with a comment on each field:
{
"id": "program-update", // lowercase-hyphen; names the run dir and ledger
"kind": "writer", // writer | consumer | collector
"component": "program", // partition; "hr" is the private one by default
"trigger": {"cron": "29 8 * * 1-5", "timezone": "UTC", "events": []},
"bot": "ProgramStatus", // the Kiro Crew bot that hosts it (bound on the Schedule page)
"sources": [ // connectors, never tool names; bound through connectors.json
{"connector": "docs.read", "ref": "${config.statusDocId}", "notes": "latest dated entries"},
{"connector": "tasks.list", "ref": "${config.taskProject}", "notes": "owner, due, status, last comment"},
{"connector": "mail.search", "ref": "${config.meetingSummaryQuery}", "notes": "last ${config.lookbackDays} days"},
{"connector": "chat.search", "ref": "${config.discussChannel}", "notes": "status and blockers"}
],
"coverage": {"min_sources": 3}, // check fails a writer that reads fewer sources
"cache": {"key": "program/${config.program}", "ttl_hours": 20},
"writer": {"skill": "write-exec-update"},
"gate": {"skill": "validate-writing", "doc_type": "exec-update",
"min_passes": 2, "max_passes": 5, "coverage_bar": 85,
"second_opinion": "codex"}, // optional independent critic
"sink": {"connector": "chat.draft", "ref": "${config.postChannel}", "dry_run_path": "update.md"},
"ledger": {"file": "program-update.jsonl",
"fields": ["program", "overall_status", "red_sections", "green_by_dates", "open_action_items", "posted_to"]},
// sample evidence: program-update.sample.json beside this file, by default
"config": {"program": "Project Lantern", "statusDocId": "doc-0000", "taskProject": "project-0000",
"meetingSummaryQuery": "\"Meeting summary\" Lantern", "discussChannel": "#lantern",
"postChannel": "#lantern-leadership", "lookbackDays": 14}
}
Rules of thumb:
- Connectors, not tools.
chat.searchin the workflow,slack-mcp / searchinconnectors.json. Change the tool once, every workflow follows. ${config.x}is substituted anywhere in the workflow, so ids and channels live in one block.- Three sources or more. One source is a copy. Add a corroboration connector when your chat tool
has an assistant you can ask, and put it in
coverage.require_connectorsso the check insists on it. - The sink is always a draft.
chat.draft,docs.writeto a[Draft],mail.draft. A connector that sends is a bug. - A private workflow (
component: "hr") must name aworkspace, and its ledger fields may not carry ratings, candidates or feedback text.vstack checkrefuses otherwise.
Full field reference: schema/workflow.schema.json. Validate with $V check.
$V run <workflow> --harness claude
$V run <workflow> --harness claude --no-publish
$V run <workflow> --harness claude --second-opinion codex
$V render <workflow> --harness kiro
$V gen-cron --harness claude # crontab lines (workflows from $VSTACK_INSTANCE)
$V gen-cron --harness kirocrew # kirocrew cron add commands, with the bot to bind each to
$V gen-agent --harness kiro > ~/.kiro/agents/vstack-runner.json
$V retro --days 7
On a schedule, the cron line calls vstack run directly. For Kiro Crew, the job's message tells
the agent to render the workflow with its shell and follow the printed prompt, so every wake gets a
fresh run directory and the agent's own MCP tools do the gathering.
~/.local/state/vstack/runs/program-update/claude-20261115-094200-c0b4fc/
prompt.md the exact prompt the harness received
command.txt the exact command
evidence.json {"gathered_at", "sources": [{"connector","status","items"}], "items": [...], "evidence_hash"}
diff.md what changed since the previous run
draft.md line 1 title, line 2 "Sources: used ...; unavailable ...", then the document
gate.md "passes: 2" then the last pass report, every rule with what it checked
brief.md three lines: what landed, the one fact to look at with its source, where and what to do
update.md the landed copy (dry run and no-publish) or the landed id/URL
result.json {"status": "ok" | "known_gaps" | "failed", "gate_passes": 2, "draft", "brief", "landed"}
gate-second.md (with --second-opinion) "findings: N" then each finding with the offending text quoted
meta.json run id, harness, timings, result, contract {met, unmet[]}, second_opinion
stdout.log what the harness printed
~/.local/state/vstack/ledger/runs.jsonl one line per run, append-only
~/.local/state/vstack/cache/<key>/last-evidence.json
~/.local/state/vstack/retro/<date>.md written by vstack retro
A brief from a real dry run, so you know the register:
PRISM daily exec update (dry run, 11/07 sample data): RED.
Ingestion is RED with no recovery date because the sources give two Hub cut-over targets, 11/05 and 11/19, and the owner owes one date by 11/10 (fixture, test data).
Draft at .../prism-update.md. Reader action: nothing (dry run, not posted).
All under skills/, one directory each, linked into every harness. The writers never fetch and
never publish: they turn evidence into a document and nothing else.
| Skill | Use when | Reads |
|---|---|---|
write-exec-update |
a status update for executives: overall line, one block per workstream (RED/YELLOW/GREEN, Green-by when RED), milestones, risks, action items, Known Gaps | format.md |
write-talent-card |
a per-person talent-review card: rating rationale and key deliverables sections | template.md |
write-work-summary |
a structured work summary: timeline, task, challenges, action, result, artifacts | template.md |
write-promo-doc |
a narrative promotion document against a level rubric, with a real Reasons Not To Promote section | template.md ,rubric-TEMPLATE.md |
validate-writing |
the gate. gate mode returns pass or fail with every failure quoted and a fix;evaluate mode returns a scored report. Never rewrites |
checklist.md |
rewrite |
tighten supplied prose to the house rules, every fact and link preserved, nothing added | |
rewrite-and-validate |
the same, then loop through the gate until it passes, at least two passes | |
score-gate |
run any draft through the gate in a fixed loop and return the final draft plus a one-line result | |
gather-evidence |
the gather stage: cache-first, by connector, one evidence.json , never prose |
|
leadership-writing |
not invoked. Holds house-rules.md (the voice: 17 rules, 4 of them mechanical blockers),glossary.md (neutral defaults) andrationalizations.md (12 excuses with their rebuttals, 7 red flags). Every writer and the critic read all three first |
The voice in one paragraph: lead with the point and the fact behind it, active voice, no
superlatives, no hedging, no em-dashes or semicolons, every claim tied to an artifact in the
evidence, every missing fact labelled (unverified) or listed under Known Gaps, never invented.
A rule nothing enforces is a wish. docs/RULES.md pairs every rule with its check. The checks, in the order they run:
scripts/check.sh group |
Fails when |
|---|---|
| identity | a commit here is not by the personal e-mail, or git config user.email is wrong |
| no-org | any public file carries a company term, internal host, ticket, chat, doc or account id |
| schemas | a JSON file does not parse, or the example instance breaks an invariant |
| frontmatter | a skill's name is not its directory name in lowercase-hyphen, or a description is empty or over 1024 characters |
| loop | a writer skill lacks the gate loop (min 2, max 5, reads house-rules) |
| glossary | a skill references a glossary key that is not defined |
| triggers | a skill's description does not win its own prompts in evals/triggers.json (36 cases, no model) |
| rules | docs/RULES.md names a check or subcommand that does not exist |
| instance | with VSTACK_INSTANCE set: the instance is inside this checkout, is a remote of it, or has a public remote |
And vstack check over an instance:
- Writers and gates never fetch: a writer receives
evidence.jsonand nothing else. - Every writer has exactly one gate before its sink,
min_passesat least 2. - Every sink records: a workflow with no ledger fields fails.
- The privacy cut: a private workflow names a private workspace, and its ledger fields may not carry rating, candidate, promo, salary or feedback text.
- Every workflow has a
dry_run_path, so it can run with no side effects. - A writer reads at least two sources, more when
coveragesays so. - Every source is a connector name, never a tool name.
And after every run, the contract: evidence.json with sources and hash, diff.md, draft.md
with its Sources: line, gate.md with enough passes, a three-line brief.md, result.json.
| Command | Does |
|---|---|
vstack render <workflow> [--harness h] |
print the prompt, run nothing |
vstack run <workflow> --harness h [--dry-run] [--no-publish] [--second-opinion h2] [--agent a] [--model m] |
pre-flight, render, execute, contract check, ledger line |
vstack check [--instance d] |
invariants over the workflows |
vstack map [--instance d] [--json] |
the estate derived from the workflows: sources, writers, gates, sinks, ledgers, bots |
vstack check-run <run-dir> |
contract check on an existing run directory |
vstack verify-skills --dirs ... --skills ... |
every named skill present and identical in every harness dir |
vstack link-skills --canonical d --targets ... --skills ... |
symlink the canonical skills into each harness dir |
vstack gen-cron --harness h [--instance d] |
crontab lines, or kirocrew cron add commands with the bot to bind to |
vstack gen-agent --harness kiro [--instance d] |
a Kiro CLI agent template whose tool surface is exactly connectors.json |
vstack gen-mcp --servers f --target h |
the MCP server block for one harness |
vstack retro [--days n] |
per-workflow runs, contract misses, gate passes, recurring Known Gaps |
Every command accepts --instance DIR or reads $VSTACK_INSTANCE and fills --connectors,
--glossary and --workflows from it. State lives under ~/.local/state/vstack.
bin/vstack the CLI, one file, standard library only
schema/ workflow, connectors, ledger (JSON Schema)
skills/ one canonical copy of every skill
harness/README.md the four harnesses: exact command, skills dir, what a run leaves behind
example/ a complete instance for a made-up company: README, connectors.json, glossary.md, mcp-servers.json, workflows/ with sample evidence, vstack.lock
evals/ triggers.json, fixtures/ (synthetic evidence packs the skill evals read), results/
scripts/check.sh the nine check groups
scripts/trigger-eval.py the routing eval
docs/ARCHITECTURE.md why two repos, the layers, the run, the derived map, the scales
docs/RULES.md every rule and its enforcer
| Symptom | Cause and fix |
|---|---|
pre-flight failed (skills) |
a harness dir has a stale copy or is missing a skill. vstack link-skills ... again, thenvstack verify-skills |
pre-flight failed (invariants) |
the workflow breaks a rule. vstack check prints each one |
"status": "contract_unmet" with"claimed_status": "ok" |
the model said done but a file is missing or malformed. meta.json lists which;vstack check-run <dir> repeats it |
warning: instance pins vstack X, this checkout is Y |
you updated vstack. Dry run every workflow once, then write the new short SHA into the instance's vstack.lock |
draft says Sources: ... unavailable chat.search |
the connector is unbound in connectors.json , or the tool returned nothing. Fix the binding or theref , never the draft |
| Kiro CLI denies a tool | kiro-cli 3.x denies any tool not named in --trust-tools ; run under thevstack-runner template fromvstack gen-agent , or let the adapter pass--trust-all-tools |
a kirocrew run shows"status": "scheduled" |
correct: the job runs asynchronously. Its run dir fills in when it finishes; vstack check-run on it then |
check.sh no-org fails on your own text |
the word is on the denylist for a reason. Rephrase in the public repo; the term belongs in the instance |
Why two repositories, what each layer owns, the derived map, the privacy cut and the same workflow at four scales: docs/ARCHITECTURE.md. Recorded test runs: evals/results/.
MIT.