docs: add Try-it-yourself runnable demo to every user story#60
Merged
Conversation
closes user-stories-runnable-demos Stories 01–08 described behaviors with prose and static examples but never gave the reader a sequence of shell commands they could copy-paste against a fresh repo to see the behavior. Each story now ends with a `## Try it yourself` section — a self-contained ~10-line demo (mkdir tmp + git init + write TASKS.md + run a few `tasks` / `tasks-lint` commands + cleanup) that lets a new reader verify the story's claims in roughly 60 seconds. Eight demos: - 01: `tasks init` scaffolds TASKS.md + the AGENTS.md Task Management section, then `tasks-lint` confirms the file is spec-valid. - 02: write one rich + one bare task; `tasks pick` reports `Candidates: 2`, showing both shapes are valid but the rich one is what the agent actually picks up. - 03: queue with P0 + P1; first `tasks pick` returns the P0, then rewrite TASKS.md without the completed task and `tasks pick` returns the P1 — the read-only twin of `/next-task`'s loop. - 04: blocked-by chain — `tasks pick` returns the schema task with `Unblocks: 1` and `Candidates: 1`, proving the dependent task was filtered out. - 05: monorepo with `packages/api/TASKS.md` + `packages/web/TASKS.md`; `tasks list --tag backend|frontend` carves out per-agent queues without explicit config; `tasks-lint packages/*/TASKS.md` validates both files together. - 06: every provider lives behind `tasks sync <provider>`; the demo walks `--help` for github / jira / linear and lists the real invocation lines (auth-gated, so no live network call). - 07: queue with blocked + claimed tasks; `tasks stats` reports Blocked/Claimed/Available; `tasks list --unclaimed --unblocked` filters down; commit + edit + `tasks diff` shows +1 added. - 08: empty `**Research**` value fails lint with a specific error; populate it + add `**Last-enriched**: YYYY-MM-DD` and lint passes. Each demo was verified against the local CLI (`node packages/cli/ dist/cli.js`, `node packages/lint/dist/cli.js`) before committing — every command exits cleanly and prints the expected output. Verified: npm run build, npm test (402 tests), npm run lint, npx -y @tasks-md/lint TASKS.md — all clean. --- _🤖 Written by an agent, not Fyodor. Ping me if this looks off._
7 tasks
fyodoriv
added a commit
that referenced
this pull request
May 3, 2026
Story 08 introduces standing audit loops alongside `**Blocked**`, `**Research**`, `**Last-enriched**`, `**Parent**`, and policies, but only describes the pattern in passing — readers had no worked walkthrough to model their own usage on. Add story 09 with one full cycle, mirroring the Try-it-yourself shape PR #60 established for every other story. Sections: 1. **When to reach for one** — recurring queue refill, scheduled audit cadence, post-deploy checklist, onboarding-friendly audits. 2. **The shape** — canonical TASKS.md block with `**Tags**: standing-loop, audit, queue` + the `standing-audit-gap-loop` ID. 3. **How agents pick it up** — `pickBestTask` skips `standing-loop` tasks during automatic walks; `/next-task standing-audit-gap-loop` targets it on demand. Cross-references the parser, CLI, and MCP tests that pin the contract. 4. **The agent's audit pass** — five-step rule lifted from `spec.md`, with a sample commit message that closes the loop. 5. **Anti-pattern** — don't promote every recurring task to a standing loop. Symptoms + the "one loop per repo" rule of thumb. The runnable demo creates a temp directory, drops one normal task and one standing-loop task into TASKS.md, and shows `tasks pick` returning `Candidates: 1` (the standing-loop task is filtered out) while `tasks list --priority P2` returns both rows. Demo executed locally and the expected highlights match what `tasks pick` actually prints. Cross-links: - `docs/user-stories/README.md` table — new row 9. - `docs/user-stories/08-rich-task-metadata.md` — closing line of the Standing Audit Loops section now points to story 09 for the worked example. - `spec.md` standing-audit-loops section — adds the one-line "See User Story 09 for a worked example" cross-link the task asked for, no other spec changes. Verification: `npm run build`, `npm test` (415/415), `npm run lint`, `npx -y @tasks-md/lint TASKS.md` all pass; the runnable demo was executed end-to-end and produced the documented output. closes user-stories-09-standing-loops-walkthrough
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why this is needed
Closes
user-stories-runnable-demos(P1 hardening from PR #58).Stories 01–08 described behaviors with prose and static examples but never gave the reader a sequence of shell commands they could copy-paste against a fresh repo to see the behavior. Hardening means making every claim verifiable — a reader who landed on a story should be able to confirm the claim in their own shell, not just trust the prose.
Summary
Each story now ends with a
## Try it yourselfsection — a self-contained ~10-line demo (mkdir tmp+git init+ writeTASKS.md+ run a fewtasks/tasks-lintcommands + cleanup) that lets a new reader verify the story's claims in roughly 60 seconds.tasks initscaffoldsTASKS.md+ the AGENTS.md Task Management section,tasks-lintconfirms it is spec-validtasks pickreportsCandidates: 2, showing both shapes are valid/next-tasklooppickreturns the schema task withUnblocks: 1andCandidates: 1, proving the dependent task was filtered outpackages/api/TASKS.md+packages/web/TASKS.md;tasks list --tag backend|frontendcarves out per-agent queues without explicit configtasks sync --helpplus per-provider help; real invocation lines listed but auth-gated so no network calltasks stats,tasks list --unclaimed --unblocked, commit + edit +tasks diffshows +1 added**Research**value fails lint; populate it + add**Last-enriched**: YYYY-MM-DDand lint passesVerification
Every demo was run end-to-end against the local CLI (
node packages/cli/dist/cli.js,node packages/lint/dist/cli.js) before committing — each command exits cleanly and prints the expected output. The TASKS.md examples embedded in each demo are also spec-valid (per the acceptance criterion).Test plan
🤖 Written by an agent, not Fyodor. Ping me if this looks off.