Skip to content
View Stroi's full-sized avatar
  • Bohemia

Block or report Stroi

Block user

Prevent this user from interacting with your repositories and sending you notifications. Learn more about blocking users.

You must be logged in to block users.

Content in all repositories owned by your account will be closed.
Maximum 250 characters. Please don’t include any personal information such as legal names or email addresses. This note will only be visible to you.
Report abuse

Contact GitHub support about this user’s behavior. Learn more about reporting abuse.

Report abuse
stroi/README.md

stroi

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
Loading

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.


Install

# from GitHub (recommended)
/plugin marketplace add https://github.com/Stroi/stroi
/plugin install stroi@stroi

Or 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).

Requirements

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.

Your first 10 minutes

  1. /stroi:setup — where issues live, how you test, how strict reviews are. Writes one config block into CLAUDE.md.
  2. /stroi:docs-init — maps your codebase into CLAUDE.md map blocks agents load just-in-time; optionally interviews you for a domain glossary.
  3. /stroi:prd-new dark mode — grilled one question at a time until the spec is solid.
  4. /stroi:issues-new — the PRD becomes small, end-to-end issues with dependencies.
  5. /stroi:issue-start 0001 — routes into the right planner and builds it, gated by your approval and per-checkpoint verification.
  6. /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.

The issue lifecycle

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 --> [*]
Loading
  • issue-start refuses blocked issues — every blocked-by reference must be done first. (plan-big / plan-fast run the same readiness check when handed an issue ref directly.)
  • finalize refuses 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.

How plan-big builds an issue

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"]
Loading

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).

Skills (slash commands)

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.

Per-repo config — one block, greppable

/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 exemplar path:lines, an ADR, an [S-###] rule, an acceptance criterion — so "looks fine to me" is never a verdict.

Agents & model tiers

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.

What runs automatically (hooks)

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.

Docs the agents actually use

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.

The morning ritual — progress-status

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.

Learning — the Ratchet

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 (bumps hits: 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 inside docs-update.
  • /stroi:learn-global — the rare personal, cross-project lesson → your ~/.claude memory.

Project by default, global only on request — rules live where the code lives.

Where stroi writes

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

Session badge (color + live progress)

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" }
}

Development

./tests/run.sh

Checks 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.

Philosophy

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.

License

MIT — see LICENSE.

@Stroi's activity is private