A lean software-development delivery harness for Claude Code, packaged as a plugin.
stroi takes a feature from idea → spec → issues → implementation → verified, reviewed, closed with evidence — and keeps the whole cycle honest with approval gates, independent review, a cross-worktree overseer, and a learning ratchet. It is mechanism, not content: no language or framework skills are bundled; you bring those and bind them per-scope.
📐 Visual overview — the whole harness in eight diagrams: the cycle, gated execution, issue states, agents, hooks and config. Start there if you'd rather see it than read it.
flowchart LR
subgraph once["🔧 once per repo"]
setup["/stroi:setup<br>configure"] --> dinit["/stroi:docs-init<br>map the codebase"]
end
subgraph cycle["🔁 every day"]
ps["/stroi:progress-status<br>☀️ morning: status + what to work on"] --> istart["/stroi:issue-start<br>pick one up"]
ps -.->|"independent items?<br>spawn worktrees ∥"| istart
istart --> impl["plan-big / plan-fast<br>build + verify + review"]
impl --> fin["/stroi:finalize<br>close issue + session,<br>with evidence"]
fin --> ps
end
subgraph spec["🆕 per feature"]
prd["/stroi:prd-new<br>spec it"] --> isu["/stroi:issues-new<br>slice into issues"]
end
once --> cycle
spec --> cycle
Everything in the cycle is optional — with no tracker configured, stroi behaves like a pure
planning/verification harness (plan-fast, plan-big, verify, learn all work standalone).
Built to the doctrine in HARNESS.md: start minimal, earn each piece,
separate the generator from its evaluator, and ratchet every fix into a control.
# from GitHub (recommended)
/plugin marketplace add https://github.com/Stroi/stroi
/plugin install stroi@stroiOr iterate on a local checkout with claude --plugin-dir ./stroi.
Confirm: the /stroi:* commands appear, the seven stroi-* agents show under /agents, and
Context7 is connected (/mcp).
| git | required | Every planning and status skill reads the working tree. Outside a repo the hooks degrade quietly. |
| bash | required | Hooks target bash 3.2 (macOS system bash) and use no GNU-only flags. |
| Context7 MCP | bundled | Declared in .mcp.json and started with the plugin — a plugin's MCP server is not user-optional. Planner and developer fall back to WebFetch when it's unavailable. |
jq · gh |
optional | jq for the opt-in statusline's context figure; gh for the GitHub tracker and PR reporting. Both degrade gracefully; no hook depends on either. |
Hooks load once at session start and cannot be hot-swapped — restart Claude Code after changing
the plugin, its hooks, or .mcp.json.
/stroi:setup— where issues live, how you test, how strict reviews are. Writes one config block intoCLAUDE.md./stroi:docs-init— maps your codebase intoCLAUDE.mdmap blocks agents load just-in-time; optionally interviews you for a domain glossary./stroi:prd-new dark mode— grilled one question at a time until the spec is solid./stroi:issues-new— the PRD becomes small, end-to-end issues with dependencies./stroi:issue-start 0001— routes into the right planner and builds it, gated by your approval and per-checkpoint verification./stroi:finalize— verify gate, issue evidence + close, docs, learnings, commit, summary.
Then start each morning with /stroi:progress-status. Skipped setup? Everything still works
on defaults: no tracker, tests-required, standard review, concise output.
Issues move through a small state machine; each transition names the command that causes it:
stateDiagram-v2
[*] --> needs_triage: issue created
needs_triage --> needs_info: triage — details missing
needs_info --> needs_triage: reporter replies
needs_triage --> ready_for_agent: triage — agent brief posted
needs_triage --> ready_for_human: triage — needs a human decision
needs_triage --> wontfix: triage — rejected (KB entry)
ready_for_agent --> in_progress: issue-start
ready_for_human --> in_progress: issue-start
in_progress --> done: finalize — evidence stamped
done --> [*]
wontfix --> [*]
issue-startrefuses blocked issues — everyblocked-byreference must be done first. (plan-big / plan-fast run the same readiness check when handed an issue ref directly.)finalizerefuses unverified closes — each acceptance criterion is re-checked against reality, and the close carries evidence (gates · validator · reviewer · commits).- Rejected enhancements land in
docs/stroi/out-of-scope.md, so the next duplicate request is caught at triage.
flowchart LR
lock["🔒 auto read-only lock"] --> ex["explore<br>(≤3 explorers)"]
ex --> pl["design plan<br>(planner)"]
pl --> ap{"you<br>approve?"}
ap -->|changes| pl
ap -->|yes| cp["build checkpoint<br>(developer)"]
cp --> gate{"verify gate<br>green?"}
gate -->|"red — ≤2 fixes"| cp
gate -->|"next checkpoint"| cp
gate -->|"all green"| vr["validate ∥ review<br>(independent)"]
vr --> fx{"issues?"}
fx -->|"≤2 fixup rounds"| cp
fx -->|clean| cl["docs-update · evidence<br>summary · learnings"]
Nothing is edited before you approve the plan (a real read-only lock, not a promise). The developer never grades its own work — a separate validator and an adversarial reviewer do, in fresh context. Every fix loop is bounded (≤2) and then comes back to you.
Two things happen quietly along the way: every failure (red gate, validator FAIL, reviewer
block, fixup round) is recorded to a durable signal log that later feeds
/stroi:learn --review, and on long runs a green gate prints a one-line /compact suggestion —
that's the loss-free moment to compact, since all plan state is already on disk (much better
than auto-compaction firing mid-checkpoint).
| Group | Command | One line |
|---|---|---|
| Setup | /stroi:setup |
Interactive per-repo config: tracker + conventions, labels, testing policy, review strictness, style, docs, scribe, dispatch mode. Re-run to update. |
| Oversee | /stroi:progress-status [--deep] |
☀️ The morning ritual: roadmap + PRs + branches + updates since last run → "you can work on", plus the parallel-worktree dispatch offer; --deep adds an architecture sweep. |
| Deliver | /stroi:prd-new <idea> |
Grilling interview → PRD on the tracker (--fast = no interview). |
/stroi:issues-new [prd] |
PRD → thin end-to-end issues with blocked-by dependencies. | |
/stroi:triage [ask] |
Evaluate incoming issues; reproduce bugs; post agent briefs; reject into the KB. | |
/stroi:issue-start <id> |
The router: verify ready + unblocked → mark in-progress → route to a planner. | |
| Plan | /stroi:plan-fast <ask> |
Small known changes: inline plan, quick approval, implement. |
/stroi:plan-big <goal|issue> |
Complex work: the full pipeline above. Resumable across compaction. | |
/stroi:verify [scope] |
Mechanical health gate: build / typecheck / lint / test / security / diff. Not a code review. Silent on pass. | |
| Docs | /stroi:docs-init [scope] |
First-run: generate CLAUDE.md map blocks + optional domain glossary/ADR interview. |
/stroi:docs-update [scope] |
Maintenance: refresh stale maps, verify doc pointers, curate rules. Headless-safe. | |
| Learn | /stroi:learn "<rule>" |
Ratchet a lesson into a traceable [S-###] project rule (--review mines the session, --curate tidies). |
/stroi:learn-global "<rule>" |
The rare cross-project personal lesson → [G-###] in your ~/.claude memory. |
|
| Close | /stroi:finalize [id·notes] |
One close-out for everything: verify gate → issue evidence + close (auto-detected) → docs → learnings → commit ask → summary. |
/stroi:setup writes a marked block into the root CLAUDE.md (always loaded, readable by
prompts and hook scripts alike). Hand-edits are fine; unknown values fall back to defaults.
| Key | Values (default first when unconfigured) | What it changes |
|---|---|---|
tracker |
none · local · github · freeform |
Where PRDs/issues live; none keeps tracker skills dormant. Detail: docs/stroi/tracker.md. |
labels |
default · custom |
Map stroi's triage states onto your tracker's label names. |
testing |
tests-required · tdd · no-tests |
TDD: checkpoints open with a failing test. no-tests: verification = build/lint/smoke, no test scaffolding. Per-repo on purpose. |
review |
standard · strict |
strict: reviewer reports ≥50%-confidence findings, any HIGH blocks. |
style |
concise · standard |
concise (default): a session-start hook injects a terse-output directive. |
docs |
single · multi |
One CONTEXT.md, or CONTEXT-MAP.md pointing at per-context files. |
glossary / adr |
off/on per setup | Domain glossary (CONTEXT.md) and decision records (docs/adr/) maintenance. |
scribe |
on · off |
Delegate rote text (commits, tracker bodies) to the cheap haiku scribe. |
model-<agent> |
per-agent default | Override one agent's model: inherit · sonnet · opus · haiku. One key per agent — model-planner, model-developer, model-reviewer, model-overseer, model-validator, model-explorer, model-scribe. Omit to keep its default tier. |
dispatch |
print · terminal · tmux |
How progress-status presents spawned worktree sessions: paste-ready commands, macOS terminal windows, or tmux windows. |
review-skills |
none · skill ids |
Stack-specific skills the plan-big reviewer ALSO applies (review already runs in plan-big by default), e.g. react-best-practices. |
verify-commands |
none · commands |
Extra commands every verify gate runs (plan-big checkpoints, validator, finalize), e.g. pnpm test:e2e. |
Tracker choices: local keeps issues/PRDs as markdown under docs/stroi/; github uses
the gh CLI; freeform covers Linear, Jira, or an existing issues folder — describe six verbs
once (publish / fetch / list / comment / label / close) and every skill follows that file. It
also carries a ## Conventions section (naming, project/team, priorities, required fields) that
every tracker-writing skill reads first, so issues match how your tracker is organized.
Verify vs review — and where your skills plug in:
- verify = the mechanical gate (build · typecheck · lint · tests · security · diff). Runs
commands, no judgment. Built into plan-big's checkpoint gates, the validator, and finalize.
Extend with
verify-commands. - review = adversarial judgment, already included in plan-big (finalize never re-runs it).
Extend with
review-skills. Judgment has to bite on something: each rubric criterion names the bar it's judged against — an exemplarpath:lines, an ADR, an[S-###]rule, an acceptance criterion — so "looks fine to me" is never a verdict.
Cost follows the job — recon and bookkeeping don't need your strongest model. Every row below is
a default: any of them can be overridden per repo with the matching model-<agent> config key.
| Agent | Model | Job |
|---|---|---|
stroi-scribe |
haiku | Rote text: commit messages, tracker bodies, changelogs. Never edits code. |
stroi-explorer |
sonnet | Read-only codebase recon for planning and docs. |
stroi-validator |
sonnet | Runs the verify loop independently; can't edit. |
stroi-developer |
sonnet | Implements one checkpoint per spawn, against a plan you already approved. |
stroi-planner |
your session model | Designs the living plan; researches docs first. |
stroi-reviewer |
your session model | Adversarial review: correctness, security, architecture & patterns, rubric. Can't edit. |
stroi-overseer |
your session model | Roadmap, evidence audit, PR/branch/updates report, worktree checks. Writes only ROADMAP.md + tracker comments. |
Tip: run plan-big on your strongest session model — planner and reviewer inherit it, so design
and judgment stay sharp while the developer implements on sonnet. Want it on your session model
too? - model-developer: inherit.
The reviewer's architecture & patterns dimension checks each change against the scope's
documented architecture, the plan's reuse table, the ADRs, the glossary's vocabulary and earned
[S-###] rules, and flags unjustified new dependencies. Its report opens with a per-dimension
verdict table, so nothing looks skipped.
Deterministic, silent on success, each with an explicit timeout.
| When | What | Effect |
|---|---|---|
Before any Bash call |
safety guard | Blocks catastrophic commands — rm -rf /, force-push, DROP TABLE, raw disk writes, fork bombs. Reads the command itself, not the surrounding payload. |
| Session start | map staleness | One line per scope whose CLAUDE.md map lags the code. Silent when clean. |
| Session start | style | Injects the concise-output directive unless style: standard. ~25 tokens. |
After Write · Edit · MultiEdit · NotebookEdit |
dirty log | Records touched paths (outside the repo) so staleness detection works. |
| Before compaction | handoff | Snapshots a resume pointer so a long plan-big run survives. |
| Session end | cleanup | Clears finished-run state and stale overseer locks; nudges un-harvested learnings. |
Each scope's CLAUDE.md holds two regions: your rules (hand-written + earned [S-###]
conventions) and a generated map block (architecture, entry points, patterns, dependencies
with doc links) between stroi:map markers. The root map is always loaded and stays tight;
per-package leaf maps load just-in-time. docs-init creates them, docs-update refreshes them,
and nothing outside the markers is ever touched.
Optionally, the repo also keeps a domain glossary (CONTEXT.md — canonical terms, one
definition each) and ADRs (docs/adr/ — one paragraph per hard-to-reverse decision).
prd-new's grilling challenges your wording against the glossary and updates it inline; the
reviewer enforces both.
Link your own skills to a scope by listing them under ## Relevant Skills in that scope's
CLAUDE.md, outside the map markers — applied during development, verification and review in
that scope only. ## Code Review alongside it carries scope-specific review notes. Scope lists
say where; the config block's review-skills / verify-commands say always.
Run /stroi:progress-status at the start of every day. It answers "where does the project
stand, and what can I work on?" — then offers to parallelize.
- Roadmap — orders open issues by unblocking power → priority → age; flags dependency
cycles and stale in-progress work. Written to
docs/stroi/ROADMAP.md(only when changed). - PRs — your open PRs with CI + review state, and PRs awaiting your review (needs a
GitHub remote +
gh; silently absent otherwise). - Branches — unfinished branches ahead of the default, with unpushed commits.
- Updates since last run — tracker items created/changed since the previous status.
- Evidence audit — issues closed without verification evidence get flagged and commented.
- Worktree check — with several parallel worktrees, flags branch pairs touching the same modules and components that should be shared instead of built twice.
--deep— an architecture sweep for duplication, pattern drift, and rule violations.
Parallel dispatch: when ≥2 ready items are independent, it offers a git worktree per item,
each handed to its own Claude session — as paste-ready commands (print, default), macOS
Terminal windows (terminal), or tmux windows (tmux). Each gets its own color badge and
isolated runtime state. Nothing spawns without your explicit pick, and never on scheduled runs.
A lockfile keyed by the main repo keeps exactly one overseer running across all worktrees.
Scheduled mode (opt-in): the report is headless-safe, so you can wire
claude -p "/stroi:progress-status" as a cron job or a Claude Code scheduled routine — setup's
section F prints the instructions.
Every lesson becomes a traceable, itemized rule:
## Conventions (earned)
- [S-012] Use the http client in `lib/` — never add a new one. (why: dup-client bug · hits: 3)/stroi:learn "<rule>"— dedups against existing rules (bumpshits:instead of duplicating), then offers escalation: prose line → deterministic hook → reviewer check./stroi:learn --review— reads the recorded failure log (signals.log— every red gate, verify FAIL, and review finding, appended at the moment it happened, so nothing is lost to compaction or recall), clusters by root cause, and proposes rules with the log lines as evidence. Cleared once harvested./stroi:learn --curate— merges near-duplicates, sharpens wording, proposes pruning dead rules. Also runs insidedocs-update./stroi:learn-global— the rare personal, cross-project lesson → your~/.claudememory.
Project by default, global only on request — rules live where the code lives.
| Where | What | Committed? |
|---|---|---|
CLAUDE.md (per scope) |
map blocks, config block, earned rules | ✅ yes — the only stroi artifacts that belong in the repo |
docs/stroi/ |
tracker adapter, local issues/PRDs, ROADMAP, out-of-scope KB | ✅ yes (when tracker = local) |
CONTEXT.md, docs/adr/ |
glossary + decision records (opt-in) | ✅ yes |
~/.claude/stroi/<project>/ |
plans, resume pointer, session badge, dirty log, failure-signal log | ❌ runtime, auto-cleans |
~/.claude/stroi/<main-repo>/shared/ |
overseer lock + last-run marker (shared across worktrees) | ❌ runtime, auto-cleans |
Each plan run gets its own color, shown as a one-line banner in chat
(🟣 **<goal>** — planning) and, opt-in, as a statusline badge with the current
stage/checkpoint and context usage. Enable the statusline by pointing your settings.json at
the shipped script:
{
"statusLine": { "type": "command", "command": "<stroi>/hooks/scripts/statusline.sh" }
}./tests/run.shChecks hook syntax and exec bits (in the git index, not just the working tree),
manifest/marketplace version agreement, skill and agent frontmatter, that every sibling
reference resolves, and guard allow/block behaviour across 24 cases. CI runs the same suite on
Linux and macOS — bash 3.2 and the BSD userland, where a GNU-only flag would surface.
evals/ holds trigger cases for claude plugin eval.
This harness is deliberately small. Add to it only when you hit a real, repeated need — and use
/stroi:learn to make each addition traceable. Prune on model upgrades. See
HARNESS.md for the doctrine and sources.
MIT — see LICENSE.