Skip to content
cheezyPublic

About

Task lifecycle skills for Stride kanban: claiming, completing, creating tasks and goals

Resources

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Stride

Drive the full Stride kanban task lifecycle from Claude Code — claim, explore, review, and complete tasks, with automatic lifecycle hooks. Stride is a task management platform designed for AI agents.

Security: for what the plugin runs on your machine, what data leaves it, and how your API token is handled, see SECURITY.md.

External service: this plugin talks to your Stride server — https://www.stridelikeaboss.com by default — over HTTPS, authenticated with a bearer token you supply. It contacts no other host. See SECURITY.md for exactly what is sent.

Installation

From the community plugin directory (once the listing is approved):

/plugin install stride@claude-community

From the Stride marketplace (available today):

/plugin marketplace add cheezy/stride-marketplace
/plugin install stride@stride-marketplace

Prerequisites

  • A Stride account and API token from stridelikeaboss.com.
  • Two files in your project root: .stride_auth.md (your API URL + token — never commit it) and .stride.md (your lifecycle hook commands). See Configuration below for the exact format.

What's in this plugin

  • 7 skills — stride-workflow (the recommended orchestrator), plus stride-claiming-tasks, stride-completing-tasks, stride-creating-tasks, stride-creating-goals, stride-enriching-tasks, and stride-subagent-workflow.
  • 5 subagents (Claude Code) — task-explorer, task-enricher, task-decomposer, task-reviewer, and hook-diagnostician.
  • 2 slash commands — /stride:create-tasks and /stride:create-goals.
  • Hooks — hooks/hooks.json wiring plus stride-hook.sh and stride-skill-gate.sh (with .ps1 equivalents) for automatic lifecycle hook execution and the sub-skill gate.

Each component is detailed below.

Mandatory Skill Chain

Every Stride skill is MANDATORY — not optional. Each skill contains required API fields, hook execution patterns, and validation rules that are ONLY documented in that skill. Attempting to call Stride API endpoints without invoking the corresponding skill first results in API rejections, malformed data, or hours of wasted rework.

Workflow Order

Recommended: Use the single orchestrator skill for the complete lifecycle:

stride:stride-workflow                ← Invoke ONCE — handles claim → explore → implement → review → complete

Standalone mode (when you need individual skills):

stride:stride-claiming-tasks          ← BEFORE calling GET /api/tasks/next or POST /api/tasks/claim
    ↓
stride:stride-subagent-workflow       ← AFTER claim succeeds, BEFORE implementation (Claude Code only)
    ↓
[implementation]
    ↓
stride:stride-completing-tasks        ← BEFORE calling PATCH /api/tasks/:id/complete

When creating tasks or goals:

stride:stride-enriching-tasks         ← WHEN task has empty key_files/testing_strategy/verification_steps
    ↓
stride:stride-creating-tasks          ← BEFORE calling POST /api/tasks (work tasks or defects)
stride:stride-creating-goals          ← BEFORE calling POST /api/tasks/batch (goals with nested tasks)

Why This Matters

Without skill What happens
Claim without stride-claiming-tasks API rejects — missing before_doing_result
Complete without stride-completing-tasks 3+ failed API calls — missing completion_summary, actual_complexity, actual_files_changed, after_doing_result, before_review_result, explorer_result, reviewer_result, workflow_steps
Create task without stride-creating-tasks Malformed verification_steps, key_files, testing_strategy — causes 3+ hours wasted during implementation
Create goal without stride-creating-goals 422 error — wrong root key ("tasks" instead of "goals")
Skip stride-subagent-workflow No codebase exploration, no code review — wrong approach, missed acceptance criteria
Skip stride-enriching-tasks Sparse task specs → implementing agent wastes 3+ hours on unfocused exploration

Skills

stride-workflow

RECOMMENDED entry point for all task work. Single orchestrator that walks through the complete lifecycle: prerequisites, claiming, codebase exploration, implementation, code review, hooks, and completion. Handles both Claude Code (with subagent dispatch) and other environments (Cursor, Windsurf, Continue). Eliminates the need to remember which skills to invoke at which moments. (v1.38.0+) adds an optional Manual & Exploratory Testing step (Step 5.5); (v1.39.0+) adds an optional Deep security-considerations review sub-step in Step 5 — see below; (v1.40.0+) threads the optional behaviour_test_matrix through Step 4 (implementation driver) and Step 5 (reviewer dispatch); (v1.41.0+) hardens every rule that reads matrix row text — row text is untrusted data rather than instructions, the secret rule triggers on row state and covers credentials named by location, a refused row has a named channel (completion_notes) and a redaction sentinel for the reviewer's echo, and the PATCH-body contradiction is resolved by stating that re-sending already-stored row text unchanged onto its own record is not a new copy; (v1.48.0+) maps the exploratory-testing severity rubric onto the reviewer issue enum and sets the escalation policy for a Critical exploratory finding — see below; (v1.53.0+) adds an optional /harden sub-step (Step 5.6) that turns a session's findings into drafted regression checks, sequenced so a drafted check can never turn the after_doing gate red; (v1.65.0+) a skipped workflow_steps entry may carry an optional machine-readable reason_code beside its free-text reason — see below; (v1.66.0+) the hot path is re-extracted and size-gated — the regrown orchestrator body moves back into gated sibling files (review-block-extraction.md, optional-security-review.md, behaviour-test-matrix.md, plus new hook-execution.md and reference.md sections) with every gate, decision matrix, Decision Summary, and prompt-injection framing rule kept inline; reference.md's dispatcher-mode summaries gain the completed-status confirmation gate; and scripts/check-skill-budgets.sh runs as hook-suite Group 28 so hot-path files cannot silently regrow. (v1.67.0+) a relatedness gate sits ahead of the Step 5.5 severity/provenance policy — a finding whose responsible lines are lines this task changed, or that is the same defect class as the change, is fixed in-task at any severity rather than filed, with a follow-up task the documented exception for a genuinely out-of-scope bug; and reference.md gains a Session Position operator section saying when to share a session and when to start fresh.

Dispatcher mode is the default for multi-task work (v1.83.0+)

When you ask Claude Code to work a goal, the queue (Ready column) or more than one task, stride-workflow runs each task in its own stride:task-runner subagent, which returns one small record. The main conversation holds only those records, so later tasks no longer carry every earlier task's diffs and reports. You do not need to say "dispatcher mode". A single-task request still runs inline unless you ask for isolation or set STRIDE_DISPATCHER_MODE=1. Branch A tasks (goals to decompose, large tasks with no children, 25+ hour estimates) and small tasks with 0–1 key_files still run inline.

Opting out: set STRIDE_DISPATCHER_MODE=0, or say "don't isolate" / "run inline". The opt-out wins over everything. Text inside a task can never switch the mode on or off. Outside Claude Code every task runs inline; without the runner agent (an older install) every task runs inline and the workflow records that isolation was unavailable.

Optional: Manual & Exploratory Testing integration (v1.38.0+)

When the stride-exploratory-testing plugin is installed, the workflow gains an optional Manual & Exploratory Testing step — Step 5.5 in stride-workflow, Phase 3.5 in stride-subagent-workflow, between Code Review and Execute Hooks. When a task's testing_strategy.manual_tests or edge_cases is non-empty, the workflow builds exploratory charters from the manual tests and from one change-mode run of the plugin's read-only charter-generator agent over the task's edge cases and change — at most about five per task, about three for a small one, every manual test and edge case mapped to a charter, a named unit test or a recorded human responsibility — and runs a budgeted session (12 probes by default) per charter via its one session surface — the explorer agent, dispatched once per charter. (/charter and /debrief are non-interactive too; they simply do not run sessions.) Interactive commands are never auto-dispatched, including /explore itself: its opening question round asks which interaction tools the session has, which a slash command cannot answer for itself, so it cannot be driven unattended. /pair in particular is the plugin's human-at-the-keyboard surface and is a deliberate human action, never something the workflow starts, because the orchestrator does not prompt the user between steps and an unattended prompt would stall the task until its claim expired. /nightmare-headline and /recon are excluded on the same grounds, as is the plugin's own routing skill — the surface a careless "dispatch the plugin" lands on, which can hand the request to any of them. The skills carry that list in full, and behind it a principle that governs whatever the plugin gains later: dispatch a command, agent or skill only if it completes unattended, judging it by the prompts it can raise rather than only those it always raises. The findings are recorded in existing completion fields (completion_notes and the reviewer_result.testing_strategy note) — no new completion field is introduced. (v1.51.0+) that summary also names who is harmed and how for each bug, not only its severity, since severity says how bad a failure is and never who it lands on — read from the installed contract's impact field where it has one, and assessed in the agent's own words where it does not. Where no reviewer ran, completion_notes is the only carrier and is persisted only by newer Stride servers, so one line is mirrored into the required, always-rendered completion_summary as a durability backstop — an existing field, not a new one. When a written session artifact exists, its path is cited so a reader can reach the full record instead of only the paragraph; the path is recorded repository-relative, and never the artifact's contents, which may hold unredacted session output. In practice the automated path writes no artifact — nothing in the explorer agent's contract asks it to write a session file — so the prose summary is the normal and complete record there, and a path appears only when a human separately ran a session that wrote one. Dispatched manual testing preserves the exploratory-testing safety boundary — it never runs destructive or production-mutating actions. Since v1.87.0 the creation skills, the decomposer and the enricher write each manual_tests entry as a risk charter by default (a target plus the information to discover, never a click script), and for a UI or HTTP feature they write edge_cases after considering each change-risk lens of the plugin's heuristics skill whose trigger matches, naming the lens; the testing_strategy shape and its validation are unchanged, and terse entries still validate. Before your first session, add .exploratory/ to the project's .gitignore, alongside .stride/. A session that writes to disk puts it there by default — /explore, /pair and /harden each take an --output flag that relocates artifacts elsewhere, and a relocated path needs its own entry — holding transcribed application output, and it arrives untracked — so if your .stride.md ## after_doing section stages everything before committing (git add -A is a common quality-gate shape), it will sweep those files into a commit. Neither behaviour is wrong on its own; they interact badly, and one line prevents it. The plugin never edits your .gitignore for you, and the entry is inert when the directory never appears. Add it before your first session: .gitignore does not untrack a path git already tracks, so an artifact that has already been committed needs git rm --cached as well.

(v1.84.0+) Step 5.5 follows stride-exploratory-testing 0.4.0's explorer contract (contract_version 1.0). Manual tests that share a target merge into one charter, at most about three run per task (about five for a medium or large task since v1.87.0, which also adds edge-case and change-risk charters), and independent observe-only charters are dispatched together. Every dispatch fills one fixed template that carries the explorer's required AUTHORIZED_NON_PRODUCTION: yes and ALLOWED_HOSTS: lines, written only when you gave the Step 0 affirmative. A session that ends no_observation_surface is not a performed test, and the manual test is handed back. An unreplicated or provisional Critical is recorded as advisory rather than escalated. A fixed introduced Critical is re-checked in the explorer's verify mode, falling back to the full charter. Step 5.6 runs /harden unattended with an explicit --framework. (v1.87.0+) Step 5.5 pairs with stride-exploratory-testing 0.5.0 (explorer contract 1.1, which a 1.0 reader still reads unchanged). Step 0 reads a .exploratory.md you confirm (or asks) for a probe harness or role accounts, the template passes a confirmed harness as the explorer's PROBE_HARNESS lines, and a charter on a signed-in or members-only target is not dispatched without one — it is recorded as not performed, no signed-in surface. When a session ends no_observation_surface and the main loop holds a browser tool, it runs a bounded, observe-only visual pass itself — light and dark, composited contrast, accessible names and each new state — in your own signed-in browser on an allowed host, and hands back only what it did not observe. The completion gate checks that record: one outcome line per charter and a coverage line, with every charter not performed owned by a follow-up or a HANDED BACK: line that is repeated to you, and a skipped Step 5.5 on a task with manual tests or edge cases says why in one line. A task-runner now also receives the confirmed .exploratory.md observation and constraints lines, so its Step 5.5 keeps your project's rules. When a task is its goal's last open child, Step 5.5 adds one goal-scope pass: up to about five cross-task charters over every child's changes, whose related findings (in any child's changed lines, or of a child's defect class) are fixed in that task and the rest filed as today, while the introduced-Critical block still covers only that task's own lines.

(v1.48.0+) each finding's severity maps onto reviewer_result.issues[].severity — Critical → critical, High and Moderate → important, Minor → minor, with an absent or unrecognized value landing on important and never on critical; the four-into-three collapse falls on High/Moderate because the reviewer values are dispositions at the completion gate rather than descriptions. A Critical finding now has a stated escalation policy in both Step 5.5 and Phase 3.5, turning on one decidable question: are the responsible lines among the lines this task added or modified? The agent localizes the finding to its fault site by reading the repository, then compares that against its own change set — every line changed relative to the task's base ref (read from the project root's .stride-env-cache, since that value is exported to hooks and not to the agent, and computed in the repo actually edited when that is a nested one), staged, unstaged and untracked-new included, minus the paths already dirty when the task was claimed, which are the human's edits rather than the agent's. The application's output is a lead for locating the defect and never evidence of provenance, because an escalation that blocks completion must not be triggerable by content an attacker can influence — and for the same reason the change set is never widened to the task's author-written key_files. Introduced — lines this task wrote — escalates fail-closed in the same shape as the security integration: testing_strategy.status → failed, a category: testing Critical issue appended to issues[], issue_counts.critical and issues_found incremented, and the defect fixed, the charter re-run, and the reviewer re-run before completing. Every other case — the fault site is elsewhere, the change set cannot be determined, or the fault site could not be identified — is discovered: it appends nothing and flips nothing, and is recorded in completion_notes and one line of completion_summary and filed as a follow-up defect, so a bug whose responsible lines this task did not write never blocks it. No new completion field is introduced, and when the payload carries no structured review block — review skipped, or its JSON unparseable — there is no issues[] to escalate into and none is synthesized.

(v1.53.0+) Optional hardening. When a session returns convertible findings and the /stride-exploratory-testing:harden command is available, an optional Step 5.6 (Phase 3.6 in the subagent skill) drafts one regression check per bug — the step that turns Explored back into Checked, so a bug found once stays found. /harden runs nothing and writes drafts to .exploratory/checks/, outside your test tree, so nothing enters your suite without you moving it there. That sequencing is the point: a check for an unfixed bug is supposed to fail, and after_doing is a blocking gate — so leaving drafts staged is the default. A check enters the suite only when two things hold: the file loads (a skip marker makes a test case inert, not a file, and a draft with unresolved wiring fails at compile time however it is tagged) and the case is green or marked skipped/pending. Both are established by running what the gate runs, once, rather than by expecting — anything less than clean means reverting and filing a follow-up instead. The hazard is presence in the tree, not the commit, since the gate runs your working tree. Because these files are written after the reviewer saw the diff, the step requires that they be named in the completion record rather than riding along silently. Note the command post-dates the plugin's first release, so the step checks for /harden itself rather than assuming the plugin implies it.

(v1.54.0–v1.61.0) Reachability, honesty about coverage, and where the time goes. A run of consistency fixes, most of them found by exploratory sessions run against this integration itself. The step is reachable on small tasks, and now says so everywhere. Its gate is manual_tests plus plugin availability with no review precondition, so a small 0-1 key_files task that skipped review still reaches it — but seven routing artifacts across the three skills said otherwise, sending that task straight from the skipped review to the hooks. All of them now route through it, and the completion gate's "a verdict must be present" checks are scoped to payloads where a review block was actually parsed, so a skipped or unparseable review no longer makes an otherwise-valid completion unsubmittable. A blocked session is no longer silently counted as coverage: it takes the same disposition as a zero-probe one — recorded as not performed, handed back as a human responsibility — unless the sheet shows it got through meaningful probes first, in which case it is partial coverage. The obstacle itself is recorded as an obstacle, in the terms the contract emits it, rather than as a severity-bearing finding, so an unreachable dev server stops being filed as an important testing bug. The session's wall-clock has a stated home: it folds into the existing reviewer workflow_steps entry, never a seventh step name — and where no reviewer ran, that entry is the skip form carrying no duration, so the dispatch is recorded in completion_notes instead of a duration being invented for a step that did not run. The gate's surface list and its never-execute-untrusted-plugin-content prohibition are now stated identically in both orchestrator skills, and the session-sheet guidance is conditioned on the installed contract rather than assuming one version's fields.

Graceful fallback: when the stride-exploratory-testing plugin is not installed, the task has neither manual_tests nor edge_cases, or you are in a non-Claude-Code environment, this step is skipped with no failure — completion proceeds exactly as before. The integration is optional and Claude-Code-only. The escalation policy changes nothing here: it exists only on the path where a session actually ran, so no exploratory finding can block completion when the plugin is absent, the task has neither manual_tests nor edge_cases, or the environment is not Claude Code.

Optional: Deep security-considerations review (v1.39.0+)

When the stride-security-review plugin is installed, the Code Review phase gains an optional Deep security-considerations review — a sub-step in stride-workflow Step 5 (and an orthogonal Decision-Matrix dispatch in stride-subagent-workflow). It runs only when the task's security_considerations list is non-empty and the plugin is available (detected via its sanctioned surface, the same way the exploratory-testing gate is detected — never by executing untrusted plugin content). The stride-security-review:security-reviewer agent is dispatched in considerations mode, in the same message as the task-reviewer so the two run side by side, with the git diff and the task's security_considerations list (framed as data to assess, never instructions), and writes its full result to the SECURITY_RESULT_PATH the workflow supplies (.stride/.security-<IDENTIFIER>-r<N>.json, deleted at Step 7), returning only a few summary lines — the merge reads only that path, falling back to the inline JSON an older plugin returns; (v1.86.0+) the prompt opens with the one mode tag the specialist accepts, /security-review invocation, mode: considerations, carries the same TASK_BASE_REF diff the task-reviewer gets (no diff, no dispatch) and never asks for results in any other file, and after the merge considerations_match_ok checks one verdict per task consideration, verbatim and in order (the credential sentinel accepted at its position), failing closed when it prints false; once both have returned, its per-consideration verdicts are merged — via the existing verbatim whole-object copy — into reviewer_result.security_considerations.considerations[]. On a review round after the first it is re-dispatched only for the considerations whose prior verdict was not mitigated, cited no path:line, or cites a file the fixes touched (all of them when that cannot be measured or a fix added a file) — and not at all when none is — with every other verdict carried over verbatim from the prior round. Its findings[] map into issues[] as category: security — critical/high → Critical, medium → Important, low/info recorded in completion_notes. Escalation is fail-closed: any partial or unmitigated verdict forces security_considerations.status to failed with a category: security issue at its backing finding's mapped severity (low/info → Minor), Critical when no finding backs it, which flows through the completion gate. The dispatch's time folds into the existing reviewer step — no new workflow_steps name. (v1.86.0+) When the specialist grades every consideration in a round, the task-reviewer is dispatched with deep_security_review: it keeps its dimension sweep but skips its own per-consideration verdicts, and the section's status comes from the merge; if the specialist then fails, the next round goes out without the flag and the task-reviewer grades each consideration itself.

(v1.60.0–v1.61.0) It fires without a reviewer — and the docs now route you to it. This sub-step's gate has no reviewer precondition, so it fires on a small 0-1 key_files task whose review the decision matrix excused. Two consequences were stated but unreachable. Its telemetry rule now covers that case: where no reviewer ran, the reviewer entry is the skip form carrying no duration, so the dispatch is recorded in completion_notes rather than a duration being folded into a step that did not run — and the entry is still submitted as dispatched: false, never dropped. (The JSON-parse fallback is explicitly not that case: there the reviewer did run and its entry keeps a real duration.) And the sub-step was structurally unreachable on that path — it is filed under the reviewer-dispatch section, which a small task never reads — so the "Skip review" branch now points at it, in the prose and in both flow summaries. Its gate conditions are unchanged; only its reachability was.

Graceful fallback: when the stride-security-review plugin is not installed, the task's security_considerations is empty (or an explicit None — … placeholder), or you are in a non-Claude-Code environment, this sub-step is skipped with no failure — the task-reviewer's prose verdict remains the sole source. On a review-skipped path there is no prose verdict to fall back to either, which is equally fine: the task simply continues with no security verdict recorded. If the plugin is present but returns malformed or absent verdicts, the review stays fail-closed: the prose verdict is kept (or, on a round that sent deep_security_review, the next round restores the task-reviewer's own check) and the anomaly is noted, never silently downgraded to passed. The integration is optional and Claude-Code-only.

Optional: workflow_steps[].reason_code (v1.65.0+)

A skipped workflow_steps entry may carry a machine-readable reason_code beside its free-text reason — the code is what the compliance dashboard aggregates, the prose is what a human reads on the task detail page. Six values, derived by classifying every skipped entry persisted on a real board rather than invented: decision_matrix_skip, ran_inline, hook_body_empty, subsumed_by_task_spec, folded_into_prior_step, matrix_deviation.

The measured problem: 73 skipped entries produced 58 distinct reason strings averaging 145 characters, so grouping them verbatim is very nearly one row per entry.

Supplying it is optional and omitting it is always valid — reason stays required-when-skipped and unconstrained, so an agent that predates this field, on any runtime, completes exactly as before. A reason_code outside the list is rejected, which is what stops a typo opening its own silent bucket. Use matrix_deviation when the decision matrix called for a step you did not run: it is the one code that records non-compliance, and reaching for decision_matrix_skip there would launder a deviation into a sanctioned skip. The validator and the aggregation live in the Stride server; emitting a code against a server that predates them is harmless.

Canon-governed — entry reason-code-vocabulary in docs/port-canon.md. That entry registers this vocabulary as one every port must carry, and the list above restates it rather than being its source of record. A change to its substance owes a version bump in two places before the next release: that entry in the canon, and stride's own reason-code-vocabulary anchor — which lives beside the picking table in skills/stride-workflow/SKILL.md, not in this file. This README deliberately carries no anchor of its own: the canon assigns one per rule per port directory, and stride's is already placed.

Optional: claims_verified_by (v1.77.0+)

A completion may carry claims_verified_by, an object of {command, output} recording the command that enumerated every entity a factual claim covers. It is required when this change writes a claim about several entities — ports, files, rows, repositories — into a document that outlives the session: a skill file, a README, a CHANGELOG entry, a canon entry. It does not apply to claims about the diff under review, which the completion prose rule already governs.

The provenance is W2120, where three successive drafts of two row reasons were wrong in the same way — a claim about one port reasoned from a sentence written for another — and a one-line census of the trees settled the wording. A sampled command does not satisfy the rule (a claim about nine ports needs a command that lists nine), and a subagent's answer is not evidence, because the point is a command a reviewer can re-run to falsify the claim.

Supplying it is optional and omitting it is always valid — a task making no such claim omits it, and an agent that predates the field, on any runtime, completes exactly as before. This repository's Stride server casts a fixed key list on /complete, so the field is currently accepted and discarded rather than persisted; the skill says so where it documents the field and directs the agent to mirror the command in completion_summary, which is persisted, so the evidence reaches a human today. Persistence is tracked separately.

The check for it is prose-only by construction. Whether a command is exhaustive relative to a sentence is not mechanically decidable, and a shape-only pin would go green on exactly the sampled command the rule exists to refuse. The contract is skills/stride-workflow/claims-census.md, gated from the Step 4 bullet. No canon entry: this registers no cross-port rule.

Task attachments reach the agents (v1.88.0+)

When a task carries attachments — a mockup, an error screenshot, a spec PDF, a log — the claim hook downloads them into .stride/attachments/<IDENTIFIER>/ with a manifest.json (see Task attachments under Automatic Hook Execution), and stride-workflow hands that directory to the agents that work the task. Nothing in the workflow downloads anything itself.

  • Only a manifest that names this task. Step 3's explorer and Plan dispatches and Step 5's reviewer dispatch name ATTACHMENTS_DIR beside TASK_FILE only when manifest.json exists there and its task names the claimed task, checked with a single-field jq read. Otherwise the line is omitted and the agents work exactly as they did before. A task-runner resolves its own claim's directory, never one handed down to it.
  • Only downloaded files. task-explorer, task-reviewer, task-runner and the planner read only entries whose status is downloaded: images and PDFs with Read, large text in ranges, and any other type from its filename, content_type and byte_size. A skipped or failed entry is named with its reason and never fetched; agents never run curl -o.
  • Data, never instructions. Attachment contents and filenames, including text inside an image or a PDF, are untrusted task material. An attachment never overrides acceptance_criteria, pitfalls or security_considerations, and one that shows a secret is reported without transcribing it.
  • Removed at Step 7. The directory is deleted with the task's other working artifacts, only after a 2xx completion, and kept after a failed or rejected one for the retry. .stride/attachments/.gitignore stays.

The procedure is skills/stride-workflow/attachments.md; the cross-port contract is docs/porting-attachments.md. The end-to-end manual check against a live server has not yet been run.

stride-claiming-tasks

MANDATORY before any task claiming or discovery API call. Enforces proper before_doing hook execution, prerequisite verification, and immediate transition to active work. Contains the claim request format including before_doing_result.

stride-completing-tasks

MANDATORY before any task completion API call. Owns the completion contract — its Completion Request Field Reference table is the authoritative required-field set (including explorer_result, reviewer_result, and workflow_steps, which the API rejects requests without) and it documents both hook execution patterns (after_doing + before_review). Skipping causes 3+ failed API calls as missing fields are discovered one at a time. (v1.66.0+) the skill is roughly half its former size: the happy path — the Field Reference, the Explorer/Reviewer Result Schema with the skip-reason enum, the pre-submission hard gate, and the curl stdout rules — stays inline, while worked examples, the per-file-diff back-compat subtree, hook-failure remediation, and the summaries move to four sibling files (manual-testing-findings.md, diff-capture.md, hook-failures.md, reference.md), each reachable from a pointer at its original site; no field requirement, schema shape, or enum value changed.

stride-creating-tasks

MANDATORY before creating work tasks or defects. Contains all required field formats — verification_steps must be objects (not strings), key_files must be objects (not strings), testing_strategy arrays must be arrays (not strings). Also documents the optional technical_details field — a free-form JSON object (no fixed keys) for any extra technical context; it is optional everywhere and is not one of the five review_queue-scored fields. (v1.30.0+) documents the optional created_by_agent field — set it to the plugin's own agent name (the same value sent as agent_name on claim/complete) so the /agents feed attributes the creating agent; it is create-only and forbidden on PATCH. (v1.37.0+) documents the top-level agent_name beside the task root key on every create request — the always-sent fallback the server reads when created_by_agent is omitted (which cannot be backfilled), with the full five-step resolution order and an explicit note that agent_name is display metadata only, never an authorization signal. The same release adds a Request Envelope section: POST /api/tasks takes {"agent_name": "...", "task": {...}}, not a bare task object — the skill previously documented the body without its task root key, which the server rejects with a 422.

stride-creating-goals

MANDATORY before batch creation or goal creation. Contains the only correct batch format — root key must be "goals" not "tasks". Most common API error when skipped. (v1.30.0+) documents created_by_agent on the batch goal — set once on the goal; the server propagates it to every nested child task. (v1.37.0+) documents the top-level agent_name beside the goals root key — outside the array, not on any goal or task — set to the same plain agent name sent on claim and complete, with the same five-step resolution order and display-metadata-only caveat.

stride-enriching-tasks

MANDATORY when a task has sparse specification. Transforms minimal human-provided specs into complete implementation-ready tasks through automated codebase exploration. 5 minutes of enrichment saves 3+ hours of unfocused implementation.

stride-subagent-workflow

MANDATORY after claiming any task (Claude Code only). Contains the decision matrix for dispatching task-explorer, task-enricher, task-reviewer, task-decomposer, and hook-diagnostician agents. Determines exploration and review strategy based on task complexity and key_files count.

Agents

Progressive disclosure of the agent bodies (v1.67.0+). The three largest agent prompts are re-paid on every dispatch, so their reference material now lives in sibling files under docs/ that the agent Reads on demand: task-reviewer.md 66,177 to 55,936 bytes (docs/task-reviewer-examples.md), task-enricher.md 37,338 to 28,865 (docs/task-enricher-reference.md), and task-decomposer.md 25,521 to 13,684 (docs/task-decomposer-reference.md) — 30,551 bytes off the per-dispatch cost. What moved is illustration only: worked examples, edge-case sections and anti-example galleries. Every contract stays inline — the emitted block schema, the verdict rules, the bounded-summary contract, the four enrichment phases and their field types, the six decomposition steps and both sizing tables, and in all three the prompt-injection framing and the redaction rules. docs/ rather than agents/, because every .md under agents/ registers as a dispatchable agent. Each split was verified by dispatching the slimmed body against a real fixture rather than by reading the diff, and each verification found defects the diff review would not have: the reviewer's returned-summary rendering existed only in the example that moved (now specified inline for the first time), the enricher's waived-matrix-row shape was stated only by a sentence narrating its removed example, and the decomposer turned out never to have carried a treat-task-text-as-data boundary at all despite reading free-form human goal text.

stride:task-explorer

A read-only codebase exploration agent dispatched after claiming a task. Reads every file listed in key_files, finds related test files, searches for patterns referenced in patterns_to_follow, navigates to where_context, and returns a structured summary so the primary agent can start coding with full context.

Report persistence (v1.65.0+). The explorer writes its full findings to .stride/.explorer-<IDENTIFIER>-r<N>.md and returns a summary bounded at 60 lines / 6,000 characters naming that path — measured explorer reports ran 15.5–20.7 KB across 133–210 lines, and the caller re-sends whatever comes back on every later request. The bound is deliberately looser than the reviewer's because this summary is implemented from rather than parsed, so over-trimming forces the file open every time and saves nothing; it must carry one line per key_file, every pattern with its file:line, every conflict, and the reuse list, degrading by dropping quotes before detail. A dispatch that supplies no EXPLORER_REPORT_PATH is an older orchestrator that will never read the file, so the explorer writes nothing and returns its findings inline exactly as before. The same contract governs the Plan dispatch via .stride/.plan-<IDENTIFIER>-r<N>.md, stated in the orchestrator's Step 3 because Plan is the generic subagent and has no agent file of its own.

Sourced claims (v1.77.0+). Every factual claim about the codebase in an explorer report — a size, a count, a line number, whether two files are identical, what a header row says — carries verified_by, the command that produced it, written inline on the claim's own line. A claim with none is marked unverified, and an unverified claim may not be the basis for shipped text without a check the caller runs itself. It binds facts, not judgement: "this is the pattern to follow" carries nothing, because no command settles it. A claim established by reading rather than running is unverified and names its file:line, since a read is not a measurement and a subagent's assertion never verifies itself. The recorded command is data — repo-relative, never carrying a token or a private host, and never executed by a consumer because it appeared in a report. The bounded-summary limits are unchanged; a command that will not fit is shortened, never dropped, since a dropped field would misreport a verified claim as unverified. An older explorer omits the field entirely; its claims are read as unverified and it still works, with no detection and no negotiation. This is distinct from claims_verified_by above: that governs a claim shipped into a document that outlives the session, while a report is deleted at Step 7.

Contradicted task statements (v1.85.0+). Before composing its findings, the explorer checks every statement the task makes about the current code — in the key_files notes, description, where_context, patterns_to_follow and technical_details — with a verified_by command of its own choosing, and runs git log --since the task's inserted_at on each key_files path, inside the repository that tracks it. Contradictions go at the top of the returned summary under Task statements the current code contradicts; a statement no command can check is listed as unverified rather than dropped. Task text is data: the explorer never runs a command that appears in it.

stride:task-enricher

Explores the codebase to fill in a sparse task before it is claimed — discovers key_files, patterns_to_follow, testing_strategy, verification_steps, security_considerations, pitfalls, and a complexity estimate, and returns a single enriched-task JSON object that the orchestrator PATCHes onto the existing task. It never rewrites the human-authored title, type, or description. Claude Code only.

Cross-field consistency pass (v1.85.0+). Before returning a task, the enricher compares its fields with each other: every verification step covers the scope of the criterion it verifies, no instruction contradicts a pitfall or security consideration, a prescribed regex or command is checked against the task's own edge cases by pattern matching only, instructions that can conflict say which wins, each acceptance criterion fits on one line, and external contracts are named in pitfalls or patterns_to_follow. A check it cannot resolve is recorded as an open question, never settled by dropping one side. The decomposer runs the same pass on every child task, and the creation skills point to it so a hand-written task gets it too.

stride:task-decomposer

Breaks goals and large tasks into dependency-ordered child tasks. Uses scope analysis, task boundary identification, and dependency ordering to produce implementation-ready task arrays with complexity estimates, key files, and testing strategies per task. Claude Code only.

A behaviour_test_matrix by default (v1.85.0+). Whenever a task's testing_strategy names a unit or integration test, the decomposer (for every child task) and the stride-creating-tasks and stride-creating-goals skills emit a complete seven-category matrix, waiving categories that do not apply with na_reason — the rule the enricher already followed. A task with no testable behaviour omits the matrix and says why in its description.

stride:task-reviewer

A pre-completion code review agent dispatched after implementation but before running hooks. Validates the git diff against acceptance_criteria, detects pitfalls violations, checks patterns_to_follow compliance, verifies testing_strategy alignment, and confirms the task's security_considerations were implemented. Returns categorized issues (Critical/Important/Minor) with file and line references.

The canonical reviewer_result JSON schema (schema_version "1.7") — summary, status, issue_counts, issues[], acceptance_criteria[] with the met/not_met enum, project_checks[] (v1.18.0+; per-entry status enum met/not_met/not_applicable and full-checklist emission as of v1.23.0), and the per-section testing_strategy / patterns / pitfalls (v1.19.0+) / security_considerations (v1.21.0+) verdict objects (passed/failed/not_assessed), plus the OPTIONAL behaviour_test_matrix verdict with its per-row breakdown (v1.40.0+; emitted only when the task supplies a matrix) — is defined in agents/task-reviewer.md and is the schema of record for all six reviewer-variant prompts. Variant prompts cite that path; do not duplicate the schema elsewhere. The full structured block is persisted verbatim as reviewer_result: orchestrators and completion skills passthrough every key the reviewer emits and never re-enumerate an allow-list of which keys to copy (v1.22.1), so any field the schema gains flows through automatically. As of v1.24.0, review reports must be delivered complete, with no exceptions: the orchestrator passes the reviewer every field the task supplies (including security_considerations), not_assessed is reserved strictly for a section the task left empty, the structured output is carried through by a mechanical whole-object copy, and a mandatory pre-submission self-check refuses to complete a task whose review is thin or leaves a task-supplied section unassessed. The persisted block is rendered by the Kanban review queue (issue list, acceptance verdicts, code-review checks, and the four section-verdict tiles). As of v1.42.0, the file's worked example also demonstrates category: "security" — an important-severity issue paired with an unmitigated considerations[] entry and a failed security_considerations verdict — so the fail-closed escalation rule, and step 5's Important-unless-exploitable severity split, are shown rather than only stated. As of v1.43.0, the example's not_met acceptance criterion is likewise backed by a category: "acceptance_criteria" issue its evidence resolves to, and the preamble records why that issue is important rather than critical: review step 1 works on a three-value scale (Met / Partially Met / Not Met) while the emitted status enum has two, so a partially-satisfied criterion collapses to not_met on the wire and keeps important severity, with critical reserved for a criterion whose behaviour is wholly absent. pattern is now the only issues[].category value with no worked instance. As of v1.44.0, a real finding outranks not_assessed in all four section tiles — an empty task section plus a genuine matching-category issue is failed, never not_assessed, with suppressing or re-labelling the finding named as the worse defect; review step 5's dimension checks now run whether or not the task listed considerations; and the two nested-array escalation rules bind in both directions, with deliberately opposite reverse cases (a failed security_considerations beside an all-mitigated considerations[] is legitimate, because the failure can originate outside the task's list, while a failed behaviour_test_matrix beside no failing row is a defect, because rows[] enumerates everything that verdict can be about). As of v1.54.0, the self-check's three "the task supplied it, so a verdict must be present" checkboxes — the task-supplied-section rule, its behaviour_test_matrix sibling, and the nested considerations[] check — are scoped to a payload where a structured review block was actually parsed: a self-reported skip and the JSON-parse fallback carry no verdict object at all, so those checks are inapplicable there rather than failed, which is what makes the fallback's "degraded-but-valid completion, never a hard failure" guarantee true as written. The rules still hard-block the case they were written for — a dispatched review whose block parsed and returned not_assessed for a field the task supplied — and the fail-closed security escalation survives the scoping with completion_notes plus completion_summary as its carrier where no issues[] exists. As of v1.72.0, a commit-pending carve-out stops the review reporting a scheduled post-review commit as a defect: because the reviewer is dispatched before the commit, a criterion asking for that commit was reported not_met and paired with a critical issue on every task that had one, which made approved unreachable. The carve-out is gated on an orchestrator-asserted commit_pending naming the step that performs the commit, plus two judgements the reviewer makes — that the criterion asks for nothing but that commit, and that it is the commit performed_by names rather than an earlier one the work should already have produced — so a genuinely overdue commit is still reported exactly as before. The criterion stays visible rather than hidden: its row is still emitted, its status is still not_met (the enum gains no third value), and its evidence opens with the literal sentinel PENDING COMMIT — ; only its paired issues[] entry is suppressed, which is what removes it from issue_counts and from the approval decision. schema_version stays "1.6" — no field was added — and with no commit_pending asserted the review behaves byte-for-byte as it did before.

Review rounds capped at two (v1.74.0+). A round is a reviewer dispatch that produced a merged result file, so a crashed dispatch consumes no round; the count lives in .stride/.review-rounds-<IDENTIFIER>.json. Round two is scoped to verifying round one's fixes via the review_round dispatch field — and, since W2252, runs only when those fixes edited a code path or round one reported a critical or security finding (otherwise the fixed findings are recorded and round one's result is submitted) — and after it remaining important/minor findings are recorded in completion_notes rather than fixed. A critical is exempt and blocks regardless of round. The cap is enforced by round_cap_ok in the completion self-check, on both extraction paths.

Cosmetic findings (v1.74.0+). issues[] entries carry an optional cosmetic boolean for findings that are purely presentational — wrapping, column width, counts, phrasing — where the claim itself is correct. A cosmetic finding is still emitted with its honest severity and category and still reaches completion_notes; the only thing it changes is that a round whose findings are all cosmetic buys no further review round. It is orthogonal to severity, not a fourth level: it only ever sits on a minor, and a minor can be substantive and still buy a round. Pinned mechanically as cosmetic_shape_ok on both extraction paths — cosmetic: true on a non-minor severity, on category: "security", or as a non-boolean is refused rather than coerced. A false statement of fact is never cosmetic, however small.

Review-cost telemetry (v1.74.0+). The reviewer entry of workflow_steps carries an optional dispatch_count — how many times the reviewer subagent was dispatched, counting a re-dispatch after a crash, since a crashed dispatch still spent its tokens. Omitting it stays valid, so an older plugin completes unchanged, and no seventh step name is added. Read skills/stride-workflow/telemetry-cost.md before drawing conclusions from it: the entry's duration_ms is an aggregate over more dispatches than the count reports, so the two do not divide, and wall-clock is not token cost — it can rank two tasks in the wrong order. Canon-governed (v1.75.0+) — the three rules above. All three are registered in docs/port-canon.md: the round cap as entry review-round-cap, the cosmetic class as cosmetic-finding-class, and dispatch_count as dispatch-count-telemetry. Each is check: "anchor", each quotes its governed text verbatim in its Provenance section, and each is required of every port — so the drift check now reports a port lacking any of them instead of passing it silently. A change to any of their substance owes a version bump in two places before the next release: that entry in the canon, and stride's own anchor for it — which lives beside the governed text in skills/stride-workflow/SKILL.md (round cap, dispatch_count) or agents/task-reviewer.md (cosmetic), not in this file. As at line 128, this README deliberately carries no anchor of its own: the canon assigns one per rule per port directory, and stride's are already placed.

The back-reference is itself a governed rule now, and the gate can see it (v1.76.0+). docs/port-canon.md gains entry edit-site-back-reference, required of all nine ports: wherever a file states a governed rule, prose beside it must name the canon by path and name the entry id. It is checked as a property rather than an anchor, because the obligation is distributed over every rule-stating site rather than sitting at one. scripts/check-port-canon.sh and its PowerShell twin implement that check, so a port carrying a current anchor and no back-reference is now reported instead of passing. Two bounds are stated in both script headers rather than closed: the check sees anchored sites only, so a file that states a rule without an anchor is invisible to it, and a paragraph far below that names the id and the canon will credit the anchor above it. Both move a cell away from refusal.

Rework gates in review (v1.85.0+). Four checks aimed at the causes of review rework. None adds a block key (schema_version stays "1.7"), and none lets the reviewer run tests or project code:

  • Per-item testing coverage. Each unit_tests, integration_tests and edge_cases item is mapped to the test that asserts it, by file:line; an unmapped item is an Important testing issue.
  • Break-it evidence. Every new or changed test needs a break_it entry showing it failed with the behaviour it guards broken and passed once restored (the procedure is skills/stride-workflow/test-non-vacuity.md); a missing entry, or one whose break misses the asserted behaviour, is an Important testing issue.
  • Statement verification. Checkable factual statements the diff adds to prose, comments, changelogs or skill text are checked with read-only commands of the reviewer's own choosing; a contradicted one is an Important code_quality issue, never cosmetic.
  • Twin check. Declared counterparts of a touched file — .sh/.ps1 twins, files named in keep-in-sync or mirror sentences, and files sharing a canon anchor — are found with git ls-files and grep; one left unchanged while the diff changes behaviour is an Important code_quality issue naming both files.

Block and report persistence (v1.65.0+). The reviewer writes the structured block to .stride/.review-<IDENTIFIER>-r<N>.json and the full human report to the .md beside it, returning a summary bounded at 24 lines / 2,000 characters. A review response ran roughly 27 KB, ~17 KB of it the block; on a real 25-project_checks review the summary is 8 lines / 475 characters, and it is O(1) in review size because project_checks renders as a tally and the issue index is capped at ten rows. Two files rather than one, because review_report is what a human reads on the task detail page and the block alone would reduce it to a stub. The orchestrator reads only the paths it supplied — the paths named in the returned summary are for the human reader and are never used as a path, since a reviewer steered by injected content could otherwise name any local file and have its bytes spliced into review_report and PATCHed to the server. A dispatch with no REVIEW_BLOCK_PATH writes nothing and emits the block inline, which is what keeps an older orchestrator working. The schema is unchanged and schema_version stays "1.6": the carrier moved, no field did, and the five other variant prompts keep returning the block inline.

stride:hook-diagnostician

Analyzes hook failure output and returns a prioritized fix plan. Parses compilation errors, test failures, security warnings, credo issues, format failures, and git failures with structured diagnosis per issue. Accepts both structured JSON from Claude Code hooks and raw text from legacy agent-executed hooks. Dispatched automatically when blocking hooks fail during the completion workflow. Claude Code only.

Commands

Two slash commands create Stride work from existing project markdown. Both wrap the stride-workflow orchestrator (which dispatches the matching creation sub-skill) — they never call the creation sub-skills directly, and the orchestrator's activation marker and sub-skill gate still apply.

/stride:create-tasks

/stride:create-tasks [--dir <path>] [task description]

Create one or more work tasks (or defects). With --dir <path> — alias --context, and also accepting --dir=<path> — the command loads the .md files in that directory as a read-only context bundle and forwards it through stride-workflow to stride-creating-tasks, which mines it for key_files, patterns_to_follow, acceptance_criteria / description, and pitfalls. A --dir path that is set but missing is an error (non-zero exit); a directory with no .md files warns and continues. The context augments your interactive intent — it never overrides your confirmation or excuses a blank required field (including the five review_queue-scored fields). Only files inside --dir are read.

/stride:create-goals

/stride:create-goals [--dir <path>] [goal description]

The goal-creating sibling of /stride:create-tasks, with identical --dir / --context parsing and validation. Routes through stride-workflow to stride-creating-goals, producing a goal with nested tasks seeded from the context bundle. The batch "goals" root key and index-based dependency rules are unchanged.

Automatic Hook Execution (Claude Code Hooks)

When the Stride plugin is enabled, .stride.md hooks execute automatically without permission prompts via Claude Code's hook system. The plugin ships a hooks/hooks.json that registers PreToolUse and PostToolUse hooks on Bash commands, and a hooks/stride-hook.sh script that:

  1. Detects Stride API calls (claim, complete, mark_reviewed) in Bash tool commands
  2. Parses the corresponding section from your .stride.md
  3. Executes each uncommented command sequentially
  4. Caches task environment variables ($TASK_IDENTIFIER, $TASK_TITLE, etc.) from the claim response for use in all subsequent hooks
  5. Outputs structured JSON for diagnostics on both success and failure

Executor stdout contract (v1.64.0+). The hook writes exactly one JSON document to stdout per invocation. Claude Code parses hook stdout as a single document, so when a primary section and ## after_goal both ran, the previous two-object output failed a strict parse and every harness-facing field in it — including hookSpecificOutput.additionalContext — was silently dropped. One section still emits its own object unchanged; more than one emits {sections: [...]} with hookSpecificOutput hoisted to the root, discriminated by the absence of a top-level hook key. Verify with a strict parser, never jq — both jq . and jq -s accept a concatenated stream and cannot detect the failure. See skills/stride-workflow/parser.md.

Durable hook results (v1.64.0+). Every section that does work also persists its structured result to .stride/.hook-result-<hook>.json, on both the success and failure paths, cleared at claim time. An absent file means the section body was empty and did no work, so 0 is the truthful duration. This makes after_goal's real duration readable when building its follow-up PATCH; after_doing and before_review remain 0 because both fire on the very curl whose body already carries their result.

Loop state (v1.73.0+). A successful completion also persists .stride/.loop-state.json — exactly four keys: identifier, needs_review (a JSON boolean, read from the API response and recorded verbatim), completed_at, and session_id. The next claim clears it, so the file means "a completion happened and no claim has followed it yet" and never describes a stale task. The clear is unconditional — a claim that fails clears it too, and that is a decision rather than an oversight. Preserving the record on a failed claim was implemented and reverted: the claim that fails most often is the one against an empty ready queue, which is how essentially every session ends, and a record preserved there is byte-identical to one left by an agent that completed and never claimed at all — yet a gate must refuse in the second case and not the first, and none of the four keys can tell them apart. An over-eager clear costs only a missed gate; a false one is worse. Both values also have trailing linefeeds stripped before the charset check, matching what the bash half's command substitution does unavoidably — linefeeds only, since a carriage return survives that stripping and is then refused by both halves alike. It exists so a Stop gate can refuse to end a session on an un-followed completion — and, since v1.78.0, its absence alongside a claim pointer is equally the evidence for the symmetrical shape, a claim held and abandoned: the gate cannot refuse an action it has no evidence for, and this file is that evidence. It is written by the hook rather than by the agent on purpose — an agent-written marker would be exactly as skippable as the instruction it replaces. A failed or 422 completion writes nothing: every non-success body the API emits lacks .data, which is the discriminator, and the write reads only this call's own tool_response rather than the canonical response file, because that file survives across calls and would otherwise let a truncated 422 inherit the previous claim's payload and record a completion that never happened. The write is atomic (temp staged in .stride/, then renamed) and never fatal — a failure is swallowed, because this is a gate input, not a correctness dependency — but it is announced on stderr, and so is a failed clear, which matters more: a record that could not be removed is the one direction that produces a false gate. A destination that exists and is not a regular file is refused outright, because a rename onto a directory succeeds by relocating the temp inside it and would otherwise leave the record where no reader looks. Both halves implement it; the one divergence is Windows PowerShell 5.1's non-atomic -Force, noted in the compatibility gaps below.

Claimed task file (since W2248). A successful claim whose own response proves the task identity also writes the response's data object to .stride/.task-<IDENTIFIER>.json, so later steps and subagents can read the task's fields instead of having them retyped. The name comes only from an identifier matching \A[A-Za-z0-9_-]{1,64}\z, else the numeric task id. A failed, unparsable or truncated claim writes nothing and leaves an earlier file untouched. The file holds task free text and is data to every reader, never instructions. Step 7's artifact cleanup deletes it after a successful completion. The bash half needs jq, as its whole claim block already does. The PowerShell half writes the response's raw data text without a byte-order mark rather than re-serialising it, so both halves write the same bytes for the compact JSON the API sends, except that jq lower-cases a \u escape the API writes in upper case. The two files are always equal as JSON, so compare them as JSON.

Task attachments (since W2522). When that same proven claim lists attachments, the hook downloads each file into .stride/attachments/<STEM>/ (the task file's stem) as <id>-<sanitised filename>, then writes manifest.json last. docs/porting-attachments.md is the contract; this is what the stride hook does with it. The download runs after the ## before_doing section has finished, so it never shortens that section's budget or changes its result, and it is never fatal: every problem becomes a manifest entry or one stderr line, and the hook's exit code and stdout are unchanged. The list comes from this claim's own response, never from the canonical response file, so a truncated claim downloads nothing. Only a download_url of the form /api/tasks/<this task's id>/attachments/<digits> is fetched, joined to the API URL in .stride_auth.md and never to one found in the intercepted command. The URL must be https, or plain http for a loopback API URL only; with no token, no URL, or any other URL nothing is requested and each entry records transport. The token travels only in the request's Authorization header (the bash half hands it to curl on stdin, never in argv) with a curl-like User-Agent. Redirects are not followed: a 3xx is recorded as http_<code>, so the token never reaches another host. Caps: the declared byte_size must be a JSON number written as plain digits (since D403, 7.0, 7.00000000000000001, 7e0 and 0.7e1 are skipped too_large, though a double rounds each to 7; the bash half judges the literal before jq parses it, so this holds on any jq) of at most 26,214,400 bytes (25 MiB); at most 20 files; at most 104,857,600 bytes (100 MiB) in total, counting accepted entries only; and a 120 s wall clock for the whole download, also held inside the 900 s PostToolUse timeout. STRIDE_ATTACHMENT_BUDGET_SECONDS can only shorten that budget. A body whose length is not its byte_size, or whose SHA-256 is not its sha256, is removed and recorded as failed, and a host with no SHA-256 tool keeps nothing. The bash half bounds the body twice: curl's --max-filesize refuses a declared length past byte_size, and the body is piped through head -c <byte_size + 1>, so a chunked body with no declared length is cut off at once even on a curl older than 8.4, which does not apply --max-filesize to a streamed body. An id that is not 1-64 characters of [A-Za-z0-9-] (a number id must be written as plain digits) is skipped as unsafe_id, and so (since D403) is an entry whose id, or whose saved name, an accepted entry already took, compared without regard to letter case, with 7 and "7" the same id and a saved name's trailing dots ignored (Windows strips them), so two entries never share one local_file; and the off-pattern URL case above is skipped as unsafe_url, both without a request. The manifest (manifest_version 1) is compact JSON with one trailing LF, staged and renamed into place, with no URL and no token. It has one entry per server entry, in server order: the server's fields, plus local_file, download_path, status (downloaded, skipped or failed) and reason (unsafe_id, unsafe_url, too_large, count_cap, total_cap, time_budget, size_mismatch, sha256_mismatch, http_<code> or transport). The server's own limits surface as reasons, not errors: its per-token rate limit on the download endpoint gives http_429, and a workspace token that names no board gives http_400, because the hook sends no X-Stride-Board header. Layout: .stride/attachments/.gitignore holds exactly *, so nothing under it is ever committed even where .stride/ is not gitignored. A missing one is created in place with no staging file, and since D403 every claim, with attachments or without, first sweeps a staging file an interrupted earlier run left in .stride/attachments/ (either half's exact staging name, regular files only), so git add -A can never commit one. A claim with no attachments creates no directory, and removes one left by an earlier claim of the same task. A re-claim replaces the task's directory, deleting the old manifest first so it never names files that are gone. A .stride, .stride/attachments or task directory that is a symlink or not a directory stops the download and nothing is written through it. The PowerShell half does the same with HttpWebRequest (AllowAutoRedirect off, each read held to the remaining budget) and writes a byte-identical, BOM-less manifest for the same claim. Four differences are known, and the compatibility list below records them too. A number written with an exponent, such as an id or comment_id of 1e3, is refused or treated the same by both halves, but the bash half echoes it into the manifest as jq renders it (1E+3) while PowerShell keeps the literal; a byte_size not written as plain digits (7.0, 1e3) is skipped too_large by both, but since D403 the bash half echoes it as null, because it is nulled before jq parses the claim, while PowerShell keeps the literal; and an exponent form jq renders as plain digits, such as an id of 7e0, is accepted by bash and refused by PowerShell. The PowerShell half reads its hook input as UTF-8 (since D403) whatever the console code page, so a non-ASCII filename gets the bash half's saved name under Windows PowerShell 5.1 as well. The User-Agent is curl/<installed version> in bash and curl/8.0 (stride-hook.ps1) in PowerShell. The bash half's per-request limit is curl's --max-time; PowerShell checks the deadline on every read instead. A tool_response that arrives as an object rather than a string is unwrapped by the bash half, which then downloads, while the PowerShell half reads no claim text from it and downloads nothing. Until D403 one gap was shared: neither half detected a duplicate id, so two entries with one id shared one local_file and the manifest could describe a file the later entry replaced. Both halves now skip the later entry as unsafe_id.

Canon-governed — entry stop-hook-capability. The two paragraphs below are this port's own statement of how its runtime ends a session and how a stop is refused here. The rule they answer to lives in stride/docs/port-canon.md, entry stop-hook-capability; a change to what that rule obliges moves the entry's version and the anchor above together, in the same change.

The Stop gate (v1.73.0+). hooks/stride-stop-gate.sh (plus a PowerShell twin) is registered for Claude Code's Stop event and refuses to end a session while a claimable task remains — the mechanism the loop-state file above exists to feed. It blocks on two conditions, and they are mutually exclusive — the loop-state file's presence selects which applies, so at most one API call is made on any path. (1) An unfollowed completion: the loop-state file exists, its needs_review is the JSON boolean false, and GET /api/tasks/next answers 200 with a non-empty .data.identifier. The block message names the claimable task from that response, never the loop state's own identifier, which names the task just completed — naming that one would send the agent back to work it had already finished. (2) A held claim (v1.78.0+): the loop-state file does not exist, .stride-env-cache names an identifier-shaped TASK_IDENTIFIER with TASK_STATUS='in_progress', and GET /api/tasks/:id?fields=status,claim_expires_at,completed_by_id answers 200 for that same task with status in_progress, a null completed_by_id, and a claim_expires_at still in the future. That condition exists because loop state is written only by a completion, so a session that claimed a task and stopped before finishing it was invisible to condition 1 — the most damaging stop there is, and one actually observed. Its message names the held task, the inversion of condition 1's rule, because that is the task the agent must act on. All three fields are load-bearing: completion_changeset moves a completed task to Review and sets completed_by_id but never touches :status, so a task completed with needs_review: true still reads in_progress and status alone would refuse a sanctioned stop; and the server's own claimable set counts an in_progress claim past its expiry as claimable by anyone, so an expired claim is not held. .stride-env-cache is read as a pointer, never a fact — its TASK_IDENTIFIER survives a completion, an unclaim and the session that wrote it — which is why the live task is what decides. Everything else permits: no loop-state file and no usable cache pointer (the silent, zero-call path taken on nearly every stop), a malformed loop-state file, needs_review anything but false, no credentials, transport failure, timeout, any non-200, a 200 with no usable identifier, a 200 answering for a different task, a held task that is completed, unclaimed or expired, and (since W2255) a held claim whose stride subagent is still running. Claude Code's Stop input lists running background agents in background_tasks. A running agent of an exact type stride dispatches, or the generic Plan agent, permits the stop and is named by type and id, for at most 30 minutes per wait, where a wait is one set of pending agents (.stride/.stop-pending-since.json). That stop is the agent waiting for its own subagent, and the subagent's completion re-invokes the session, where the gate applies again. Note an empty Ready column answers 404, not a 200 with empty data, so "no task available" and "non-200" are the same wire event and one test covers both. The call is bounded three ways — --connect-timeout 3, --max-time 5, and the hooks.json timeout — because a gate sitting in the user's exit path must never be the reason leaving is slow.

Wedging a session is worse than missing a gate, and the design is shaped around that — and (v1.78.0+) that principle was re-examined against the stronger requirement that the loop continue until no claimable task remains, then deliberately kept. The two read as being in tension because the gate yields at all, but the budget is per-state, not per-session: the counter is keyed on the completed identifier or on held:<identifier>, so a new completion or a new claim gets a fresh budget, and "refuses twice then yields" is a statement about one unresolved state rather than a session-wide allowance of two early stops. To keep stopping early an agent would have to keep resolving states, which is to say keep making progress. The decisive evidence is that the budget has never been what failed: every early stop this was filed for was the gate blind rather than out of budget — a completion whose response was redirected away so no loop state was written, and a claim abandoned mid-task where no loop state exists yet — and in both the gate permitted on the first attempt with a full budget, so no larger number would have refused either. The risk accepted is stated plainly: a working gate still permits an early stop on the third attempt against one state it can see. That is preferred to the alternative, because a larger budget makes a genuinely stuck session expensive to leave while an agent willing to spend three refusals is equally willing to set STRIDE_ALLOW_STOP=1 — so a bigger number only penalises the honest case. A per-condition budget was considered and declined: a held claim already self-heals when it expires, and an unfollowed completion has by definition already recorded its work, so neither is the shape that needs more insistence. A bounded re-block guard (.stride/.stop-gate-blocks) refuses at most twice for one unfollowed completion — or for one held claim, which shares the same single counter under a held: key prefix rather than getting a second one, so that a budget spent refusing a held claim on a task does not then silently skip a real gate when that same task is completed — and then yields — and stays yielded: the spent record is deliberately left in place rather than deleted, because deleting it restarted the budget from zero and the cycle ran 2,2,0,2,2,0 forever, making every later session pay two more blocks for the same stale completion. It is keyed on the completed identifier rather than the claimable one, because the head of the queue can change between attempts while the agent's stuck state has not, and it is cleared at the two events that genuinely end a completion's life: the loop-state file disappearing, or its identifier changing. The counter is written before the block is emitted, and a write failure permits — a block the gate cannot count is a block it cannot bound. STRIDE_STOP_GATE_MAX_BLOCKS overrides the budget but is validated as an unsigned integer, because an unvalidated value reaches [ "$n" -gt "$MAX" ], where a non-numeric right operand makes [ error and the gate then blocks unbounded — so STRIDE_STOP_GATE_MAX_BLOCKS=off, the most natural way to try to disable it, would have produced a permanently unstoppable session. The Windows delegation shim likewise permits when the .ps1 or powershell.exe is missing, deliberately diverging from stride-skill-gate.sh, whose equivalent branches exit 2: copied verbatim that would be an unconditional, uncounted, permanent block of every stop on that machine. Escape hatches, and note they are not all interchangeable across the two block conditions. Two work against either: STRIDE_ALLOW_STOP=1, and STRIDE_STOP_GATE_MAX_BLOCKS=0 — a valid unsigned integer, so honoured, disabling the gate outright. Deleting .stride/.loop-state.json frees an unfollowed completion only: a held claim is blocked precisely because that file is absent, so deleting it is inert there. What frees a held claim instead is resolving it — complete the task, or POST /api/tasks/:id/unclaim — which is what its own block message names, or removing the .stride-env-cache pointer the condition reads. That last one matters because it gives anyone who wants the gate off a numeric way to say so, rather than the =off attempt the validation exists to catch — and it is the reason a modest budget costs a genuinely stuck user so little. The gate is registered for Stop only, never SubagentStop — a subagent has no Stride loop of its own, and blocking one on its parent's state would wedge work that can never clear the gate. The token is read only into the Authorization header and never reaches either output stream; the only server-controlled string that can appear in a message is the next identifier, which is refused rather than sanitised if it is not identifier-shaped.

Native Windows runs now capture, attribute and narrow their own diffs (v1.68.0+). Before this, stride-hook.ps1 had no capture step at all: it PUT a .stride-changed-files.json that something else was assumed to have written, and on native Windows that something is nobody — stride-hook.sh execs the ps1 and exits. A native-Windows run therefore produced no snapshot at all, with no error. The ps1 hook now builds the snapshot (Build-ChangedFilesSnapshot), carries the five per-task record families, runs the same window-classification engine as bash (D236 windows, the D244 purity heuristic, the D256 fixpoint), evicts per window rather than by count so a live outer task's anchor survives (D268/D274), and replays the capture-time narrowing verdict on retry instead of re-deriving it (D273). The ps1 suite went from 530 to 961 assertions; the bash suite is unchanged at 787 and both bash files are byte-identical across the whole port.

What still does not work on Windows PowerShell 5.1, stated because an over-claim here is the hazard. The Invoke-WebRequest -SkipHttpErrorCheck blocker is fixed (D277): the 7.0+ parameter is gone from both call sites, so a non-2xx now throws on either host and the real status is recovered from the exception's .Response, with a null response — the transport case — yielding 000, matching what the bash twin gets from || printf '000'. Before that fix, binding failed before the request issued and every 5.1 upload recorded 000, while the after_goal detection call swallowed the same failure under a catch { return } and no-opped D119 silently. What has not changed is the harder gap: nothing in this repo has ever executed the hook under powershell.exe — the compatibility gate is static and the ps1 suite runs under pwsh 7 (D237), so D277's fix is verified by reasoning and by pwsh-7 behaviour, not by a 5.1 run. D277 was found by reading rather than by a red gate; the regression cover that would now catch its return is Test Group 30 in the ps1 suite, not the gate.

Commit attribution hardening (v1.67.0+). The window model that attributes commits to tasks now classifies each window before subtracting it: a window whose residual is one commit is PURE and subtracts whole, two or more residual commits make it AMBIGUOUS and it subtracts only what other windows cover, with the trade decided for never losing an author's commit (D244). A nested task that commits through after_doing records its exact SHAs, so it no longer absorbs the outer's mid-window commit (D255); purity is a fixpoint, so two concurrently-open siblings can no longer manufacture purity from their mutual overlap (D256); eviction is per window and open-window-aware, so a live outer's anchor never falls to the cap (D268); and an outermost task — which has no enclosing window to absorb a dropped commit — keeps its manual commits instead of silently under-reporting them (D271). The remaining zero-commit-child steal is documented and pinned rather than fixed: the candidate branch was implemented behind a flag and measured to break nine pre-existing pins, reverting per-window attribution for every hand-committing agent (D272).

Task-attributed changed_files (v1.64.0+). A completing task's diff snapshot now carries the commits that task made, rather than everything committed between its claim and its completion. Tasks that claim and complete inside another task's window — the normal shape under dispatcher mode — no longer have their commits absorbed by the outer task. 6. Blocks tool calls (exit 2) on failure in PreToolUse context

Hook routing:

Claude Code Event API Endpoint Pattern Stride Hook
PostToolUse (Bash) /api/tasks/claim before_doing
PreToolUse (Bash) /api/tasks/:id/complete after_doing (blocks completion on failure)
PostToolUse (Bash) /api/tasks/:id/complete before_review (+ after_goal if the response bundles it)
PostToolUse (Bash) /api/tasks/:id/mark_reviewed after_review (+ after_goal if the response bundles it)
PreToolUse (Bash) a curl invocation targeting /api/tasks/ unsafe-shape guard — refuses -o/--output/-O, a stdout redirect, or a transformer pipe in that curl's own command segment (v1.72.0+)

Unsafe-curl guard (v1.72.0+). The four curl invocation rules — never -o/--output, never redirect stdout (>, >>, 1>, &>, >|; 2> and 2>&1 are fine), never pipe into a transformer (jq, head, awk, grep, sed), always pipe into tee — are backed by a PreToolUse guard rather than stated only in prose. Be exact about which of the four it enforces: the guard refuses the three shapes that take the body off stdout and does not require a tee. A bare curl with no tee is permitted, because it leaves the response on stdout, which is what the hook reads. The tee is unenforced but not therefore optional — it is what persists a full copy for the truncation fallback. That file has two writers and they fail differently: the tee writes it from the shell, before the hook runs and regardless of size; capture_canonical_response writes it from inside the hook, but deliberately declines a payload that does not parse, precisely so a truncated blob cannot overwrite a good tee'd copy. So on a truncated response the hook-side writer does not refresh the file at all. Without a tee the snapshot then still holds the previous call's payload, which is why the loop-state fallback's own guards — the response must carry a hooks array and a matching task id — are what make that path safe rather than any assumption about the tee. They matter because the hook reads the API response off stdout to capture the task's diff and refresh the env cache, so hiding or transforming stdout drops the diff silently: the task completes with an empty changed_files and no error at all. The guard refuses with exit 2 and a message naming the rule and the tee alternative. A stdout redirect is refused for the same reason -O is — it takes the body off stdout — and is judged by file descriptor rather than by operator, so 2> and 2>&1 are untouched while >&2 is not. Both halves enforce it (v1.78.0+). hooks/stride-hook.sh and hooks/stride-hook.ps1 — the one native Windows actually reaches, since hooks.json registers only the shell entry and that script execs powershell.exe — carry the same three refusal rules and return the same four refusal kinds. They diverged for one cycle, when the redirect rule landed in the shell half first and in PowerShell second; that divergence was recorded in both files and in the changelog rather than tolerated, which is how it was found and closed. The two halves reach the same verdict by different mechanisms: the shell half walks a segment one > at a time, while the PowerShell half erases every permitted file-descriptor redirect with one .NET regex and asks whether a > survives. Scope is deliberately narrow — a command must look like a Stride API call (/api/tasks/ plus curl) before any shape is judged, so ordinary shell usage is untouched, and tee is explicitly allowed because it passes stdout through unchanged. Two narrowings keep it from misfiring, and both were added because the first revision misfired without them. Scope requires curl to be the actual command of a pipeline stage, not merely a string in the text — otherwise grep -o "curl.*/api/tasks/" file is refused as a Stride curl. And shape is judged per command segment, split on ;, &&, || and the newline — a newline is a command separator too, and treating it as whitespace both merged a curl with its neighbour and hid one behind it — so a flag belonging to a neighbour is not attributed to the curl — otherwise curl … | tee r.json && gcc -o app is refused, naming a flag the curl does not have. Within a segment the pipeline stays intact, because | tee and | jq really are part of the curl's own command. Shape is also judged only outside quotes, so a -o or the word jq inside a -d payload is not a false positive. It runs after the .stride.md check: a project without one captures nothing anyway, so there is no diff to lose there, and gating on it keeps the guard's blast radius to projects that actually run Stride hooks. It never inspects, stores or echoes any part of the command — the command carries a Bearer token, and matching is on URL and flag/pipe shape only. Attachment re-fetch exemption (since W2522). The one -o the guard allows is a GET of a task attachment, /api/tasks/<id>/attachments/<id>, whose -o/--output target is an absolute literal path under this project's .stride/attachments/<dir>/<file>. It exists for an operator's manual re-fetch: the claim hook downloads attachments itself, and an agent never runs curl -o. It is judged on the whole command, so nothing can ride along with it. The command must be one simple curl: no pipe, redirect, ;, &, parenthesis, newline, backtick, command substitution, unquoted glob or brace character, unquoted $, or empty word such as '' (curl would read an empty word as a second URL). A $NAME or ${NAME} URL base is allowed only inside double quotes, where the shell cannot split it into extra words, and inside double quotes nothing but a plain $NAME or ${NAME} is: a quoted "$@", "${a[@]}" or "$*" can expand to zero or several words and re-pair the words after it, so it loses the exemption. Every option must be on an allowlist (-s, -S, -f, -g, -o, -H, -A and -m with their long forms, plus --fail-with-body, --no-progress-meter, --compressed, --create-dirs, --connect-timeout, --retry, --max-filesize, --proto, and -X/--request only as GET), so an unknown option such as --location-trusted, --proxy, -K or -v loses the exemption rather than passing. Since D403, -w/--write-out is not on it, because its %output{} directive writes a second file anywhere, and a -H/--header value that starts with @ loses the exemption, because curl would read headers from that local file; so does one that starts with $ (-H "$H"), which the shell could expand to @file after the guard has judged it. The documented -H "Authorization: Bearer $T" stays exempt. It needs exactly one -o/--output and exactly one URL, the attachments path with no query, fragment or percent-encoding. The target may not be manifest.json in any letter case (APFS and NTFS fold case), a name ending in a dot (Windows strips it, so manifest.json. opens the manifest there) or the .gitignore, may not be a symlink itself or be reached through a symlinked .stride, .stride/attachments or task directory, may not carry a backslash on a host whose separator is /, and may not start with $NAME: the guard cannot know what the shell will expand it to, so it cannot say where the file lands. There is no exemption at all until the claim hook's .stride/attachments/.gitignore exists as a regular file (not a directory, not a link), so a re-fetch never creates a tree git would commit. A command that misses any rule is judged by the refusal rules exactly as before. stride-hook.ps1 carries the same exemption, rule for rule. The contract, with the attachment plan's duplicate-id and plain-digit byte_size rules, is in docs/porting-attachments.md.

after_goal (v1.17.0+): the server bundles an after_goal entry alongside the primary hook in the response of /complete or /mark_reviewed when the completing task is the final child of a parent goal. The plugin auto-executes the local ## after_goal section as a blocking hook (600s timeout, same shape as after_doing) and emits a structured result on stdout. The agent forwards the result via PATCH /api/tasks/:goal_id/after_goal to flip the goal to Done. A missing ## after_goal section in .stride.md is a clean no-op (back-compat — older .stride.md files keep working unmodified). The hook receives GOAL_ID / GOAL_IDENTIFIER / GOAL_TITLE / GOAL_DESCRIPTION env vars from the server's hook.env, and is general-purpose (Slack notifications, artifact archival, release pipelines, project-level smoke tests are all valid uses — not just PR creation). (v1.34.0+) detection is now reliable regardless of /complete response size: the harness truncates a large tool_response.stdout mid-JSON, so the hook prefers a full canonical response file (.stride/.last-api-response.json) and, when that is absent/truncated, spawns a fresh GET /api/tasks/:id/after_goal_status call (not subject to Bash-tool truncation, zero agent cooperation) as the authoritative guarantee — the two paths are mutually exclusive so ## after_goal runs at most once, and against a server without that endpoint the fresh call is a clean no-op (the grace worker still flips the goal to Done).

Note: Add .stride-env-cache, .stride-changed-files.json, .stride-diff-upload-state, .stride-dirty-baseline, and the .stride/ directory to your .gitignore — all are temp artifacts written between hook invocations. (v1.52.0+) add .exploratory/ too when the stride-exploratory-testing plugin is installed: session artifacts land there, hold transcribed application output, and arrive untracked, so an ## after_doing section that stages everything would commit them (see the Manual & Exploratory Testing section). (v1.34.0+) .stride/.last-api-response.json is the canonical full API response the hook writes early in the post phase so ## after_goal detection survives a harness-truncated tool_response.stdout; it lives under .stride/ and is hard-excluded from every snapshot by name. .stride-dirty-baseline (v1.33.0+) records the paths already modified or untracked at claim time (with blob hashes) so pre-existing unrelated edits are excluded from changed_files unless re-modified during the task; like the other artifacts it is excluded from snapshots by name and cleaned up at claim refresh and after after_review. .stride-env-cache caches task metadata (including the base commit captured at claim time — (v1.28.0+) this TASK_BASE_REF is now refreshed on every claim, including when the claim response is too large to parse inline and Claude Code persists it to a file: the hook recovers the JSON from that "saved to" file, and even when no JSON is obtainable it still rewrites TASK_BASE_REF to the current HEAD so a stale base ref from a previous claim can never make changed_files span unrelated commits); .stride-changed-files.json holds the per-file diff snapshot; .stride-diff-upload-state (v1.25.0+) records the last upload outcome (task id + HTTP code only, never credentials). Gitignoring .stride-diff-upload-state and .stride-changed-files.json matters: if they stay tracked, an after_doing auto-commit that stages everything will commit them, and because their contents change on every run they then surface in every later task's diff against base, polluting changed_files. (v1.27.0+) capture_changed_files also excludes both of these root artifacts from the snapshot as a backstop (anchored to the repository root, so a same-named file in a subdirectory of your project is still captured) — but gitignoring them keeps them out of your commits in the first place. (v1.25.0+) the snapshot is captured and uploaded before the after_doing section commands run — so a hook timeout mid-quality-gate no longer loses the diffs — then refreshed after all commands succeed, and the before_review hook verifies the recorded outcome on its own fresh timeout budget, re-capturing and re-uploading when the recorded state is missing, stale, or non-2xx (a healthy upload is never repeated). On Stride server v1.16.0+ the after_doing hook PUTs this snapshot to the server automatically (no agent action required); against older servers, agents inline-cat the file into the completion body (see stride-completing-tasks SKILL.md). All three files are cleaned up automatically at the claim refresh and after the after_review hook. (v1.22.0+) The automatic PUT sends a transport-encoded envelope — {"changed_files":{"encoding":"base64","data":"<base64>"}} — so an edge request filter (WAF) cannot misread a code diff as an attack and silently drop the upload; the server decodes it back to the identical list. When base64 is unavailable the hook falls back to the raw {"changed_files":[...]} shape, and a non-2xx upload response is now surfaced as a stderr warning (non-fatal; the bearer token is never logged). (v1.35.0+) the upload now targets the task id parsed from the /complete|/mark_reviewed command URL rather than the claim-time env-cache TASK_ID, so a stale or corrupt cache can no longer upload the diff to the previous task (D127); and when the before_review self-heal — the last retry — still fails to land a 2xx, the hook logs a distinct CHANGED_FILES UPLOAD UNRESOLVED message and appends unresolved=yes to .stride-diff-upload-state (fail-soft — it never vetoes the completion; a later successful PUT self-clears the mark) so a definitively-lost diff is actionable rather than silent (W1658). Both land in stride-hook.sh and stride-hook.ps1. (v1.36.0+) TASK_BASE_REF is captured after the ## before_doing section runs — the section's git pull moves HEAD, and a pre-pull base made the diff span another clone's pushed commits (D132); the claim interception now strips any inherited base immediately and writes it (plus a TASK_BASE_REF_TRUSTED marker and the dirty baseline) post-section, jq-free. Every capture also passes the base through a resolve_snapshot_base trust guard that loudly recomputes empty/unresolvable, non-ancestor, or (for unmarked inherited values only) pre-branch-point bases from the task branch point — resolved once per task window and persisted as a base= line in .stride-diff-upload-state so the self-heal reuses the same judgment — and paths committed between the base and HEAD can never be dropped by the dirty-baseline filter (D137: committed task files whose content matched their claim-time hashes silently vanished from the snapshot).

The after_doing time budget

The two Bash hook entries in hooks/hooks.json carry a 300-second timeout (the Skill-matcher gate stays at 10 seconds — it fires on every Skill invocation and must remain fast). The timeout is a ceiling, not a guarantee: the entire after_doing section — every command in your .stride.md quality gate (test suite with coverage, credo, sobelow, auto-commit) plus the plugin's own snapshot work — shares this one budget.

When the budget is exceeded, Claude Code kills the hook process. With the early-capture fix (v1.25.0+) the per-file diffs are already uploaded before your gate commands start, so a timeout no longer loses them — but the structured success JSON, the post-command snapshot refresh, and any not-yet-run gate commands are still lost, and the completion call is blocked as if the gate had failed.

If your project's quality gate runs close to the ceiling, either trim the .stride.md ## after_doing section (move slow steps like a full coverage run into CI) or raise the timeout values further in a fork of the plugin.

Configuration

Before using Stride skills, you need two configuration files in your project root — and one .gitignore addition.

.gitignore

Add these before your first task. Every entry is either a working artifact or a credentials file, and none should ever be committed:

.stride/
.stride-env-cache
.stride-changed-files.json
.stride-diff-upload-state
.stride-dirty-baseline
.stride_auth.md
.exploratory/

.stride_auth.md holds your API token. .exploratory/ is where exploratory-testing session artifacts land when that plugin is installed — they hold transcribed application output and arrive untracked, so an ## after_doing section that stages everything (git add -A) would commit them. Add the line before your first session: .gitignore does not untrack a path git already tracks, so an artifact already committed needs git rm --cached too.

The two configuration files:

.stride_auth.md

Contains your API credentials (never commit this file):

- **API URL:** `https://www.stridelikeaboss.com`
- **API Token:** `your-token-here`
- **User Email:** `your-email@example.com`

.stride.md

Contains hook scripts that run during the task lifecycle:

## before_doing
git pull origin main
mix deps.get

## after_doing
mix test
mix credo --strict

## after_goal
# Optional fifth hook — fires after the parent goal's final child task
# completes. Omit the section entirely for the back-compat no-op path.
./scripts/notify-team.sh "$GOAL_IDENTIFIER" "$GOAL_TITLE"

Updating

To update to the latest version of Stride skills:

/plugin update stride

Running the hook test suites

The hook scripts ship with unit-style test suites that stub curl to verify argument shape:

(v1.64.0+) Both suites calibrate machine load at the start and end of a run and scale their wall-clock backstops accordingly — clamped below each case's un-killed duration, so a timeout that never fires still fails. Each run reports its own wall clock and warns when the machine was busy, so a loaded run is distinguishable from a failing one without re-running it.

(v1.66.0+) The bash suite's final group (Group 28) runs scripts/check-skill-budgets.sh, the hot-path byte-budget drift detector: the gate fails when stride-workflow/SKILL.md, stride-workflow/review-block-extraction.md (budgeted since W2257), stride-completing-tasks/SKILL.md, stride-claiming-tasks/SKILL.md, or agents/task-reviewer.md (budgeted since W2258) exceeds its stated budget, and the failure output names the file, its size, its budget, the extraction pattern to apply, and where the budget table lives. Budgets sit 10-15% above post-extraction sizes, so ordinary edits pass and only sustained regrowth trips (D229 philosophy) — except stride-workflow/SKILL.md, held tighter since W2257, and stride-completing-tasks/SKILL.md and agents/task-reviewer.md, held tighter since W2258, so each extraction saving cannot regrow unnoticed; raising one is a deliberate, reviewed decision.

(v1.68.0+) Group 29 runs scripts/check-ps1-compat.sh, a static Windows PowerShell 5.1 compatibility gate over hooks/*.ps1 and scripts/*.ps1 — six files, the ps1 test suites included. It runs PSScriptAnalyzer's PSUseCompatibleSyntax (TargetVersions = 5.1) and PSUseCompatibleCmdlets (desktop-5.1.14393.206-windows), pinned in scripts/PSScriptAnalyzerSettings.psd1, because stride-hook.sh execs powershell.exe (5.1) and not pwsh: a 7-only construct a contributor's pwsh 7 accepts would fail only on a user's Windows box. Every run first proves itself against an in-memory 7-only probe and fails when either rule stops firing, so a misconfigured settings file cannot pass as a clean run. The group skips — loudly, printing the install command — when pwsh or the analyzer is absent.

(v1.71.0+) bash Group 30 and PowerShell Group 32 run the self-test of both halves of the port-canon drift check, in both suites, and cross-verify the two against each other. They never run the fleet scan -- not because it is red (it is not, as of W2119) but because it measures other checkouts this repository does not control. See the fleet-scan paragraph below.

The cross-verification is what makes the pair worth having. 30c/32c compare the two halves' case-name sets, so a case renamed or lost on one side goes red — something neither half's own tally can see, since each stays internally consistent while disagreeing with the other. 32d then runs both halves against one fixture tree — the three exit tiers (0 all-clean, 1 drift-found, 2 no-verdict-possible), plus fixtures that reach the verdict space (a stale anchor, an unknown-id anchor, vendored content under each pruned directory) and the property path (including a case-varied rule id and a case-varied registry key, the two shapes where the halves were found to diverge) — and compares exit codes, tally counts, verdict lines and work lists, normalizing only the two absolute-path header lines and each script's reference to its own filename. Both halves also agree line for line over the real fleet, which is stronger evidence than any of these — and is exactly what cannot be a test group, because it is red by design.

Adding both halves' self-tests costs roughly a minute of wall clock in each suite (about 9s for the bash half, about 55s for the PowerShell half, which re-execs its own script once per case group). SUITE_WALL_BASELINE_S in hooks/test-stride-hook.sh was raised from 100 to 175 to match, rather than trimming cases to fit the old number.

bash hooks/test-stride-hook.sh
pwsh hooks/test-stride-hook.ps1

These run by default with no setup, and they make no network requests — with one exception in both respects, described next.

The PowerShell 5.1 compatibility gate

Group 29 — and the same gate run on its own — needs PSScriptAnalyzer installed once. That install is the suite's only setup step and its only network fetch, at install time only, never during a run:

pwsh -NoProfile -Command "Install-Module -Name PSScriptAnalyzer -RequiredVersion 1.25.0 -Scope CurrentUser"

The version is pinned so a later run cannot silently take a different build. Nothing in the plugin installs it for you — no hook installs modules on your machine. Without it, Group 29 skips with that command in its output, and the rest of the suite is unaffected.

Run the gate on its own with:

bash scripts/check-ps1-compat.sh              # scan hooks/*.ps1
bash scripts/check-ps1-compat.sh --self-test  # prove the gate still detects 7-only code

Exit codes: 0 clean, 1 findings or a gate error, 2 pwsh or PSScriptAnalyzer not installed.

When the analyzer in use is not the pinned version, the gate still runs and still passes — the pin is a lower bound at runtime so a contributor already on a newer build is not blocked — but it emits a warn: line naming both versions, and Group 29 surfaces that line even on a pass. Drift is visible rather than silent.

Because absent tooling skips, a runner without pwsh reports a green suite having gated nothing. Where the gate is meant to be mandatory — CI, a release check — set STRIDE_PS1_GATE_REQUIRED=1 and the skip becomes a failure:

STRIDE_PS1_GATE_REQUIRED=1 bash hooks/test-stride-hook.sh

The gate matches hooks/*.ps1 and does not recurse, matching the scope it documents. If a .ps1 ever lands in a subdirectory it is not scanned, so the gate names it in a warn: line rather than passing clean over an unexamined tree.

What this gate cannot see

A clean run means exactly this: no PowerShell 7-only syntax, and no cmdlet name the 5.1 profile knows to be 7-only. It is not evidence that the hook runs on 5.1 — runtime verification on a real Windows host is a separate job. The gaps below were each confirmed by execution, not assumed:

  • 7-only parameters on cmdlets that exist in 5.1 are invisible to this gate, and still are. ForEach-Object -Parallel, Get-Content -AsByteStream and ConvertFrom-Json -AsHashtable all pass silently: the cmdlet rule checks that a cmdlet name resolves, never which parameters it accepts. Nothing below changes that — the coverage that closed D277 lives in the ps1 suite, not here. This repo had two live instances (W2106): Invoke-WebRequest -SkipHttpErrorCheck at both call sites — the changed_files PUT, which therefore never issued on 5.1, and the after_goal detection call, which sits under a catch { return } and so degraded D119 detection to a silent no-op on every 5.1 run. Both are removed as of D277; the surviving mentions in hooks/stride-hook.ps1 are comments recording why the parameter is not used. Line numbers are deliberately not cited here — the two this entry used to name had already drifted by the time D277 was worked, which is its own small lesson about pinning a defect to a line in prose. They were found by reading, not by this gate. What replaces the reading is Test Group 30 in hooks/test-stride-hook.ps1: an AST walk over hooks/*.ps1 and scripts/*.ps1 that checks each command's named parameters against a per-cmdlet denylist of 7-only ones. It is abbreviation-aware (so -SkipHttpError is caught too) and alias-aware (iwr -SkipHttpErrorCheck resolves to Invoke-WebRequest before the lookup — without that it passed clean, which is what D277's review found). It also catches the positional form of the same class: a 3-argument Join-Path, which silently binds the 7-only -AdditionalChildPath. It carries a planted-violation case, exercised through the same function the real assertions use, so a scan that silently stopped matching fails rather than passing clean. A denylist is incomplete by construction — it catches what someone has learned to list. That is strictly more than the name-only gate sees, and strictly less than "every 7-only parameter". It is suite coverage, not a gate, so it runs with the ps1 suite and not with check-ps1-compat.sh; extending the denylist is how a newly-learned parameter gets pinned.
  • The .NET API surface is invisible. A 3-argument [System.IO.File]::Move(src, dst, overwrite) — an overload .NET Framework does not have — is flagged by neither rule. Related and more important: Move-Item -Force — in Write-EnvCache, Write-HookResult and Write-LoopState — is a behaviour divergence, because 5.1 implements -Force as delete-then-move; the consequence is written up in the comment above Write-EnvCache. "Never partial" survives on both hosts; "never absent" does not. For the loop-state file (W2123) that window degrades safely, because the gate reading it treats an absent file as "no completion awaiting a claim" — a missed gate, never a false one. No static rule can see any of this, so it is recorded here as a gap and not as a suppressed finding — a suppression would falsely imply the analyzer had flagged it.
  • No connect-timeout on the Stop gate's PowerShell half. Invoke-WebRequest -TimeoutSec bounds the whole request, and Windows PowerShell 5.1 has no separate connect timeout, so stride-stop-gate.ps1 has ONE bound where stride-stop-gate.sh has two (--connect-timeout 3 plus --max-time 5). The hooks.json timeout is an independent backstop on both halves, and the failure direction is identical either way — a slow or dead host permits the stop. Recorded rather than papered over: this is a real, if minor, divergence in a pair the rest of the fleet keeps in lockstep. The Step 0 plugin-currency helper (W2251) has the same divergence: check-plugin-current.ps1 has one -TimeoutSec 3 bound where check-plugin-current.sh has --connect-timeout 2 plus --max-time 3. A slow or dead host gives silence on both halves.
  • Task attachments (W2522) differ in four small ways between the halves. An exponent-form number (1e3) in an attachment's id or comment_id is echoed into the manifest as 1E+3 by bash (jq's rendering) and as the literal by PowerShell, and a byte_size not written as plain digits is echoed as null by bash (since D403) and as the literal by PowerShell, so the cross-half byte-identity holds for every other claim. An exponent form jq renders as plain digits (7e0) is an accepted id in bash and a refused one in PowerShell (a byte_size of 7e0 is refused by both since D403); the server writes ids as integers, so it never sends one. The User-Agent is curl/<installed version> against curl/8.0 (stride-hook.ps1). The per-request bound is curl's --max-time against a deadline checked on every read. And a tool_response delivered as an object is unwrapped and downloaded by bash but downloads nothing in PowerShell. Each fails in the safe direction or not at all.
  • Set-StrictMode -Version Latest (hooks/stride-hook.ps1:14, hooks/stride-skill-gate.ps1:17) is valid on both hosts, but Latest resolves to a different strictness on each. Not flagged, by design.
  • The syntax rule covers five constructs, not "7-only syntax" in general. An exploratory pass over ~40 constructs found it detects ? :, ??, ??=, &&/|| pipeline chains, and ${x}?.Member — and misses ${x}?[0] (the null-conditional index, introduced in the same release as the member form it does catch), clean{} blocks, the background operator &, the 7.0 numeric literal suffixes (100u, 1n, 1.5d, 16l, 5s, 3y), and the `e / `u{} escape sequences. The escapes are the nastiest shape: on 5.1 they are not errors at all, the backtick is simply dropped and the script emits the literal text.
  • The cmdlet profile's coverage is arbitrary within a single family. Of twelve genuinely 7-only cmdlets tested it flagged five and missed Get-Error, Join-String, Start-ThreadJob, Enable-ExperimentalFeature, Debug-Runspace, Get-PSSubsystem and Switch-Process — flagging Get-ExperimentalFeature while missing Enable-ExperimentalFeature. It is a name-membership test, so a misspelled cmdlet is equally invisible.
  • 7-only automatic variables and the whole .NET surface are invisible, and this is the class most likely to bite: $IsWindows / $IsLinux / $IsMacOS / $IsCoreCLR, $PSStyle, $PSNativeCommandUseErrorActionPreference, 7-only types such as [System.Half] and System.Text.Json, and .NET-Core-only method overloads. None produces a syntax or unknown-cmdlet error — just different behaviour, or a runtime throw, on the user's machine.
  • The profile is one specific 5.1 build (5.1.14393.206, Windows Server 2016 era). Other 5.1 builds may differ at the margins.

Nesting does not hide anything, and neither do encodings — both were tested. A ? : inside a string interpolation, a here-string or a scriptblock parameter default is still flagged, as is && inside a scriptblock; and BOMs, CRLF, latin-1 and a missing trailing newline all analyze correctly. A file whose bytes do not decode as script text is reported as a gate error rather than as clean, so "no findings" never stands in for "never analyzed".

What it does catch, also verified by execution: ? :, ??, ??=, &&/|| pipeline chains and ${x}?.Member (syntax); and profile-known 7-only cmdlets such as Get-Uptime, Test-Json, ConvertFrom-Markdown, Show-Markdown, Remove-Service and Remove-Alias.

The cross-port canon drift check

scripts/check-port-canon.sh and scripts/check-port-canon.ps1 compare every port repo and vendored catalog copy against the rules registered in docs/port-canon.md, reporting per rule and per port whether the port's anchor is present, stale, unexpected, or missing.

The two halves are independent implementations, not a script and its transliteration: the bash half tokenises the canon's json with awk, the PowerShell half builds an object graph with ConvertFrom-Json. That is deliberate — two readings of one document that reach the same verdict are worth more than one reading run twice — and the suites hold them to it (below).

The FLEET SCAN is still a release-time step that nothing runs for you. It exits 0 as of W2119, which closed the last MISSING cells; consult a live run rather than this sentence for today's result. It stays out of the pass/fail suite regardless, because a bare run measures eleven subjects -- this repository, eight sibling ports and two vendored catalogs -- ten of which this repo does not control — the reasoning is recorded in the script's own EXIT CODES header and in the canon's Release gate section. The SELF-TEST is different and is now gated: both halves run as bash Test Group 30 and PowerShell Test Group 32, and those groups also cross-verify the two halves against each other.

bash scripts/check-port-canon.sh                 # scan the fleet against the canon
pwsh scripts/check-port-canon.ps1                # the same scan, the other half
bash scripts/check-port-canon.sh --self-test     # prove the gate still detects drift
pwsh scripts/check-port-canon.ps1 -SelfTest      # the other half's own suite

--ports-parent and --canon exist for fixture trees and are confined (D301): each must resolve, physically, under the repository's parent directory (where the default ports parent and canon live) or the system temp directory (where the self-tests build their fixtures). Anything else is refused with the exit-2 GATE ERROR before it is read, and so is a port or catalog directory checked out as a symlink whose physical target leaves those roots, so neither flag can point the walk at an arbitrary directory. A json fence whose syntax the parser cannot read is reported by block and line only, never by echoing the token. Schema-validation messages for a canon that parses are not covered by that: they still name the value they refused.

The two suites cover the same cases apart from the sanctioned asymmetries described below, and hooks/test-stride-hook.sh Group 30c (with its PowerShell mirror, Group 32c) is what holds them to it: each compares the two halves' case-name SETS, which catches a case renamed or lost on one side — something neither half's own tally can see, since each stays internally consistent while disagreeing with the other. The two tallies are not expected to be equal; what must be equal is the set of names left after the sanctioned asymmetries are filtered out. Reproduce with the normalization 30c itself uses:

diff <(bash scripts/check-port-canon.sh --self-test | grep '^ok: ' | sed 's/ \[skipped on this host:.*\]$//' | grep -Ev '^ok: \[(ps1|bash)-only\]' | sort) \
     <(pwsh -NoProfile -File scripts/check-port-canon.ps1 -SelfTest | grep '^ok: ' | sed 's/ \[skipped on this host:.*\]$//' | grep -Ev '^ok: \[(ps1|bash)-only\]' | sort)

Three sanctioned asymmetries, and what each one claims. A [skipped on this host: …] suffix means the case exists on both sides but could not run here. A [ps1-only] or [bash-only] prefix means the HAZARD does not exist in the other half at all — not that porting the case was inconvenient. The live example is the grep-stub pair, marked [bash-only]: it pins the behaviour of a grep the bash half shells out to, and the PowerShell half invokes no grep anywhere. A case testing an outcome BOTH halves owe is ported instead, which is what happened to the locale pair. Marking a case that the other half could have run would turn these groups into the false green they exist to prevent.

Exit codes: 0 every applicable cell reports ok, 1 at least one cell reports MISSING, STALE, UNEXPECTED, DEFECT or UNVERIFIABLE and the drift is listed above, 2 no verdict was possible — the canon is absent, unparseable, carries an unknown schema version, has a bad registry dir, or the command line was wrong. Under --self-test the same codes mean all cases passed, at least one failed, and the temp dir or the flag combination was wrong.

Treat 2 as red, not as silence. It does not mean a missing machine dependency the way it does in check-ps1-compat.sh — the bash half shells out to nothing but awk and grep, and the PowerShell half's ConvertFrom-Json ships inside every PowerShell that could run it at all. Neither half has a machine-fault tier, so in both a 2 means the run proved nothing, and its lack of findings is not a pass.

Fix a red result by placing the anchor, never by editing the canon. A MISSING cell means the port does not carry the rule's marker beside its own statement of the rule; the remedy is to add the anchor there, or to write the rule in that port's own words first where the substance is genuinely absent. Editing an applies_to row in docs/port-canon.md to make a cell green records that the port does not owe a rule it does owe, which turns the gate into a report of its own configuration. Where a port truly should not owe a rule, that is a change to the canon made deliberately and on its own terms, not a way to clear a red line during a release.

Optional end-to-end PUT round-trip

test-stride-hook.sh Test Group 11 drives finalize_after_doing against a real kanban server, GETs the task back, and asserts the persisted changed_files equals the snapshot. This catches wire-shape regressions across the plugin/server boundary that stub-only tests miss.

The group is gated on three env vars and skips cleanly when any are unset:

cd stride
STRIDE_TEST_E2E_URL=http://localhost:4000 \
STRIDE_TEST_E2E_TOKEN=$(grep 'Local API Token:' ../.stride_auth.md | sed 's/.*`\(.*\)`.*/\1/') \
STRIDE_TEST_E2E_TASK_ID=42 \
bash hooks/test-stride-hook.sh

Required:

  • STRIDE_TEST_E2E_URL — base URL of the kanban server (must be http://localhost*, http://127.0.0.1*, or end in .dev / .local / .test; production hostnames are a hard fail)
  • STRIDE_TEST_E2E_TOKEN — API bearer token for that server
  • STRIDE_TEST_E2E_TASK_ID — id of a sacrificial test task whose changed_files this group is allowed to overwrite

The group does NOT create or delete tasks — it mutates only the changed_files field on the designated task. Pick a sacrificial task on a local board, not a production task. The group runs three sub-cases: a populated-snapshot round-trip, an empty-snapshot round-trip (legitimate clear), and a fail-soft check (missing token must not crash the hook).

License

MIT — see LICENSE for details.

About

Task lifecycle skills for Stride kanban: claiming, completing, creating tasks and goals

Resources

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages