{ "markdown": "\"Trigpoint:\n\n# Trigpoint\n\n**Your agent's plan was accurate the day it was written. It has not been accurate since.**\n\nTrigpoint is a Claude Code plugin that turns a codebase into a plan of record which cannot quietly\ngo out of date.\n\n---\n\n## A week with an ordinary plan\n\n**Monday.** You ask an agent to plan the work. It reads the repository and produces something\ngenuinely good: 40 tasks across 6 tracks, dependencies mapped, a summary table at the top.\n\n**Tuesday.** You finish three tasks. Two others turn out to have been done months ago. One of them\nuncovers four more that nobody knew existed.\n\n**Friday.** The table at the top still says **0 of 40 done**. Nobody updated it, because updating\nit was nobody's job. The four discovered tasks live in a chat window that has since been closed.\n\n**Next Monday.** A fresh session opens the plan and believes the table. It schedules work that is\nalready finished, and it has never heard of the four tasks that turned out to matter most.\n\nThe plan did not fail because it was wrong. It failed because it **stopped being true**, and\nnothing announced that it had.\n\n---\n\n## Why plans rot\n\nThree causes, none of which are fixed by trying harder.\n\n**Counts are typed by hand.** A header that reads \"12 of 40\" is one person's memory of the\ncheckboxes below it. It is correct on the day it is written and wrong soon after. The fix is not\nmore discipline. The fix is to stop typing it.\n\n**\"Done\" is a claim, not a fact.** A ticked box asserts that something happened. It carries no\nevidence that it did. An agent in a hurry ticks the box it believes is finished, and belief is not\nthe same as having run the command and read the output.\n\n**Discovered work has nowhere to land.** The most valuable thing a week of implementation produces\nis the work nobody predicted. It gets mentioned in conversation, and it dies when the session ends.\n\n---\n\n## What Trigpoint does about it\n\n**Nobody types a number.** The summary table is regenerated from the task lists themselves. A\ncount cannot disagree with the tasks it counts, because it is derived from them. Add the two-line\nregenerate-and-diff step to your CI, as this repository does, and the build fails on any\ndifference, so drift stops being discouraged and starts being impossible. Trigpoint does not write\nthat step into your workflow for you; until you add it, the guarantee is only as good as running\n`/trigpoint-sync`.\n\n**A tick requires evidence.** A ticked task must carry the command that was run, or, when no\ncommand can re-check the work, a record of what happened. There is no exemption for obvious tasks,\nand no setting to turn it off, because the moment there is one an agent decides what counts as\nobvious. Six months later you can see not only that\nsomething was done, but how anyone knew.\n\n**The rules live in your repository.** They are written into your `CLAUDE.md` as plain markdown, so\nevery future session picks them up automatically, and a colleague who has never installed this\nplugin still gets them.\n\n**The questions come after the evidence.** Trigpoint audits the code before it asks you anything,\nso the options it offers are drawn from what is actually there. A plan built from a README is a\nplan built from a claim.\n\n---\n\n## What you get\n\n- **Numbers you can trust.** Generated, never typed.\n- **Progress you can believe.** Every completed task carries proof.\n- **A plan that survives context resets.** It lives in the repository, not in a chat window.\n- **Questions grounded in your real code**, not in what the documentation claims.\n- **Something to scan as well as read.** A generated dashboard alongside the markdown.\n\n---\n\n## When to reach for it\n\n- **You have inherited a codebase** and need to know what is real before promising anything.\n- **A project has gone dormant** and you cannot tell what still works, what half-shipped, and what\n should simply be deleted.\n- **An agent wrote you a plan** and a week later you no longer trust it.\n- **The work will span many sessions**, so whatever holds the plan has to outlive any one of them.\n- **Several people or agents are working in parallel** and you need one place that says what is\n actually done.\n\nIt is a poor fit for a small change you can hold in your head, or for a greenfield project with no\nexisting code to audit. It earns its keep where there is more truth to establish than you can keep\nin working memory.\n\n---\n\n## What a run produces\n\nThree linked artefacts. The examples below are not mock-ups: they are this repository's own\n`ROADMAP.md`, which Trigpoint's rules govern and whose gate runs against it in CI.\n\n**1. The ledger,** `ROADMAP.md` at the repository root. Tracks, dependencies, every task as a\ncheckbox, the hand-off contracts, and a falsifiable definition of done. A ticked task carries the\ncommand that was run and the date it was proven, or, for work no command can re-check, a record of\nwhat happened:\n\n```markdown\n- [x] **1.2** Write ledger validation: a ticked task with no `**Verified:**` line is an error, a\n duplicate task id is an error, an unknown `**Blocked by:**` reference is a warning\n **Verified:** `python3 -m unittest tests.test_ledger_validate -v`. 2026-08-26\n\n- [x] **5.2** Publish the plugin to a marketplace and verify a real install from outside this\n checkout\n **Recorded:** Published to `felipeflorencio/claude-plugins`; `claude plugin update\n trigpoint` reported 0.1.0 to 0.2.0 on a machine outside this checkout. 2026-08-27\n```\n\n`**Verified:**` names a command, is re-run at the end of every working turn, and unticks its box\nwhen the command stops passing. `**Recorded:**` names something that happened, and is never re-run\nor unticked by machine. The second exists so that nobody has to invent a command for work that has\nnone: a proxy that passes whether or not the claim is true is worse than an honest record.\n\n**2. The progress table,** generated in place inside that same ledger, between a pair of markers.\nNobody types these numbers. This is the current table from this repository, verbatim:\n\n```markdown\n\n| Track | Scope | Tasks | Done | Blocked by |\n| --- | --- | --- | --- | --- |\n| **T1 Parser and gate** | The ledger model, its validation rules, and the read-only CI gate built on them | 6 | 6 | nothing |\n| **T2 Generation** | The generated progress table, the dashboard renderer, and the sync CLI that writes both | 4 | 4 | T1 |\n| **T3 Installation** | The CLAUDE.md instruction block installer | 3 | 3 | T1 |\n| **T4 Packaging** | The plugin and marketplace manifests, the slash commands, and the skill with its references and templates | 4 | 4 | T1, T2, T3 |\n| **T5 Publication** | The README, the cover art, the published marketplace listing, and a verified real install | 2 | 2 | T4 |\n| **T6 Continuous verification** | The hooks that state the plan at session start and re-prove it at the end of a turn, the approval gate that keeps command execution safe, and the parser fix that made the re-run trustworthy | 18 | 16 | nothing |\n| **Total** | | 37 | 35 | |\n\n```\n\n**3. The dashboard,** `roadmap-dashboard.html`, generated from the same parse in the same pass, so\nit is structurally incapable of disagreeing with the table above. Plus a design spec recording why\nthe plan is shaped the way it is.\n\nSee [`examples/README.md`](examples/README.md) for what to look at in each.\n\n---\n\n## Install\n\nBoth routes below were run on 2026-08-26 and both succeeded.\n\nThe shared marketplace, which lists this plugin and any later ones:\n\n```\n/plugin marketplace add felipeflorencio/claude-plugins\n/plugin install trigpoint@felipeflorencio\n```\n\nOr directly from this repository, which carries its own single-entry marketplace manifest:\n\n```\n/plugin marketplace add felipeflorencio/trigpoint\n/plugin install trigpoint@trigpoint\n```\n\nVerified with the `claude plugin` CLI, which takes the same arguments as the slash commands:\n\n```\n$ claude plugin marketplace add felipeflorencio/claude-plugins\nSuccessfully added marketplace: felipeflorencio (declared in user settings)\n\n$ claude plugin install trigpoint@felipeflorencio\nSuccessfully installed plugin: trigpoint@felipeflorencio (scope: user)\n```\n\n### Other agents\n\nThe skills, the scripts and the ledger format have nothing Claude-specific in them, so the same\nplugin ships a manifest for several harnesses. Each is generated from\n`.claude-plugin/plugin.json`, and CI fails if one drifts.\n\n| Harness | Manifest |\n| --- | --- |\n| Claude Code | `.claude-plugin/plugin.json` |\n| Codex | `.codex-plugin/plugin.json` |\n| Cursor | `.cursor-plugin/plugin.json` |\n| Gemini CLI | `gemini-extension.json`, with `AGENTS.md` as the context file |\n| Anything reading `AGENTS.md` | `AGENTS.md` at the repository root |\n\n**Only the Claude Code route has been installed and run end to end.** The others are manifests\nbuilt to each harness's published shape and are unverified until someone installs one, which is\nworth knowing before you rely on them.\n\n### Requirements\n\nPython 3.9 or later, standard library only. Nothing to `pip install`. macOS and Linux already\nhave it.\n\nOn Windows the hooks run through `hooks/run-hook.cmd`, a polyglot wrapper that finds `py -3`,\n`python3` or `python`. If none of them exist it exits quietly, so the session works exactly as\nbefore, just without the ledger state and the re-run. The technique is borrowed from\n[obra/superpowers](https://github.com/obra/superpowers), which uses the same trick to find bash.\n\n---\n\n## Usage\n\n| Command | What it does |\n| --- | --- |\n| `/trigpoint` | Runs the whole thing from the beginning: light pass, audit, premise check, the question ladder, design sections, then emits the three artefacts. Any argument is your stated goal for the work. |\n| `/trigpoint-sync` | Regenerates the progress table and the dashboard from the ledger. Reports what applied and what did not, separately and verbatim. |\n| `/trigpoint-verify` | Re-runs the commands recorded in `**Verified:**` lines and unticks anything that stopped passing. Each distinct command is approved once before it will ever run. |\n| `/trigpoint-pause` | Stops Trigpoint acting in this repository: both hooks fall silent and `/trigpoint-verify` refuses to re-run anything, so nothing edits the ledger until you undo it with `rm .trigpoint/paused`. |\n\nA whole run has **seven interaction touchpoints**, and after the last one the skill never asks\nagain on that project. \"Blocks\" means it stops and waits, because only you hold that fact and\nguessing it would build the plan on an invented premise.\n\n| # | What | If you say nothing |\n| --- | --- | --- |\n| - | The premise check. A statement, not a question. | - |\n| 1 | Which audit lanes, pre-ticked with reasons drawn from your repo | Runs all seven |\n| 2 | How do you run what you already have deployed? | Blocks |\n| 3 | What is this work actually aiming at? | Blocks |\n| 4 | Half-built areas: deleted, flagged off, or finished? | Blocks |\n| 5 | What access do I have, and can I verify the result myself? | Blocks |\n| 6 | Section-by-section approval of the design | Blocks |\n| 7 | Automatic updates, unless you say otherwise | Automatic |\n\nSilence on question 1 runs all seven audit lanes. Over-cover, never under-cover: a lane skipped by\nsilence is exactly the gap that later reads as clean. The ledger names which lanes ran and which\ndid not, so an absent lane never passes for a clean one.\n\n---\n\n## Watch it refuse\n\nBoth transcripts below show a ledger with two deliberate faults in it, as an installed\nproject would run the gate. This repository's own gate runs from `scripts/`, and passes.\n\n**A hand-edited count does not survive.** The `Total` row was edited by hand from `19 | 17` to\n`24 | 22` on a scratch copy, then the generator was run:\n\n```\n$ grep -n \"Total\" ROADMAP.md\n27:| **Total** | | 24 | 22 | |\n\n$ python3 .trigpoint/build_dashboard.py --ledger ROADMAP.md --output roadmap-dashboard.html\napplied: progress table\napplied: dashboard html -> roadmap-dashboard.html\n\n$ grep -n \"Total\" ROADMAP.md\n27:| **Total** | | 19 | 17 | |\n```\n\nCI closes the loop: the workflow regenerates both files and runs `git diff --exit-code`, so a\ncommitted count that disagrees with the tasks fails the build.\n\n**A tick without evidence does not pass.** Two ticked tasks, one with no evidence at all and one\nwhose evidence is still an unfilled template:\n\n```markdown\n- [x] **1.1** Wire the export endpoint\n- [x] **1.2** Add the retry budget\n **Verified:** {{ command and output }}\n```\n\n```\n$ python3 .trigpoint/check_drift.py ROADMAP.md; echo \"exit code: $?\"\nROADMAP.md: 2 task(s) in 1 track(s) and 0 definition-of-done criteria; 2 ticked, 1 carrying evidence; 2 checkbox line(s) read, 0 not claimed as either.\nERROR ROADMAP.md:8 task 1.1 is ticked with nothing behind it. Add a **Verified:** line naming the command that was run, or a **Recorded:** line stating what happened and when, or untick it.\nERROR ROADMAP.md:9 task 1.2 is ticked but its evidence line still contains an unfilled {{ placeholder }}. Record the command that was actually run, or what actually happened, or untick it.\n2 error(s), 0 warning(s) in ROADMAP.md\nexit code: 1\n```\n\n**The gate states what it read, and refuses to pass a file it read nothing from.** Exit codes are\n`0` clean, `1` at least one error, `2` the ledger or the install cannot be read, and `3` nothing\nwas checked. Exit 3 is the one\nworth knowing about: point the gate at a ROADMAP.md that has never been converted and you get a\ndiagnostic rather than a green tick.\n\n**Already have a ROADMAP.md?** The most common reason a real one parses as zero tasks is a missing\n`**Scope:**` line. A section becomes a track only by carrying one directly under its heading, so a\ndocument with correct `## T1 - Foundation` headings and correct `- [x] **0.1** text` task lines\nstill reads as empty without it. The gate says so specifically rather than leaving you to guess.\n\n```\n$ python3 .trigpoint/check_drift.py PLANS.md; echo \"exit code: $?\"\nPLANS.md: 0 task(s) in 0 track(s) and 0 definition-of-done criteria; 0 ticked, 0 carrying evidence; 33 checkbox line(s) read, 33 not claimed as either.\nPLANS.md: no tasks parsed although 33 checkbox line(s) are present. Either this file is not a Trigpoint ledger, or the parser has stopped recognising it. A section becomes a track by carrying a **Scope:** line, and a task line reads `- [ ] **1.1** text`. NOTHING WAS CHECKED; this is not a pass.\nexit code: 3\n```\n\n---\n\n## The worked example\n\nThe method comes from one real run against a dormant two-part codebase. The audit put **248\nfindings** in front of the verification gate; **15** came out CONFIRMED, 3 were sharpened and 1 was\nrefuted. Only a confirmed finding became a task. The plan that resulted was **67 tasks across 8\ntracks**.\n\n---\n\n## Limits\n\n- **It does not replace static analysis.** It establishes ground truth for planning. It is not a\n linter and it is not a type checker; run those too.\n- **It is version 0.3.0.** The ledger, the drift gate and the verifier are covered by a test\n suite CI runs on every push; `python3 -m unittest discover -s tests` reports the count, which is\n why this sentence does not. A number here that nothing re-reads is exactly the decoration this\n tool stopped keeping in its own evidence lines, and it had already been wrong twice. The plan it hands you is a strong first draft to argue with, not a verdict.\n\n---\n\n## What is in here\n\n| Path | What it is |\n| --- | --- |\n| `skills/trigpoint/SKILL.md` | The process: audit, then the question ladder, then emit |\n| `skills/trigpoint/references/` | The seven audit lanes, the four questions, the evidence rules, the parse contract |\n| `scripts/trigpoint_ledger.py` | Parses a ledger's tracks, tasks and definition of done. No filesystem access |\n| `scripts/trigpoint_render.py` | Renders the parsed ledger into the progress table and the dashboard HTML |\n| `scripts/build_dashboard.py` | Regenerates the progress table in place and writes the dashboard |\n| `scripts/check_drift.py` | The read-only CI gate over the same parse |\n| `scripts/trigpoint_verify.py` | Re-runs the commands the ledger records and unticks what stopped passing. Never ticks |\n| `hooks/` | The session-start and end-of-turn hooks, and the guard that keeps both silent in any repository that never opted in |\n| `scripts/install_block.py` | Installs the delimited block into a target repository's `CLAUDE.md` |\n| `commands/` | The four slash commands: `/trigpoint`, `/trigpoint-sync`, `/trigpoint-verify`, `/trigpoint-pause` |\n| `ROADMAP.md` | This repository's own ledger, kept under its own rules |\n| `assets/cover.html` | The source of the cover image, version-controlled rather than a loose binary |\n\nRun the checks locally with `python3 -m unittest discover -s tests` and\n`python3 scripts/check_drift.py ROADMAP.md`.\n", "bytes": 16925, "sha": "1526d543877fe35301bec66697dfe8048ada4da08762dd5d159187c4f54ab8a0", "repo_slug": "felipeflorencio/trigpoint", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_felipeflorencio_trigpoint_37f92bd1/readme" }