Repository navigation
feat: release PAACM 3.0.0, the Verified Single-Writer Loop - #2
Merged
Merged
Conversation
Survey of agentic-coding methodologies, agent architectures, verification and evaluation research, and the current extension mechanisms of Claude Code 2.1.299 and Cursor 3.24, compiled from public sources on 2026-10-14. Includes a comparison matrix of 53 approaches, ranked practices to adopt and avoid, and the five evidence notes the topic files condense.
ALGORITHM.md is the normative specification of the Verified Single-Writer Loop: phases and gates, routes, roles, autonomy levels, escalation and the BLOCKED protocol, delegation, verification ladder, state artifacts, intake of supporting data, and the mapping onto Claude Code and Cursor. Fifteen decision records tie each major choice to the study.
src/content/ holds every piece of kit content once. The generator renders it into the plugin for both IDEs (plugins/paacm/), the Claude Code and Cursor marketplace manifests, and the project-install payload, with a --check mode that fails on drift. Validators check skills, subagents, Cursor rules, hook files, manifests, the project configuration and the check manifest against the formats both IDEs document.
The always-on AGENTS.md block holds only the non-negotiable rules. The paacm skill implements the algorithm on demand: one reference per phase, plus autonomy, escalation and the BLOCKED protocol, delegation and the brief, context hygiene, security, debugging and the runtime command reference, with templates for every task file. paacm-verify produces executed evidence before completion; paacm-review reviews someone else's change through the fresh-context reviewer. Default project configuration and check manifest included; ALGORITHM.md task state gains baseCommit, lastGate and blocked.
Adds the CLAUDE.md adapter, the explorer, implementer and reviewer subagents, the hooks (session start, protect, shell guard, post-edit checks, stop gate) and permission profiles for autonomy levels L0-L3. The hooks share the project runtime introduced here: task state, the protected-path audit, the gate and the check runner (paacm.mjs). The runner closes standard input for every check and validates the whole manifest before running anything, which fixes 2.0.0 defects D1 and D2, and reports PASS or FAIL per check with a summary (D3). Cursor-safe subagent variants are derived from the same files.
Adds Cursor hooks (session start, protect on Write and Delete, shell guard on beforeShellExecution, post-edit checks, stop gate with followup_message), all fail-closed where they enforce, and terminal allowlists per autonomy level for .cursor/permissions.json. The generator now emits the plugin both IDEs install from plugins/paacm/ and the two marketplace manifests: Cursor-safe subagents (model: inherit), an always-applied Cursor rule generated from the AGENTS.md block, and core rules the session-start hook gives Claude Code. The stop gate fingerprints the working tree so one stop event delivered twice (Cursor's import of Claude Code hooks) never runs the checks twice or counts one failure twice. Both manifests pass claude plugin validate --strict.
init, upgrade and uninstall plan every change before writing and write nothing when any path conflicts. Files the kit does not own are never overwritten: AGENTS.md and CLAUDE.md get a marked block, and .claude/settings.json, .cursor/hooks.json and .cursor/permissions.json get only the kit's entries merged in, with a record of exactly what was added so that uninstall removes only that. .agent/paacm.lock.json keeps the hashes of installed files; upgrade updates untouched files, restores missing ones and keeps the ones you changed. Writes never follow symbolic links, and a target inside the kit is refused (D5). Installed files get normal permissions (D7). --cursor-user installs the plugin into Cursor's local plugin folder. upgrade --from-v2 migrates a PAACM 2.0.0 project by comparing each file with the exact 2.0.0 content: unchanged files are replaced, changed ones kept and reported, and a kept check manifest loses only the 2.0.0 check of the scripts that the migration removes. doctor reports install health, schema validity of installed skills, agents and hooks, and the check configuration. detect proposes check commands from package.json, Makefile, pyproject.toml, Cargo.toml and go.mod, and writes them only with --write. check runs the manifest through the same runner the agent uses.
The paacm skill gets references/mcp.md: when a server is worth adding, the record to keep for each one (pinned version, need, data read, actions, credential scope), and templates for Claude Code's .mcp.json and Cursor's .cursor/mcp.json, which share a shape but expand environment variables differently. The agent proposes the entries and the human adds them, because both files start programs and are protected configuration.
scripts/agent-check and scripts/install-to-project.sh are superseded by paacm check and paacm init, upgrade and uninstall. The 2.0.0 payload at the repository root (.agent workflows, policies, templates, state, integrations and evaluation schema, the v2 skill and Cursor command) is superseded by src/content and the generated plugin, and the smoke workflow that tested only the two scripts is removed. The root AGENTS.md and CLAUDE.md now instruct agents working on the kit itself, and .agent/checks.conf holds the kit's own checks (validate, build drift, whitespace), which paacm check runs. docs/guide/upgrading-from-2.md explains paacm upgrade --from-v2 and where each PAACM 2 file and command went.
paacm eval grade grades a finished trial checkout without relying on the agent's account: it reads the diff from the start commit before running anything, runs the hidden acceptance tests (three times by default, flagging flaky ones) and the regression suite, detects modified or deleted test and CI files, and measures scope against the reference solution. Runs are appended to .agent/evals/runs/runs.jsonl with the harness's own data (claimed outcome, reviewer verdict, interventions, cost, tokens, time, safety incidents). paacm eval report gives each arm's accepted regression-free completion (pass@1 and pass^k), cost and time per accepted change, interventions, scope creep, tampering, false done claims, impossible-task passes and safety incidents, and the paired difference against a baseline arm with standard errors clustered by feature area. It reports a comparison as inconclusive, with the smallest detectable effect, when the interval includes zero, and never claims an interval from zero variance. paacm eval tasks validates the task set and prints it for a harness. docs/guide/evaluation.md documents the task-set format and the workflow.
A project install ignores .agent/tasks/ through .agent/.gitignore, but a plugin install has no such file, so task state showed as untracked and a per-task commit could include it. paacm task start now writes .agent/tasks/.gitignore when it is missing.
The core rules a plugin delivers (the Cursor rule and the text the Claude Code session-start hook injects) told the agent to invoke /paacm or open .claude/skills/paacm/SKILL.md, neither of which exists in a plugin install; Claude Code lists the plugin's skill as /paacm:paacm. Both plugin copies are now generated from one plugin variant of the AGENTS.md block, and project installs keep the project wording.
With no active task, the stop hook blocked once on every uncommitted file and told the agent it had changed them, including work in progress the user had before the session, which cost a turn on every question in a dirty tree. The session-start hook now records the uncommitted files and their content in the system temporary folder (keyed by project and session), and the stop hook reports only files that are new or changed since then. Without a baseline it reports every uncommitted file in wording that does not attribute them to the agent.
The protected-path patterns lived only in the project configuration a project install writes. A plugin install has no .agent/paacm.json, so the runtime's defaults applied, and their protect lists were empty: approved tests could be edited, executable configuration was not gated, and the audit reported nothing. The same happened in a project whose paacm.json left protect out. The defaults, protected paths included, are now defined once in the runtime's config.mjs. A project install writes them to .agent/paacm.json (unchanged output), and the runtime applies them for every key the file is missing or omits.
doctor stopped at the missing lock file, so for a plugin install it reported only that PAACM was not installed and never looked at the check manifest, which is the one thing such a project needs. It now checks the install only when a lock file exists, notes its absence otherwise, and always checks .agent/paacm.json (optional without a project install) and .agent/checks.conf.
docs/guide/ covers setup on each path (the Claude Code plugin, the Cursor plugin, a project install) and configuring the checks; running agentic coding with PAACM, from writing the request and attaching supporting data to approvals, autonomy levels, reading the report and BLOCKED stops; worked examples for both IDEs; troubleshooting and an FAQ. Invocation names and plugin commands were checked against Claude Code 2.1.292. The README describes the method and gives a quick start for each path. INSTALL_PROMPT.md now has the agent drive the installer's dry run and resolve its conflicts with the user instead of copying files by hand. CHANGELOG.md records 3.0.0. The PAACM 2 user guide is replaced by docs/guide/.
…e CLI 79 tests, run with `node --test` (no dependencies), covering: - the check manifest and runner: CRLF and BOM, every malformed line reported before anything runs, closed standard input, stop at the first failure with PASS/FAIL and a summary, timeouts (D1-D4); - managed blocks, the JSON settings merge and its exact reversal, glob matching of the protect lists, the shell guard rules; - the generator: content validation, no drift from the committed build, every generated skill, agent, rule and hook file, every IDE, layer and autonomy combination, and Claude Code's own plugin validator when the claude CLI is installed; - init, upgrade and uninstall: dry run, conflicts written as nothing, symbolic links, the kit as target (D5), file modes (D7), user files restored byte for byte, the v2 migration from a fixture of the exact 2.0.0 files; - the runtime: task lifecycle, test approval, every gate exit code, the retry cap, done refusals, block and resume, review input, the audit; - each hook against both IDEs' contracts, including fail-closed input errors, duplicate stop events and the session baseline; - doctor, detect, the dispatcher's exit codes, and eval's statistics, task-set validation, grading and report. The kit's own quick checks now run the suite.
ci.yml runs on pushes to main and on pull requests, with read-only permissions, no persisted credentials and actions pinned by commit SHA. The test job (Linux, macOS, Windows x Node.js 20, 22, 24) validates the kit content, checks the generated plugin for drift, runs the test suite, and installs the power layer into four fixture projects (empty, an existing AGENTS.md, a Node app, a Python app), where it runs detect, doctor and the checks, and uninstalls again. The lint job lints the Markdown with markdownlint-cli2 and validates the plugin and the marketplace with Claude Code's own validator. A new test checks that every relative link and anchor in the repository's Markdown resolves; external links are not fetched, so the check cannot be flaky. Lint findings are fixed: a second top-level heading in the architectures study, missing final newlines, extra blank lines and an unspaced code fence.
Each requirement R1-R12 now maps to the files and tests that satisfy it, each 2.0.0 defect to its fix and test, and the verification run on 2026-10-14 is recorded: the test suite, the fixture installs, Claude Code's plugin validator, and headless Claude Code runs showing the plugin and the project install loading and the shell guard, the protect hook and the stop gate enforcing. What could not be verified live (a Cursor session; macOS and Windows outside CI; effectiveness on a team's own code) is stated as such.
Git on Windows checks files out with CRLF, so the build drift check saw every committed generated file as different, and the Windows jobs stopped before the tests ran. .gitattributes now keeps LF in every checkout; no stored file changes. The eval tests built file:// URLs by hand, which gives file://C:/... on Windows, a form git and URL parsers read as a host. They now use pathToFileURL.
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
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.
Summary
PAACM 3.0.0 replaces the 2.0.0 kit with the Verified Single-Writer Loop: a method derived from a sourced study of agentic-coding research, vendor guidance and tooling, implemented for Claude Code and Cursor, with a zero-dependency command-line tool, an evaluation harness, user documentation, tests and CI.
What changes
docs/research/): benchmarks, architectures and context, methodologies, verification, a comparison matrix, Claude Code and Cursor mechanisms, security, evaluation and ranked practices, each with sources and evidence grades.docs/method/ALGORITHM.mdand 15 decision records):BLOCKED:protocol;src/content/,src/runtime/):paacm,paacm-verify,paacm-review;plugins/paacm/, served by both marketplace manifests).npx github:Hyper-AI-Lab/hyper-agents, Node.js 20+, no dependencies):init,upgradeanduninstall, which never overwrite user content (marked blocks inAGENTS.mdandCLAUDE.md, exact merge and unmerge of JSON settings, and a lock file with hashes);upgrade --from-v2;doctor,detectandcheck;eval, which grades runs of a private task set from the finished checkout and compares arms with clustered standard errors.docs/guide/(setup, running a request, examples for both IDEs, troubleshooting and FAQ, evaluation, upgrading from 2.0.0), a new README,INSTALL_PROMPT.mdand the CHANGELOG.scripts/agent-check,scripts/install-to-project.sh, the 2.0.0 payload at the repository root, andkit-checks.yml.Defects fixed
All seven 2.0.0 defects recorded in
docs/project/requirements.mdare fixed, each with a test:Three defects in the new code, found by the end-to-end runs, are fixed in this branch too:
.agent/paacm.json;Verification
npm test: 80 tests pass (Linux, Node.js 24).paacm validateandpaacm build --checkpass, and markdownlint-cli2 reports no issues.claude plugin validate --strict(Claude Code 2.1.285 and 2.1.292) accepts the plugin and the marketplace.AGENTS.md, a Node app, a Python app) passdoctorandcheck, anduninstallrestores the existingAGENTS.mdexactly.Limits
paacm evalis the tool for that.Review notes
Each commit is one step. Reading them in order follows the build-up: study, method, content model, instructions, Claude Code, Cursor, CLI, retirement of 2.0.0, evaluation, fixes, documentation, tests, CI, traceability. Files under
plugins/paacm/and the two marketplace manifests are generated; reviewsrc/content/andsrc/runtime/instead.