agentloopkit 0.1.1 → 0.24.0

package/README.md

@@ -2,7 +2,7 @@
 
 A drop-in engineering loop for coding agents.
 
-Your coding agent can already write code. AgentLoopKit helps it work like a disciplined engineer: scoped task contracts, explicit safety rules, verification evidence, review summaries, and clean handoffs.
+Your coding agent can write code. AgentLoopKit gives it the repo habits reviewers need: scoped task contracts, safety rules, verification evidence, review summaries, and clean handoffs.
 
 Vibe coding produces code. Agentic engineering produces auditable work.
 
@@ -10,6 +10,8 @@ Vibe coding produces code. Agentic engineering produces auditable work.
   <img src="https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/docs/assets/readme/agentloopkit-showcase.png" alt="AgentLoopKit workflow showing task contracts, verification reports, and handoff artifacts" width="100%">
 </p>
 
+The screenshots and terminal demo in this README are generated from committed sources in `docs/assets/readme/` with Playwright and VHS.
+
 ## What It Is
 
 AgentLoopKit is a repo-level toolkit for developers using Codex, Claude Code, Cursor, OpenCode, Gemini CLI, GitHub Copilot CLI, and other coding agents.
@@ -44,21 +46,55 @@ npx agentloopkit init
 npx agentloopkit init --dry-run
 ```
 
+Latest GitHub release: `v0.24.0`. npm still serves `0.1.1`: the next npm publish should catch up once to `0.24.0`; after that, releases return to normal sequential semver. Local `npm whoami` currently returns `E401`, so npm publish is blocked from this shell.
+
+See [docs/release-status.md](docs/release-status.md) for the current GitHub/npm status and update rules.
+
+Until npm catches up, run the current GitHub release tarball directly:
+
+```bash
+npx --yes --package https://github.com/abhiyoheswaran1/AgentLoopKit/releases/download/v0.24.0/agentloopkit-0.24.0.tgz agentloop version
+npx --yes --package https://github.com/abhiyoheswaran1/AgentLoopKit/releases/download/v0.24.0/agentloopkit-0.24.0.tgz agentloop init
+```
+
+The npm version jump has one reason: GitHub releases already exist for the intermediate AgentLoopKit versions between the npm-published `0.1.1` package and the current `v0.24.0` source line. Publishing older numbers from current `main` would create npm packages that do not match their GitHub tags. Once npm authentication or trusted publishing works, the next npm publish should ship `0.24.0`; future releases should then continue with normal sequential semver.
+
 Run the CLI after install:
 
 ```bash
 npx agentloopkit doctor
 npx agentloopkit create-task --title "Add settings page" --type feature
+npx agentloopkit task list
+npx agentloopkit task show .agentloop/tasks/2026-06-09-add-settings-page.md
+npx agentloopkit task set .agentloop/tasks/2026-06-09-add-settings-page.md
+npx agentloopkit task status .agentloop/tasks/2026-06-09-add-settings-page.md in-progress
+npx agentloopkit status
+npx agentloopkit next
 npx agentloopkit verify
-npx agentloopkit summarize --write
+npx agentloopkit handoff
+npx agentloopkit check-gates
+npx agentloopkit check-gates --strict
+npx agentloopkit report
+npx agentloopkit badge
+npx agentloopkit ci-summary
+npx agentloopkit release-notes
+npx agentloopkit npm-status
+npx agentloopkit policy list
+npx agentloopkit policy show security
+npx agentloopkit policy status
+npx agentloopkit task archive .agentloop/tasks/2026-06-09-add-settings-page.md
 npx agentloopkit install-agent codex
 npx agentloopkit install-agent all
+npx agentloopkit completion zsh
+npx agentloopkit completion powershell
 ```
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/docs/assets/readme/agentloopkit-cli.gif" alt="Terminal demo running AgentLoopKit init, doctor, create-task, and summarize" width="100%">
+  <img src="https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/docs/assets/readme/agentloopkit-cli.gif" alt="Terminal demo running AgentLoopKit init, task contracts, active task status, task-linked verify, handoff, reports, badges, release notes, gates, and task archive commands" width="100%">
 </p>
 
+The VHS demo runs the local built CLI so the command flow matches this repository even when npm is behind.
+
 Pinned team usage:
 
 ```bash
@@ -78,18 +114,39 @@ pnpm build
 
 ## CLI Commands
 
-| Command                         | Purpose                                                 |
-| ------------------------------- | ------------------------------------------------------- |
-| `agentloop init`                | Generate the repo harness and config                    |
-| `agentloop init --dry-run`      | Preview generated files without writing them            |
-| `agentloop doctor`              | Check setup health, commands, git state, and risk files |
-| `agentloop create-task`         | Create a task contract in `.agentloop/tasks/`           |
-| `agentloop verify`              | Run configured checks and write a verification report   |
-| `agentloop summarize`           | Generate a deterministic PR or reviewer summary         |
-| `agentloop install-agent codex` | Add agent-specific instructions                         |
-| `agentloop install-agent all`   | Add all bundled agent instruction files                 |
-| `agentloop list-templates`      | List bundled templates                                  |
-| `agentloop version`             | Print the CLI version                                   |
+| Command                                 | Purpose                                                                        |
+| --------------------------------------- | ------------------------------------------------------------------------------ |
+| `agentloop init`                        | Generate the repo harness and config                                           |
+| `agentloop init --dry-run`              | Preview generated files without writing them                                   |
+| `agentloop doctor`                      | Check setup health, template version, commands, git state, and risk categories |
+| `agentloop create-task`                 | Create a task contract in `.agentloop/tasks/`                                  |
+| `agentloop task list`                   | List task contracts and show the pinned active task                            |
+| `agentloop task show <path>`            | Print a task contract without changing active state                            |
+| `agentloop task set <path>`             | Pin the active task for status and handoffs                                    |
+| `agentloop task status <path> <status>` | Update a task contract status line                                             |
+| `agentloop task archive <path>`         | Move a task contract into `.agentloop/tasks/archive/`                          |
+| `agentloop task current`                | Print the pinned active task                                                   |
+| `agentloop task clear`                  | Clear the active task pointer                                                  |
+| `agentloop status`                      | Show active task, latest report, dirty files, next step                        |
+| `agentloop next`                        | Print only the next recommended loop action                                    |
+| `agentloop check-gates`                 | Check task, verification, handoff, harness, policy, and git evidence           |
+| `agentloop check-gates --strict`        | Treat warning gates as failures for CI                                         |
+| `agentloop verify`                      | Run configured checks and write a verification report                          |
+| `agentloop summarize`                   | Generate a deterministic PR or reviewer summary                                |
+| `agentloop handoff`                     | Write a reviewer handoff summary                                               |
+| `agentloop report`                      | Write a local static HTML evidence report                                      |
+| `agentloop badge`                       | Write a local SVG evidence badge                                               |
+| `agentloop ci-summary`                  | Summarize CI context and local AgentLoop evidence                              |
+| `agentloop release-notes`               | Draft local release notes from changelog, git, task, and verification evidence |
+| `agentloop npm-status`                  | Check npm registry catch-up status without publishing                          |
+| `agentloop policy list`                 | List local safety policy files                                                 |
+| `agentloop policy show <policy>`        | Print a local safety policy without mutating files                             |
+| `agentloop policy status`               | Compare local policy files with bundled templates                              |
+| `agentloop install-agent codex`         | Add agent-specific instructions                                                |
+| `agentloop install-agent all`           | Add all bundled agent instruction files                                        |
+| `agentloop list-templates`              | List bundled templates                                                         |
+| `agentloop completion <shell>`          | Print bash, zsh, fish, or PowerShell completion scripts                        |
+| `agentloop version`                     | Print the CLI version                                                          |
 
 The package exposes two binaries:
 
@@ -98,10 +155,32 @@ agentloop init
 agentloopkit init
 ```
 
+## Shell Completions
+
+AgentLoopKit prints completion scripts to stdout. It does not edit `.zshrc`, `.bashrc`, fish config, PowerShell startup files, or other shell profile files.
+
+Inspect a script before installing it:
+
+```bash
+agentloop completion zsh
+agentloop completion bash
+agentloop completion fish
+agentloop completion powershell
+agentloop completion pwsh
+```
+
+Example zsh setup:
+
+```bash
+mkdir -p ~/.zsh/completions
+agentloop completion zsh > ~/.zsh/completions/_agentloop
+```
+
 ## Generated Files
 
 ```text
 .agentloop/
+  manifest.json
   loops/
   gates/
   handoffs/
@@ -117,10 +196,12 @@ agentloop.config.json
 
 `init` appends to an existing `AGENTS.md` instead of overwriting it.
 
-The package ships `schema/agentloop.config.schema.json` for editors and config validation.
+The package ships `schema/agentloop.config.schema.json` for editors and config validation. Generated configs use the GitHub raw schema URL for editor support; the CLI validates config locally and does not fetch that URL at runtime.
 
 See `docs/configuration.md` for config fields and schema notes.
 
+Fresh `init` also writes `.agentloop/manifest.json` so `doctor` can report which template generation created the local harness. See `docs/template-migrations.md` for manual upgrade guidance.
+
 ## Agent Usage
 
 Install instructions for the agent you use:
@@ -141,9 +222,34 @@ AgentLoopKit only writes safe repo-local Markdown instructions when exact third-
 Create a contract before a coding session:
 
 ```bash
-agentloop create-task --type feature --title "Add settings page"
+agentloop create-task --type feature --title "Add settings page" \
+  --problem-statement "Users cannot manage account preferences" \
+  --desired-outcome "Users can update settings from the app" \
+  --likely-file src/settings \
+  --forbidden-file migrations/ \
+  --acceptance "Settings can be saved" \
+  --verification "pnpm test" \
+  --rollback "Remove the settings route"
+```
+
+Pin the contract when more than one task exists:
+
+```bash
+agentloop task list
+agentloop task show .agentloop/tasks/2026-06-09-add-settings-page.md
+agentloop task set .agentloop/tasks/2026-06-09-add-settings-page.md
+agentloop task status .agentloop/tasks/2026-06-09-add-settings-page.md in-progress
+agentloop task archive .agentloop/tasks/2026-06-09-add-settings-page.md
+agentloop task current
+agentloop task clear
 ```
 
+`task list --json` gives agents a deterministic list with `path`, `title`, `status`, `active`, and `modifiedAt`. Listing tasks does not create or update `.agentloop/state.json`.
+`create-task --json` returns the created task path and Markdown content so agents do not need to parse the human success line.
+`task show --json` returns the selected task metadata and Markdown content without changing active state.
+`task status --json` updates only the `- Status:` line. Supported values are `proposed`, `in-progress`, `blocked`, `review`, and `done`. Status is not verification evidence; run `agentloop verify` before claiming completion.
+`task archive --json` moves one named Markdown contract into `.agentloop/tasks/archive/`, refuses to overwrite an existing archive file, and clears the active task pointer when it archives the active task. Archive after verification and handoff, not as a substitute for either.
+
 Each contract records:
 
 - problem statement
@@ -165,24 +271,205 @@ Each contract records:
 .agentloop/reports/YYYY-MM-DD-HH-mm-verification-report.md
 ```
 
-It does not hide failures. If no commands are configured, it writes a report saying nothing was verified.
+Pass `--task .agentloop/tasks/file.md` to include task title, type, status, and path in the report. AgentLoopKit reads Markdown task contracts for this flag. It reports `.env`-style paths as unavailable instead of reading them.
+
+It does not hide failures. Failed reports include a short failure summary with each failed command, exit code, and final useful output lines before the full command output. If long logs are truncated, the report keeps the first and last output so the final error stays visible. If no commands are configured, it writes a report saying nothing was verified.
+
+When `agentloop verify` runs in GitHub Actions, the report records the workflow, event, ref, commit, run URL, and run attempt. Local reports stay quiet. AgentLoopKit does not read `.env` files or print arbitrary environment variables.
+
+In monorepos, `doctor` warns on common workspace markers and suggests package-specific verification commands. Add package checks to the task contract when root commands do not cover the touched package, for example `pnpm --filter web test` or `npm --workspace api test`. AgentLoopKit records and runs configured commands; it does not infer package graphs or run workspace commands automatically.
+
+`doctor` also reports potential risk files by category, such as migrations, auth, deployment, lockfiles, and env files. It lists path examples only. It does not read `.env` contents or claim to scan secrets.
+See `docs/doctor-risk-files.md` for category examples, limits, and reviewer actions.
+
+## Status
+
+`agentloop status` gives agents and humans a quick local readout:
+
+- active task contract, using `agentloop task set` when present
+- newest task contract when no active task is pinned
+- latest verification report
+- working tree state
+- configured and missing commands
+- next suggested command
+
+Use JSON output in scripts:
+
+```bash
+agentloop status --json
+```
+
+Use `agentloop next` when an agent or script only needs the next local command:
+
+```bash
+agentloop next
+agentloop next --json
+```
+
+`next` uses the same decision rules as `status`. It does not run verification commands, create task state, call an LLM, make network requests, or read `.env` contents.
+When an active in-progress task exists, an older verification report does not count as current evidence for that task.
+
+See `docs/status.md` for output fields and next-action rules.
+
+## Gate Checks
+
+`agentloop check-gates` checks review evidence without running tests or calling an LLM. It looks for:
+
+- a task contract
+- a generated verification report
+- a generated handoff summary
+- repo harness files
+- core safety policies
+- git working tree context
+
+Use JSON output in scripts:
+
+```bash
+agentloop check-gates --json
+agentloop check-gates --strict
+```
+
+Warnings keep exit code `0` by default. Use `--strict` in CI when warning gates should fail the command.
+
+`doctor` checks setup health. `check-gates` checks whether the current work session has the evidence reviewers expect.
+
+See `docs/check-gates.md` for gate statuses and exit-code behavior.
+
+## HTML Reports
+
+`agentloop report` writes a local static HTML page from the current task contract, latest verification report, latest handoff, git status, diff stats, and deterministic review summary:
+
+```bash
+agentloop report
+agentloop report --json
+agentloop report --out .agentloop/reports/review.html
+```
+
+The command does not run tests, call an LLM, fetch assets, read `.env` contents, or send data anywhere. It writes one local file under `.agentloop/reports/` by default. Use it after `verify` and `handoff` when you want a browser-readable artifact for a PR or CI upload.
+
+See `docs/html-reports.md` for inputs, output paths, and safety behavior.
+
+## Evidence Badges
+
+`agentloop badge` writes a local SVG badge from existing evidence:
+
+```bash
+agentloop badge
+agentloop badge --source gates
+agentloop badge --json
+```
+
+The default badge reads the latest verification report and writes `.agentloop/reports/agentloop-verification.svg`. Gate badges read local gate status and write `.agentloop/reports/agentloop-gates.svg`. The command does not run tests, call a badge service, read `.env`, or upload anything.
+
+See `docs/badges.md` for badge sources and CI usage.
+
+## CI Summaries
+
+`agentloop ci-summary` reads allowlisted CI provenance fields and existing AgentLoop artifacts:
+
+```bash
+agentloop ci-summary
+agentloop ci-summary --json
+agentloop ci-summary --write
+```
+
+In GitHub Actions, GitLab CI, and Buildkite it reports provider, workflow or pipeline, event, ref, commit, and run URL when those allowlisted fields are present. Unsupported CI providers report generic CI when `CI=true` is present. The command does not call provider APIs, read secrets, upload files, run tests, or dump arbitrary environment variables.
+
+Use `--write` when CI should upload a small Markdown summary alongside verification reports, HTML reports, badges, and handoffs. Verification consumers still read `*-verification-report.md`; CI summary artifacts do not replace verification evidence.
+
+See `docs/ci-summary.md`.
+
+## Release Notes
+
+`agentloop release-notes` drafts local release notes from the repository state:
+
+```bash
+agentloop release-notes
+agentloop release-notes --from v0.19.0 --to HEAD
+agentloop release-notes --release-version 0.24.0
+agentloop release-notes --json
+agentloop release-notes --write
+```
+
+The command reads local package metadata, changelog entries, git history, changed files, working tree status, the active task, the latest verification report, and the latest CI summary when those artifacts exist. It does not create tags, publish packages, call GitHub or npm APIs, read tokens, upload files, or rewrite changelogs.
+
+Use it before creating a GitHub release so the release note draft includes the same evidence reviewers see in AgentLoop handoffs.
+
+See `docs/release-notes.md`.
+
+`agentloop npm-status` checks whether npm latest matches the local package version:
+
+```bash
+agentloop npm-status
+agentloop npm-status --json
+agentloop npm-status --expect-current
+agentloop npm-status --registry-json npm-view.json
+```
+
+Use it after a publish attempt before saying npm has caught up. It runs `npm view` unless you pass captured registry JSON. It does not publish packages, create tags, read tokens, read `.env` files, upload files, or change package metadata.
+
+See `docs/npm-status.md`.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/docs/assets/readme/agentloopkit-verification.png" alt="AgentLoopKit verification report screenshot showing command results and reviewer handoff sections" width="100%">
+  <img src="https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/docs/assets/readme/agentloopkit-verification.png" alt="AgentLoopKit verification report screenshot showing task context, passing command results, and reviewer handoff sections" width="100%">
 </p>
 
+## Policies
+
+`agentloop policy` makes generated repo policy files visible from the CLI:
+
+```bash
+agentloop policy list
+agentloop policy show security
+agentloop policy status
+agentloop policy list --json
+agentloop policy status --json
+```
+
+The command reads Markdown files from `.agentloop/policies/`. `policy status` reports `current`, `modified`, `missing`, and `extra` files by comparing local Markdown with bundled templates. It does not enforce compliance, scan source code, fetch remote policy packs, or mutate policy files.
+
+Local policy files are repo guidance. A `modified` policy can be intentional; review it like code instead of overwriting it to match the bundled template.
+
+See `docs/policies.md`.
+
+## Security Reviews
+
+Use `security-review` task contracts when a change touches auth, sessions, permissions, secrets, dependencies, deployment config, migrations, billing, or other sensitive areas.
+
+AgentLoopKit helps reviewers see scope, checks run, checks skipped, risk notes, and rollback instructions. It does not scan code, certify compliance, or prove that code is secure.
+
+See `docs/security-review.md` and `examples/security-review/` for a copyable review task, verification report, and PR summary.
+
+## Dependency Upgrades
+
+Use `dependency-upgrade` task contracts when an agent changes packages or lockfiles. AgentLoopKit records upgrade scope, lockfile impact, verification, risks, and rollback notes. It does not choose package versions, scan advisories, or call package registries.
+
+See `docs/dependency-upgrades.md` and `examples/dependency-upgrade/`.
+
+## CI Recipes
+
+Use `agentloop check-gates --strict` as a review-evidence gate in pull request CI. Use `agentloop verify`, `agentloop handoff`, `agentloop report`, `agentloop badge`, `agentloop ci-summary --write`, and `agentloop release-notes --write` in CI when you want evidence artifacts uploaded for reviewers.
+
+CI-generated verification reports include GitHub Actions provenance when available, so reviewers can trace an artifact back to the workflow run that created it.
+
+See `docs/github-actions.md`, `examples/github-actions/`, `examples/gitlab-ci/`, and `examples/buildkite/` for copy-pasteable workflows. Until npm catches up, the examples pin the latest public GitHub release tarball. Current source moves to a new tarball when the next GitHub release is cut.
+
 ## PR Summaries
 
-`agentloop summarize` uses deterministic inputs:
+`agentloop handoff` writes a reviewer-ready summary using deterministic inputs:
 
 - git status
 - git diff stats
-- latest task contract
+- active task contract, or newest task when no active task is pinned
 - latest verification report
 - config settings
 
+The summary groups changed files into review areas such as source, tests, docs, CI, config, AgentLoop artifacts, and risk-sensitive paths. It adds review-focus hints from file paths only.
+
 It does not call an LLM.
 
+Use `agentloop summarize` to preview the same output without writing a handoff file. `agentloop summarize --write` remains available for scripts.
+
 ## Safety Principles
 
 AgentLoopKit is intentionally boring:
@@ -232,6 +519,11 @@ See `examples/` for sample generated harnesses:
 - `examples/python-service`
 - `examples/docs-only`
 - `examples/empty-repo`
+- `examples/github-actions`
+- `examples/security-review`
+- `examples/dependency-upgrade`
+
+See `docs/stack-recipes.md` for Next.js, React/Vite, Remix, SvelteKit, Node API, Django, FastAPI, Python, docs-only, empty-repo, and monorepo verification recipes.
 
 ## Roadmap
 
@@ -239,15 +531,19 @@ See `ROADMAP.md`.
 
 ## Publishing Status
 
-AgentLoopKit is published on npm as `agentloopkit`.
+AgentLoopKit is published on npm as `agentloopkit`, but npm currently serves `0.1.1`. GitHub release `v0.24.0` carries task-linked verification reports, failed-verification summaries, the guarded `--task` path behavior, refreshed README visuals, PowerShell shell completions, and the read-only `npm-status` catch-up check. npm still needs account authentication or trusted-publishing repair before a catch-up release lands.
+
+Do not publish stale older versions from current `main`. If `CHANGELOG.md` has real entries under `Unreleased`, the prepublish guard blocks npm publish until release metadata is prepared.
+
+The npm version jump is intentional. The skipped npm numbers already exist as public GitHub release candidates while npm publishing was blocked, so the next npm publish should ship the current release line rather than backfilling old source snapshots.
 
 The repository includes a GitHub Actions publish workflow for npm trusted publishing after the package is configured on npm. The workflow runs checks before `npm publish` and skips publish when the version already exists.
 
-See `docs/launch-checklist.md` before publishing.
+See `docs/launch-checklist.md` before publishing. See `docs/npm-status.md`, `docs/release-checklist-example.md`, and `examples/release-checklist/` for registry checks and compact maintainer handoffs when GitHub is current but npm is still behind.
 
 ## Contributing
 
-See `CONTRIBUTING.md`.
+See `CONTRIBUTING.md` for local setup and PR expectations. Maintainers can use `docs/contributor-playbook.md` for copyable good-first issue examples.
 
 ## License