{"slug": "vstack-ai-for-management-and-leadership", "title": "Vstack – AI for Management and Leadership", "summary": "Vstack released an open-source tool that turns recurring management writing tasks — weekly leadership updates, daily program status reports, talent cards, work summaries and promotion documents — into JSON \"workflow\" files run on existing coding agents including Claude Code, Codex, Kiro CLI and Kiro Crew. The engine is a single dependency-free Python file at bin/vstack that renders a workflow into a prompt, executes it on the chosen harness, verifies the run directory, keeps a ledger and prints schedules and agent templates, and it refuses to mark a job done until the artifacts prove it. Company-specific facts live in a separate private \"instance\" repository that vstack reads at run time but never contains, with a check that fails if that boundary is crossed.", "body_md": "**Run a manager's recurring writing work on any coding agent, with proof it was done right.**\n\nA weekly leadership update, a daily program status, a talent card, a work summary, a promotion\ndocument: each is the same job. Gather evidence from the systems that hold it, write in a fixed\nvoice, check the draft against a checklist, put it where a human presses send, record what\nhappened. vstack turns that job into a file (a **workflow**), runs it on the coding agent you already\nhave (Claude Code, Codex, Kiro CLI or Kiro Crew), and refuses to call it done until the artifacts\nprove it.\n\nEverything that names your company lives in a second, private repository called the **instance**.\nvstack reads it at run time and never contains it, and a check fails if the line is crossed.\n\n| Word | Means | \n|---|---|\n| **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 | \n| **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 | \n| **connector** | a capability name a workflow asks for ( `chat.search` ,`docs.read` ). The instance's`connectors.json` binds each connector to a real MCP server and tool, so workflows never name tools | \n| **harness** | the coding agent that runs the prompt: Claude Code, Codex, Kiro CLI or Kiro Crew | \n| **run** | one execution of one workflow: a directory of artifacts under `~/.local/state/vstack/runs/` and one ledger line | \n\nThree more words appear once you are inside: a **glossary** is your company's vocabulary the writers\nsubstitute, **context** is the standing inputs a workflow reads every time (template contracts,\nrules, rubrics), and a **brief** is the three lines you read instead of the draft.\n\n`example/` is a complete instance for a made-up company. Copy it to start yours; the checks also\nuse it as the proof that the invariants hold on a real layout.\n\nEverything in vstack is one of three kinds of thing, and the sections below follow that order:\n**Define** (what should happen every time, in the instance), **Run** (what happened this time, on\ndisk), **Check** (what refuses a bad definition or a bad run, in the engine).\n\n| Piece | What it does | Where | \n|---|---|---|\n| **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` | \n| **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 open[Agent Skills](https://agentskills.io/specification) format | `skills/` | \n| **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 | \n| **example instance** | a complete instance for a made-up company: connectors, glossary, one workflow with its sample evidence. Copy it to start yours | `example/` | \n| **evals and checks** | a nine-group check script, a routing eval for the skills, sample evidence with expected outcomes | `scripts/` ,`evals/` | \n\n```\n   your private instance                 vstack (this repository)               your harness\n   ─────────────────────                 ────────────────────────               ────────────\n   workflows/weekly-update.json ─┐\n   connectors.json               ├─▶ vstack run <workflow> --harness claude ─▶ one prompt, absolute paths\n   glossary.md                   │       │                                      │\n   context/, *.sample.json      ─┘       │ pre-flight: invariants,               ▼\n                                     │ skill copies match the lock    claude -p / codex exec /\n                                     │                                kiro-cli chat / kirocrew cron\n                                     ▼                                   │\n                        ~/.local/state/vstack/runs/<workflow>/<harness>-<id>/│\n                           evidence.json  diff.md  draft.md  gate.md  brief.md  result.json\n                                     │                                   │\n                                     │ contract check: are the files there and well-formed?\n                                     ▼\n                        ledger/runs.jsonl  (one line per run, append-only)\n                                     │\n                                     ▼\n                        a DRAFT in a compose box or a [Draft] document. A human presses send.\n```\n\nThe prompt the harness runs has eight stages. Every workflow is this loop:\n\n| Stage | What happens | Leaves behind | \n|---|---|---|\n| 1 gather | call the tools the workflow's **connectors** bind to, cache-first. Read-only | `evidence.json` with a`sources` list and a content hash | \n| 2 diff | compare with the previous run's evidence | `diff.md` | \n| 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` | \n| 4 gate | `validate-writing` scores the draft, the writer fixes every quoted failure, at least 2 and at most 5 passes | `gate.md` , first line`passes: N` | \n| 5 land | the draft goes to the sink: a compose box, a `[Draft]` document. Never sent | the landed path or id | \n| 5b brief | three lines a busy reader decides from without opening the draft | `brief.md` | \n| 6 record | one ledger line, one result file | `result.json` , a line in`runs.jsonl` | \n| contract | the engine reads the run directory back. Anything missing or malformed marks the run `contract_unmet` , whatever the model claimed | `meta.json` | \n\nTwo optional extras: `--second-opinion <harness>` runs an independent critic on another agent and\nrecords its quoted findings (never edits, never blocks), and `vstack retro` reads the ledger back\nweekly and lists what keeps going wrong.\n\nYou need Python 3.9 or newer, git, and at least one of: Claude Code, Codex CLI, Kiro CLI, Kiro Crew.\n\n**1. Clone and make every harness read the same skills.**\n\n```\ngit clone https://github.com/ivikash/vstack ~/github/vstack\nV=~/github/vstack/bin/vstack\n\n$V link-skills --canonical ~/github/vstack/skills \\\n   --targets ~/.claude/skills ~/.codex/skills ~/.agents/skills ~/.kiro/skills ~/.kiro/crew/skills \\\n   --skills leadership-writing write-exec-update write-talent-card write-work-summary write-promo-doc \\\n            validate-writing rewrite rewrite-and-validate score-gate gather-evidence\n```\n\nEach harness directory now holds symlinks into this checkout. A `git pull` here updates all of\nthem; an existing real copy is moved aside, not deleted (`~/.local/state/vstack/skill-backups`).\nPass only the target directories for the harnesses you have.\n\n**2. Create your instance from the example.** A private repository, committed with your work\ne-mail, hosted only on your company's git server.\n\n```\ncp -r ~/github/vstack/example ~/work/my-instance\ncd ~/work/my-instance && git init && git config user.email you@your-company.example\nexport VSTACK_INSTANCE=~/work/my-instance        # or pass --instance DIR on every command\n```\n\nThen edit, in this order:\n\n| File | Change | \n|---|---|\n| `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 | \n| `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 | \n| `glossary.md` | your company's words: what principles are called, the rating scale, level names. Only the keys you change | \n| `workflows/program-update.json` | rename, set the `config` values (document id, channel, project), keep the connectors | \n| `workflows/program-update.sample.json` | made-up evidence for dry runs. Real section names, invented values | \n\n**3. Prove the definition is sound.** No model call, under a second.\n\n```\n$V check                      # invariants over workflows/\n$V map                        # the estate derived from them: sources, writers, gates, sinks, ledgers, bots\ncd ~/github/vstack && scripts/check.sh    # the public repo's own checks, including that your instance is private\n```\n\n**4. Dry run.** Sample evidence in, files out, nothing published, on whichever harness you have.\n\n```\n$V run ~/work/my-instance/workflows/program-update.json --harness claude --dry-run\n#                                                    --harness codex | kiro | kirocrew\n```\n\nThe command prints `meta.json` when the harness returns. Look for `\"status\": \"ok\"` or\n`\"known_gaps\"` and `\"contract\": {\"met\": true}`. The run directory it names holds every artifact.\n\nA workflow is one JSON file. This is the example instance's workflow with a comment on each field:\n\n```\n{\n  \"id\": \"program-update\",                 // lowercase-hyphen; names the run dir and ledger\n  \"kind\": \"writer\",                       // writer | consumer | collector\n  \"component\": \"program\",                 // partition; \"hr\" is the private one by default\n  \"trigger\": {\"cron\": \"29 8 * * 1-5\", \"timezone\": \"UTC\", \"events\": []},\n  \"bot\": \"ProgramStatus\",                 // the Kiro Crew bot that hosts it (bound on the Schedule page)\n  \"sources\": [                            // connectors, never tool names; bound through connectors.json\n    {\"connector\": \"docs.read\",   \"ref\": \"${config.statusDocId}\", \"notes\": \"latest dated entries\"},\n    {\"connector\": \"tasks.list\",  \"ref\": \"${config.taskProject}\", \"notes\": \"owner, due, status, last comment\"},\n    {\"connector\": \"mail.search\", \"ref\": \"${config.meetingSummaryQuery}\", \"notes\": \"last ${config.lookbackDays} days\"},\n    {\"connector\": \"chat.search\", \"ref\": \"${config.discussChannel}\", \"notes\": \"status and blockers\"}\n  ],\n  \"coverage\": {\"min_sources\": 3},         // check fails a writer that reads fewer sources\n  \"cache\": {\"key\": \"program/${config.program}\", \"ttl_hours\": 20},\n  \"writer\": {\"skill\": \"write-exec-update\"},\n  \"gate\": {\"skill\": \"validate-writing\", \"doc_type\": \"exec-update\",\n           \"min_passes\": 2, \"max_passes\": 5, \"coverage_bar\": 85,\n           \"second_opinion\": \"codex\"},    // optional independent critic\n  \"sink\": {\"connector\": \"chat.draft\", \"ref\": \"${config.postChannel}\", \"dry_run_path\": \"update.md\"},\n  \"ledger\": {\"file\": \"program-update.jsonl\",\n             \"fields\": [\"program\", \"overall_status\", \"red_sections\", \"green_by_dates\", \"open_action_items\", \"posted_to\"]},\n                                          // sample evidence: program-update.sample.json beside this file, by default\n  \"config\": {\"program\": \"Project Lantern\", \"statusDocId\": \"doc-0000\", \"taskProject\": \"project-0000\",\n             \"meetingSummaryQuery\": \"\\\"Meeting summary\\\" Lantern\", \"discussChannel\": \"#lantern\",\n             \"postChannel\": \"#lantern-leadership\", \"lookbackDays\": 14}\n}\n```\n\nRules of thumb:\n\n- **Connectors, not tools.**`chat.search` in the workflow,`slack-mcp / search` in`connectors.json` .\nChange the tool once, every workflow follows.\n- **`${config.x}`** is substituted anywhere in the workflow, so ids and channels live in one block.\n- **Three sources or more.** One source is a copy. Add a corroboration connector when your chat tool\nhas an assistant you can ask, and put it in`coverage.require_connectors` so the check insists on it.\n- **The sink is always a draft.**`chat.draft` ,`docs.write` to a`[Draft]` ,`mail.draft` . A connector\nthat sends is a bug.\n- **A private workflow** (`component: \"hr\"` ) must name a`workspace` , and its ledger fields may not\ncarry ratings, candidates or feedback text.`vstack check` refuses otherwise.\n\nFull field reference: `schema/workflow.schema.json`. Validate with `$V check`.\n\n```\n# by hand, live: gathers from real sources, lands a draft, you press send\n$V run <workflow> --harness claude\n\n# live gather and gate, but the draft stays a file (for a first look at real evidence)\n$V run <workflow> --harness claude --no-publish\n\n# with an independent critic on another agent; findings land in meta.json\n$V run <workflow> --harness claude --second-opinion codex\n\n# see the prompt a harness would get, without running anything\n$V render <workflow> --harness kiro\n\n# standing schedule: one line per workflow with a trigger\n$V gen-cron --harness claude     # crontab lines (workflows from $VSTACK_INSTANCE)\n$V gen-cron --harness kirocrew   # kirocrew cron add commands, with the bot to bind each to\n\n# a Kiro CLI agent template whose tool surface is exactly connectors.json\n$V gen-agent --harness kiro > ~/.kiro/agents/vstack-runner.json\n\n# weekly: what happened, what keeps going wrong\n$V retro --days 7\n```\n\nOn a schedule, the cron line calls `vstack run` directly. For Kiro Crew, the job's message tells\nthe agent to render the workflow with its shell and follow the printed prompt, so every wake gets a\nfresh run directory and the agent's own MCP tools do the gathering.\n\n```\n~/.local/state/vstack/runs/program-update/claude-20261115-094200-c0b4fc/\n  prompt.md         the exact prompt the harness received\n  command.txt       the exact command\n  evidence.json     {\"gathered_at\", \"sources\": [{\"connector\",\"status\",\"items\"}], \"items\": [...], \"evidence_hash\"}\n  diff.md           what changed since the previous run\n  draft.md          line 1 title, line 2 \"Sources: used ...; unavailable ...\", then the document\n  gate.md           \"passes: 2\" then the last pass report, every rule with what it checked\n  brief.md          three lines: what landed, the one fact to look at with its source, where and what to do\n  update.md         the landed copy (dry run and no-publish) or the landed id/URL\n  result.json       {\"status\": \"ok\" | \"known_gaps\" | \"failed\", \"gate_passes\": 2, \"draft\", \"brief\", \"landed\"}\n  gate-second.md    (with --second-opinion) \"findings: N\" then each finding with the offending text quoted\n  meta.json         run id, harness, timings, result, contract {met, unmet[]}, second_opinion\n  stdout.log        what the harness printed\n~/.local/state/vstack/ledger/runs.jsonl       one line per run, append-only\n~/.local/state/vstack/cache/<key>/last-evidence.json\n~/.local/state/vstack/retro/<date>.md         written by vstack retro\n```\n\nA brief from a real dry run, so you know the register:\n\n```\nPRISM daily exec update (dry run, 11/07 sample data): RED.\nIngestion 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).\nDraft at .../prism-update.md. Reader action: nothing (dry run, not posted).\n```\n\nAll under `skills/`, one directory each, linked into every harness. The writers never fetch and\nnever publish: they turn evidence into a document and nothing else.\n\n| Skill | Use when | Reads | \n|---|---|---|\n| `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` | \n| `write-talent-card` | a per-person talent-review card: rating rationale and key deliverables sections | `template.md` | \n| `write-work-summary` | a structured work summary: timeline, task, challenges, action, result, artifacts | `template.md` | \n| `write-promo-doc` | a narrative promotion document against a level rubric, with a real Reasons Not To Promote section | `template.md` ,`rubric-TEMPLATE.md` | \n| `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` | \n| `rewrite` | tighten supplied prose to the house rules, every fact and link preserved, nothing added |  | \n| `rewrite-and-validate` | the same, then loop through the gate until it passes, at least two passes |  | \n| `score-gate` | run any draft through the gate in a fixed loop and return the final draft plus a one-line result |  | \n| `gather-evidence` | the gather stage: cache-first, by connector, one `evidence.json` , never prose |  | \n| `leadership-writing` | not invoked. Holds `house-rules.md` (the voice: 17 rules, 4 of them mechanical blockers),`glossary.md` (neutral defaults) and`rationalizations.md` (12 excuses with their rebuttals, 7 red flags). Every writer and the critic read all three first |  | \n\nThe voice in one paragraph: lead with the point and the fact behind it, active voice, no\nsuperlatives, no hedging, no em-dashes or semicolons, every claim tied to an artifact in the\nevidence, every missing fact labelled `(unverified)` or listed under Known Gaps, never invented.\n\nA rule nothing enforces is a wish. [docs/RULES.md](https://github.com/ivikash/vstack/blob/main/docs/RULES.md) pairs every rule with its check.\nThe checks, in the order they run:\n\n| `scripts/check.sh` group | Fails when | \n|---|---|\n| identity | a commit here is not by the personal e-mail, or `git config user.email` is wrong | \n| no-org | any public file carries a company term, internal host, ticket, chat, doc or account id | \n| schemas | a JSON file does not parse, or the example instance breaks an invariant | \n| frontmatter | a skill's `name` is not its directory name in lowercase-hyphen, or a description is empty or over 1024 characters | \n| loop | a writer skill lacks the gate loop (min 2, max 5, reads house-rules) | \n| glossary | a skill references a glossary key that is not defined | \n| triggers | a skill's description does not win its own prompts in `evals/triggers.json` (36 cases, no model) | \n| rules | `docs/RULES.md` names a check or subcommand that does not exist | \n| instance | with `VSTACK_INSTANCE` set: the instance is inside this checkout, is a remote of it, or has a public remote | \n\nAnd `vstack check` over an instance:\n\n1. Writers and gates never fetch: a writer receives `evidence.json` and nothing else.\n2. Every writer has exactly one gate before its sink, `min_passes` at least 2.\n3. Every sink records: a workflow with no ledger fields fails.\n4. The privacy cut: a private workflow names a private workspace, and its ledger fields may not carry rating, candidate, promo, salary or feedback text.\n5. Every workflow has a `dry_run_path` , so it can run with no side effects.\n6. A writer reads at least two sources, more when `coverage` says so.\n7. Every source is a connector name, never a tool name.\n\nAnd after every run, the **contract**: `evidence.json` with sources and hash, `diff.md`, `draft.md`\nwith its `Sources:` line, `gate.md` with enough passes, a three-line `brief.md`, `result.json`.\n\n| Command | Does | \n|---|---|\n| `vstack render <workflow> [--harness h]` | print the prompt, run nothing | \n| `vstack run <workflow> --harness h [--dry-run] [--no-publish] [--second-opinion h2] [--agent a] [--model m]` | pre-flight, render, execute, contract check, ledger line | \n| `vstack check [--instance d]` | invariants over the workflows | \n| `vstack map [--instance d] [--json]` | the estate derived from the workflows: sources, writers, gates, sinks, ledgers, bots | \n| `vstack check-run <run-dir>` | contract check on an existing run directory | \n| `vstack verify-skills --dirs ... --skills ...` | every named skill present and identical in every harness dir | \n| `vstack link-skills --canonical d --targets ... --skills ...` | symlink the canonical skills into each harness dir | \n| `vstack gen-cron --harness h [--instance d]` | crontab lines, or `kirocrew cron add` commands with the bot to bind to | \n| `vstack gen-agent --harness kiro [--instance d]` | a Kiro CLI agent template whose tool surface is exactly `connectors.json` | \n| `vstack gen-mcp --servers f --target h` | the MCP server block for one harness | \n| `vstack retro [--days n]` | per-workflow runs, contract misses, gate passes, recurring Known Gaps | \n\nEvery command accepts `--instance DIR` or reads `$VSTACK_INSTANCE` and fills `--connectors`,\n`--glossary` and `--workflows` from it. State lives under `~/.local/state/vstack`.\n\n```\nbin/vstack               the CLI, one file, standard library only\nschema/                  workflow, connectors, ledger (JSON Schema)\nskills/                  one canonical copy of every skill\nharness/README.md        the four harnesses: exact command, skills dir, what a run leaves behind\nexample/                 a complete instance for a made-up company: README, connectors.json, glossary.md, mcp-servers.json, workflows/ with sample evidence, vstack.lock\nevals/                   triggers.json, fixtures/ (synthetic evidence packs the skill evals read), results/\nscripts/check.sh         the nine check groups\nscripts/trigger-eval.py  the routing eval\ndocs/ARCHITECTURE.md     why two repos, the layers, the run, the derived map, the scales\ndocs/RULES.md            every rule and its enforcer\n```\n\n| Symptom | Cause and fix | \n|---|---|\n| `pre-flight failed (skills)` | a harness dir has a stale copy or is missing a skill. `vstack link-skills ...` again, then`vstack verify-skills` | \n| `pre-flight failed (invariants)` | the workflow breaks a rule. `vstack check` prints each one | \n| `\"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 | \n| `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` | \n| draft says `Sources: ... unavailable chat.search` | the connector is unbound in `connectors.json` , or the tool returned nothing. Fix the binding or the`ref` , never the draft | \n| Kiro CLI denies a tool | kiro-cli 3.x denies any tool not named in `--trust-tools` ; run under the`vstack-runner` template from`vstack gen-agent` , or let the adapter pass`--trust-all-tools` | \n| 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 | \n| `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 | \n\nWhy two repositories, what each layer owns, the derived map, the privacy cut and the same\nworkflow at four scales: [docs/ARCHITECTURE.md](https://github.com/ivikash/vstack/blob/main/docs/ARCHITECTURE.md). Recorded test runs:\n[evals/results/](https://github.com/ivikash/vstack/blob/main/evals/results).\n\nMIT.", "url": "https://wpnews.pro/news/vstack-ai-for-management-and-leadership", "canonical_source": "https://github.com/ivikash/vstack", "published_at": "2026-11-16 06:20:29+00:00", "updated_at": "2026-11-16 06:53:06.263243+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Vstack", "Claude Code", "Codex", "Kiro CLI", "Kiro Crew", "Agent Skills"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/vstack-ai-for-management-and-leadership", "markdown": "https://wpnews.pro/news/vstack-ai-for-management-and-leadership.md", "text": "https://wpnews.pro/news/vstack-ai-for-management-and-leadership.txt", "jsonld": "https://wpnews.pro/news/vstack-ai-for-management-and-leadership.jsonld"}}