{ "markdown": "# AgentLoopKit\n\n

\n \"AgentLoopKit\n

\n\nA drop-in engineering loop for software agents.\n\nAn open-source Baseframe Labs developer tool.\n\nYour software agent can produce a diff. AgentLoopKit helps you decide whether that work is reviewable, verifiable, and merge-ready.\n\nIt gives Codex, Claude Code, Cursor, OpenCode, Gemini CLI, GitHub Copilot CLI, and other engineering agents a local acceptance layer: task contracts, safety rules, verification evidence, review-readiness scores, PR descriptions, and reviewer handoffs.\n\nUnstructured automation produces code. Agentic engineering produces auditable work.\n\nProjScan finds the risk.\nAgentLoopKit controls the work.\nAgentFlight proves the result.\n\n

\n \"AgentLoopKit\n

\n\nThe screenshots and terminal demos in this README are generated from committed sources in `docs/assets/readme/` with Playwright and VHS. You can regenerate them locally.\n\n## What It Does\n\nAgentLoopKit is a repo-level toolkit for developers using Codex, Claude Code, Cursor, OpenCode, Gemini CLI, GitHub Copilot CLI, and other engineering agents.\n\nKeep your agent, IDE, and CLI. AgentLoopKit gives those tools a repeatable local workflow:\n\n1. Specify the task.\n2. Constrain the risk.\n3. Implement the smallest useful change.\n4. Verify with real commands.\n5. Review the diff.\n6. Hand off with evidence.\n7. Ship only when the work is reviewable.\n\nRun `init` inside an existing repository and AgentLoopKit creates:\n\n- `.agentloop/` for tasks, reports, handoffs, gates, policies, templates, and agent instructions\n- `AGENTS.md` for agent-facing repo guidance\n- `AGENTLOOP.md` for the working loop\n- `agentloop.config.json` for local command and path settings\n\nGenerated `AGENTS.md` includes a specialist roster for product, CLI, template, verification, security, release, docs, compatibility, MCP, and repo-steward work. It helps future agent sessions split work without adding a background service.\n\n

\n \"Terminal\n

\n\nThe CLI demo shows the normal path: initialize a repo, create a task, run reviewed verification, score review readiness, draft PR copy, inspect review context, and trace why a file changed.\n\n## Install\n\nUse it with `npx` from the repository you want to configure:\n\n```bash\ncd /path/to/your/repo\nnpx agentloopkit init --dry-run\nnpx agentloopkit init\n```\n\n`init` writes files into the current directory. `--dry-run` previews the same plan and writes nothing.\n\nCommit the generated harness baseline before your first feature task when you want clean diff evidence. If the harness files are still uncommitted, `explain-diff`, Guard, and resume packs will include those generated files as local work, which is accurate but noisier than the steady-state loop.\n\nAfter setup, non-init commands search upward for the nearest `agentloop.config.json` and use that folder as the AgentLoop root. You can run `agentloop status`, `agentloop verify`, `agentloop ship`, or `agentloop prepare-pr` from a nested source folder and still write tasks, reports, runs, and handoffs to the initialized repo root.\n\nDo not run `init` from your home directory unless you intend to configure your home folder. AgentLoopKit refuses that by default; `--force` allows it and prints a home-directory target warning. If you want local agent guidance but do not want to commit the generated files, use local-only mode:\n\n```bash\nnpx agentloopkit init --local-only\n```\n\n`--local-only` writes the harness, asks Git for this clone's metadata directory, then adds a marked block to that clone's `info/exclude` for `.agentloop/`, `AGENTS.md`, `AGENTLOOP.md`, and `agentloop.config.json`. It does not edit `.gitignore`, global Git config, shell profiles, or other project files.\n\nThe examples below use `agentloop` after setup. If you are not installing the package locally or exposing its binary on `PATH`, keep using the one-off form, for example `npx --yes agentloopkit@latest doctor --redact-paths`.\n\nCheck the published package explicitly:\n\n```bash\nnpx --yes agentloopkit@latest version\nnpx --yes agentloopkit@latest init\n```\n\nFor repeatable CI or team setup, replace `@latest` with a vetted version.\n\nBefore initialization, exploratory preflight can be advisory:\n\n```bash\nnpx --yes agentloopkit@latest doctor --advisory --redact-paths\n```\n\nAdvisory mode keeps missing-setup diagnostics visible but exits `0` so first-run scripts can continue. Use plain `doctor` or `doctor --strict` for gates that should fail on setup errors.\n\nPinned team usage:\n\n```bash\npnpm add -D agentloopkit\npnpm agentloop init\n```\n\n## Existing Repos\n\nRepos that already use AgentLoopKit can update the CLI without rewriting local harness files:\n\n```bash\ncd /path/to/existing/repo\nnpx --yes agentloopkit@latest version\nnpx --yes agentloopkit@latest doctor --redact-paths\nnpx --yes agentloopkit@latest upgrade-harness --details --redact-paths\nnpx --yes agentloopkit@latest init --dry-run\n```\n\nThese commands inspect the published package. This repository may document unreleased guidance before the next publish; check [release status](docs/release-status.md) before expecting `agentloopkit@latest` to include new subcommands.\n\n`init` skips existing generated files and appends to unmarked `AGENTS.md` files instead of overwriting maintainer edits. Use `upgrade-harness` to find older guidance that does not tell agents to run `agentloop doctor` and `agentloop start` before broad reads, list handles with `agentloop context handles` when available, or expand source truth with `agentloop context show `. Copy only the useful pieces into `AGENTS.md`, `AGENTLOOP.md`, or `.agentloop/harness/*`.\n\nYou can use the latest loop before refreshing old guidance:\n\n```bash\nnpx --yes agentloopkit@latest create-task --type bugfix --title \"Fix checkout bug\"\nnpx --yes agentloopkit@latest start --for generic --goal implement --redact-paths\nnpx --yes agentloopkit@latest verify\nnpx --yes agentloopkit@latest ship\nnpx --yes agentloopkit@latest prepare-pr\nnpx --yes agentloopkit@latest maintainer-check\n```\n\n## Core Workflow\n\nFirst useful loop after `init`:\n\n```bash\nagentloop doctor\nagentloop create-task --type bugfix --title \"Fix checkout bug\" --include-config-commands\nagentloop status --brief\nagentloop start --for codex --goal implement --redact-paths\nagentloop loop create --goal \"Keep checkout work release-ready\" --budget-tokens 50000 --max-iterations 5\nagentloop loop tick\nagentloop loop scorecard\nagentloop ready\nagentloop verify --task-commands --progress\nagentloop ship\nagentloop prepare-pr\nagentloop task done\n```\n\nThat sequence creates a task contract, checks the repo setup, gives the next software agent a compact start briefing, records a local loop contract with token receipts, scores whether another loop pass should continue, checks readiness gates, runs only reviewed verification commands, records review-readiness evidence, drafts PR copy, and closes the active task. It does not post to GitHub, publish packages, call an LLM, execute a coding agent, or run hidden commands.\n\n### Make Your Agent Start Here\n\nBefore a software agent broad-scans the repo, run:\n\n```bash\nagentloop doctor --redact-paths\nagentloop start --for codex --goal implement --redact-paths\nagentloop context handles --redact-paths\nagentloop context show --redact-paths\n```\n\n`doctor` checks the Agent Readiness Matrix: Doctor-before-Start guidance, Start guidance, context-handle guidance, broad-read avoidance, MCP guidance, and installed agent instruction files. `start` gives the current task, proof, risk, context budget, and source handles. `context handles` lists which handles are available now. `context show` expands exact local source truth only when the agent needs detail.\n\n```bash\nnpx agentloopkit init\nagentloop create-task --title \"Fix login redirect bug\" --type bugfix \\\n --acceptance \"Password-reset login redirects to the requested page\" \\\n --include-config-commands \\\n --verification \"npm test -- auth\"\n\n# Run Codex, Claude Code, Cursor, OpenCode, Gemini CLI, or another software agent.\n\nagentloop verify --task-commands --only-task-commands --progress\nagentloop ship --github-comment\nagentloop prepare-pr\n```\n\n`create-task` sets the new contract as the active task. Use `agentloop task set ` only when you need to switch to another contract.\nAdd `--include-config-commands` when you want the task contract to copy non-empty `test`, `lint`, `typecheck`, and `build` commands from `agentloop.config.json`. Task creation records those commands; it does not run them. Use `verify --task-commands --only-task-commands` when the active contract already includes the full check list.\nUse `verify --post-verification-gates` only for reviewed task gates that need the verification report to exist first.\nAfter verification and `ship`, use `agentloop prepare-pr` for reviewer copy and `agentloop task done` to close the active task before starting unrelated work.\n\nUse `agentloop status` or `agentloop next` when an agent needs the next local action without reading every file:\n\n```bash\nnpx agentloopkit status\nnpx agentloopkit status --brief\nnpx agentloopkit next\nnpx agentloopkit next --redact-paths\n```\n\nWhen `status` or `next` recommends `create-task` in a dirty repo, the reason calls out existing dirty non-evidence files so agents can confirm the next task scope before implementation. When `create-task` sees that same pre-existing dirty work, it also adds a bounded Risk Notes bullet to the generated task contract so later review evidence preserves the baseline count and examples.\n\nUse `agentloop start --for codex --goal implement --redact-paths` when a software agent needs the repo truth before broad reads. Start is the preflight: current task when one exists, decisive state, next safe command, read-first handles, risk summary, verification freshness, context-budget impact, and source handles. Use `agentloop context handles` to list available handles and normal empty states, then `agentloop context show ` to expand source truth only when needed. Use `agentloop context pack --for codex --goal continue --redact-paths` when you need the lower-level receipt and omission details directly. Use `agentloop guard` when you want a live local check for scope drift, stale verification, proof debt, and context-budget pressure before review. Use `agentloop explain-diff` when you need to understand whether the current changed files are covered by task scope, recent run evidence, fresh verification, and risk guidance. Use `agentloop resume-pack --for codex`, `--for claude`, `--for cursor`, `--for generic`, or `--for human` when you need the older compact continuation surface. These commands are read-only by default and use local evidence only.\n\n`agentloop start` is the agent starting point. It keeps agents from guessing by turning task state, changed files, verification, risk, and context pressure into one compact preflight. The Context Contract sits underneath it: `context pack` explains why each item is present, names what was left out, and provides local handles for the source truth. A large changed-file list becomes a small briefing the agent can expand only when it needs detail.\n\n`agentloop loop` adds a local loop contract on top of normal task contracts. `agentloop loop create` records the goal, budget, stop conditions, suggested commands, native task path, and a token receipt. `agentloop loop tick` records one iteration decision from local evidence: continue, stop, ask for human review, or mark the loop ready when gates pass. Once a loop asks for human review, AgentLoopKit rejects another tick until someone reviews the loop report and resolves the blocking evidence. Use `agentloop ready` when you need the current review-readiness gate summary without creating a loop.\n\nUse `agentloop harden [task]` before work starts to interrogate a task contract for unresolved soft spots — placeholder text, unbounded scope, unstated assumptions, untestable acceptance criteria, and contradictions between Acceptance Criteria and Non-Goals. It defaults to the active task and exits non-zero when a blocking soft spot remains. Resolve one with `agentloop harden --resolve --answer \"...\"`, which records the answer in the contract's Hardening Log. `agentloop create-task` reports the same soft spots by default right after creating a contract.\n\nFor a bounded autonomous pass, configure one local runner command and let AgentLoopKit record the iteration:\n\n```bash\nagentloop loop create \\\n --goal \"Keep checkout work release-ready\" \\\n --runner-command \"node scripts/agentloop-runner.mjs\" \\\n --runner-timeout-ms 600000 \\\n --budget-tokens 50000 \\\n --max-iterations 5\n\nagentloop loop run\nagentloop loop scorecard\nagentloop ready --strict\nagentloop loop report\n```\n\n`loop scorecard` is the pre-flight gate before another autonomous pass. It reads the loop contract, readiness state, context pack, token budget, iteration budget, runner guardrails, and scope evidence, then returns `continue`, `ask-human`, `stop`, or `ready`. It does not execute the runner or run verification.\n\n`loop run` executes only the command saved in the loop contract. It uses `shell: false`, rejects shell syntax, blocks publish and destructive command families, caps runner output, records changed files, and still applies the max-iteration and token-budget stop conditions. AgentLoopKit controls the goal, budget, scope, gates, evidence, and stop decision. Your agent, script, CI job, or AgentFlight session does the implementation work.\n\nJSON and MCP context budget/pack payloads keep that boundary: they include compact evidence fields and the `evidence-map:current` handle, but they do not send the full changed-file list unless the agent expands that local handle.\n\nStart uses a strict current-work rule. It accepts active or open task contracts. Archived, `done`, `deferred`, and AgentFlight placeholder tasks stay as previous evidence. Start and Context omit `task:active` handles and `agentloop ship` guidance for old work. In a clean repo with only previous evidence, Start tells the agent that no active task exists.\n\n```text\nYour software agent / app\n (Codex, Claude Code, Cursor, OpenCode, Gemini CLI, Copilot CLI,\n LangChain, Agno, Strands, your own scripts...)\n |\n | task contracts - diffs - verification - runs - research notes - logs\n v\n +------------------------------------------------------------------------+\n | AgentLoop Start Preflight + Context Contract (source truth stays here) |\n |------------------------------------------------------------------------|\n | State -> Next Safe Command -> Read First -> Risk -> Impact -> Handles |\n | | |\n | +-- task:active (current work only)|\n | +-- verification:latest |\n | +-- run:latest |\n | +-- evidence-map:current |\n | +-- context-budget:current |\n | |\n | Goals: implement - continue - review - debug - handoff - research |\n | MCP tools - generated agent instructions - transparent local heuristics |\n +------------------------------------------------------------------------+\n |\n | compact preflight + retrieval handles\n v\nAgent session / review / research handoff\n```\n\n

\n \"AgentLoopKit\n

\n\nThe context-budget example is generated from local AgentLoopKit output in this repository. Token estimates use `ceil(character_count / 4)` for planning, not provider tokenizer counts or billing claims. The percentage changes with repo state; the point is that agents can start from selected evidence and expand source handles instead of pasting broad history.\n\nRun the repeatable [Start usefulness demo](docs/start-usefulness-demo.md) to create a temporary messy repo and see `agentloop doctor` check agent-readiness guidance, then `agentloop start` report context avoided, broad files avoided, stale proof, scope drift, source handles, and the next safe command.\n\n

\n \"Terminal\n

\n\nThe terminal demo is generated from committed VHS sources in this repository. It shows the intended agent workflow: check readiness with Doctor, run Start preflight, see what not to broad-scan, expand the current task handle when one exists, and verify with local evidence.\n\n

\n \"AgentLoopKit\n

\n\nVerification reports turn local commands into review evidence. They keep command status, failure summaries, task links, changed-file context, and follow-up gates in one artifact reviewers can inspect.\n\n## Dogfood Gate\n\nAgentLoopKit uses its own loop in this repo. Contributors can run the same local self-check:\n\n```bash\nnpm run dogfood\n```\n\nThat command checks task-folder hygiene, current loop status, public docs hygiene, dependency audit results, harness upgrade state, review gates, artifact inventory, maintainer reviewability, agent review context, AgentFlight health, and ProjScan health. It does not publish packages, create tags, post comments, read tokens, read `.env` contents, or run verification commands.\n\nUse JSON output when an agent or CI job needs a structured dogfood summary:\n\n```bash\nnpm run dogfood:json\nnpm run dogfood:strict:json\n```\n\nThe JSON summary reports the mode, overall status, step results, exit codes, durations, and safety notes. It redacts the current workspace root as `[git-root]` before printing structured output.\n\nRun the public-doc check by itself when you edit README, examples, or release-channel docs:\n\n```bash\nnpm run check:public-docs\n```\n\nUse the stricter gate before a release or final handoff:\n\n```bash\nnpm run dogfood:strict\n```\n\nUse the maintenance gate when typecheck, release-proof or npm-status command health, public docs, SchemaStore, policy packs, GitHub metadata, AgentFlight, or ProjScan behavior changes:\n\n```bash\nnpm run maintenance:check\n```\n\n`maintenance:check` covers unit tests, typecheck, public docs, links, non-strict npm release-proof smoke coverage, read-only npm-status safety tests, SchemaStore output and consistency tests, policy-pack inventory and safety tests, GitHub metadata safety and ship-score neutrality tests, AgentFlight, ProjScan, and the non-strict dogfood self-check. Use `npm run dogfood:strict` after fresh handoff or ship evidence exists, when review-gate warnings should block the handoff. maintainer-check warnings remain reviewer guidance unless the command exits non-zero. Strict public release proof remains part of approved release gates.\n\n## Commands\n\nThe package exposes two binaries:\n\n```bash\nagentloop init\nagentloopkit init\n```\n\n| Command | Purpose |\n| -------------------------------- | ------------------------------------------------------------------------------ |\n| `agentloop init` | Generate the repo harness and config |\n| `agentloop doctor` | Check setup health, agent readiness, commands, git state, and risk files; use `--advisory` for first-run preflight |\n| `agentloop create-task` | Create a scoped task contract |\n| `agentloop task ...` | List, show, pin, update, archive, and inspect task state |\n| `agentloop status` | Show active task, latest report, latest run, dirty files, and next step |\n| `agentloop next` | Print only the next recommended loop action |\n| `agentloop start` | Run a repo-native agent preflight with task, evidence, risk, proof, and impact |\n| `agentloop review-context` | Show one read-only reviewability context snapshot |\n| `agentloop context` | List handles, build context budgets and packs, and expand source truth |\n| `agentloop ready` | Check task, scope, verification, and context-budget readiness |\n| `agentloop harden` | Interrogate a task contract for unresolved soft spots before work starts |\n| `agentloop loop` | Record local loop goals, guarded runner passes, scorecards, token receipts, iteration decisions, and stop reasons |\n| `agentloop guard` | Check local drift, proof debt, and context-budget pressure |\n| `agentloop explain-diff` | Explain the current diff with local task, verification, run, and risk evidence |\n| `agentloop resume-pack` | Generate a compact local continuation brief for agents or reviewers |\n| `agentloop verify` | Run configured checks and write a verification report |\n| `agentloop ship` | Score review readiness, write a ship report, and optionally print a PR comment |\n| `agentloop prepare-pr` | Generate a PR title, grouped body, and optional GitHub comment |\n| `agentloop summarize` | Preview a deterministic reviewer summary |\n| `agentloop handoff` | Write a reviewer handoff summary |\n| `agentloop check-gates` | Check review evidence without running tests |\n| `agentloop runs --latest` | Show the newest local ship, verify, or handoff run entry |\n| `agentloop show-run ` | Show one local run ledger entry |\n| `agentloop intent ` | Show bounded newest-first run matches for one file and why |\n| `agentloop maintainer-check` | Check whether an agent-assisted PR is reviewable |\n| `agentloop artifacts` | Inventory local tasks, reports, ship reports, badges, and run evidence |\n| `agentloop artifacts --stale` | Preview capped older local evidence candidates without deleting files |\n| `agentloop upgrade-harness` | Inspect older generated guidance without overwriting local edits |\n| `agentloop report` | Write a local static HTML evidence report |\n| `agentloop badge` | Write a local SVG evidence badge |\n| `agentloop ci-summary` | Summarize CI context and existing AgentLoop evidence |\n| `agentloop release-notes` | Draft local release notes from repo evidence |\n| `agentloop release-check` | Check local release readiness without publishing |\n| `agentloop release-proof` | Check post-release proof across public release channels |\n| `agentloop npm-status` | Check npm registry status without publishing |\n| `agentloop mcp-server` | Start the read-only MCP stdio server |\n| `agentloop policy ...` | Read and compare local safety policies |\n| `agentloop schemastore` | Print the config schema catalog entry |\n| `agentloop github import` | Import explicit local GitHub issue or PR JSON |\n| `agentloop install-agent ` | Add agent-specific instructions |\n| `agentloop list-templates` | List bundled templates |\n| `agentloop completion ` | Print shell completion scripts |\n| `agentloop version` | Print the CLI version |\n\nClean up finished task contracts after verification and review-readiness evidence:\n\n```bash\nagentloop task archive --status done --dry-run\nagentloop task archive --status done\n```\n\nSee [docs/cli-reference.md](docs/cli-reference.md) for command examples, JSON modes, and safety notes.\n\nSee [docs/loop-contracts.md](docs/loop-contracts.md) for local loop contracts, readiness gates, token receipts, and dogfood loops.\n\nSee [Baseframe Suite Integration v1](docs/integrations/baseframe-suite-v1.md) for the local JSON handoff between ProjScan, AgentLoopKit, and AgentFlight.\n\nMaintainers can run a faster focused sanity set while iterating:\n\n```bash\nnpm run test:quick\nnpm run test:integration\n```\n\nRun the full suite before release:\n\n```bash\nnpm run test:release\nnpm run release-flow\n```\n\n`test:quick` runs the fast unit-oriented set. `test:integration` runs slower CLI workflow coverage. `test:release` is the full Vitest suite. `release-flow` runs the local release gate without publishing packages, creating tags, or creating GitHub releases.\n\n## Agent Setup\n\nInstall instructions for the agent you use:\n\n```bash\nagentloop install-agent codex\nagentloop install-agent claude-code\nagentloop install-agent cursor\nagentloop install-agent opencode\nagentloop install-agent gemini-cli\nagentloop install-agent github-copilot-cli\nagentloop install-agent all\nagentloop install-agent all --json --redact-paths\n```\n\nAgentLoopKit writes repo-local Markdown instructions. Re-running `install-agent` is safe: existing `.agentloop/agents/.md` files are skipped so local edits are preserved, while `AGENTS.md` is updated with any missing AgentLoopKit references. Use `--redact-paths` before sharing setup output; it hides local roots in human and JSON output without changing where files are written. When exact third-party config conventions are uncertain, it keeps the output generic instead of pretending to own another tool's setup.\n\n## Safety Model\n\nAgentLoopKit is intentionally boring:\n\n- no postinstall scripts\n- no telemetry\n- no cloud backend\n- no database\n- no API keys\n- no hidden network calls\n- no reading `.env` contents\n- no destructive actions during install\n\nEnv files are reported by path only. Verification commands run only when you explicitly run `agentloop verify`.\n\n`agentloop ship` reuses current verification evidence by default. Pass `--run-verify` when you want it to run verification as part of the readiness flow. Pass `--github-comment` when CI needs compact Markdown for a pull request comment. AgentLoopKit does not post the comment itself.\n\n`agentloop prepare-pr` groups changed files by review area, including risk-sensitive paths, source, tests, AgentLoop evidence, docs, CI, config, and other files.\n\n`agentloop start` briefs software agents with the active task, decisive preflight state, next safe command, read-first source handles, risk summary, verification freshness, context-budget impact, and source handles. `agentloop context` turns local task, diff, verification, and run evidence into a compact context budget or source-handled pack for software agents. It is read-only and explains what was included, what was omitted, why, and how to expand local source truth. `agentloop guard` adds drift, proof-debt, baseline, and context-budget checks on top of the evidence map. It is read-only unless you explicitly pass `--write-report` or `--write-baseline`. `agentloop explain-diff` shows the evidence map directly. `agentloop resume-pack` packages the same local evidence into the older compact continuation brief with context-budget estimates. They do not run tests, call external APIs, read `.env` contents, post comments, publish packages, create tags, intercept prompts, proxy provider traffic, or change task state.\n\nFor narrower evidence history, `agentloop verify --write-run` and `agentloop handoff --write-run` can add their own local run records without changing the default command behavior.\n\n`agentloop status` includes the newest local run ledger entry when `.agentloop/runs/` exists, so agents can see the latest review-readiness or verification evidence without opening every report.\nRun ledger output uses safe display paths: `.agentloop/...` for AgentLoopKit artifacts, repo-relative paths for repo files, and filenames for older outside absolute paths.\nUse `--redact-paths` with `doctor`, `task list`, `task show`, `task set`, `task status`, `task done`, `task archive`, `task clear`, `status`, `next`, `start`, `review-context`, `context`, `guard`, `explain-diff`, `resume-pack`, `check-gates`, `artifacts`, `report`, `badge`, `runs`, `show-run`, `intent`, `verify`, `summarize`, `handoff`, `ship`, `prepare-pr`, `maintainer-check`, `upgrade-harness`, `ci-summary`, `release-notes`, `schemastore`, `github import`, `install-agent`, `release-check`, or `release-proof` before pasting output into a public issue, PR, or CI log. That mode replaces local root paths with a placeholder. Default JSON output keeps raw paths for scripts unless the redaction flag is passed. `task show` applies redaction to displayed task contract content. `task list`, `artifacts`, `runs`, `show-run`, `intent`, `schemastore`, and `github import` already use repo-relative paths or catalog metadata, and accept the flag for command consistency.\n`agentloop review-context --json` gives non-MCP agents one read-only local snapshot with status, active-task risk-note count, compact evidence map, context-budget estimates, gates, policies, artifacts, recent runs, latest ship evidence, and the next action. It omits the full changed-file list by default and points agents to `agentloop context show evidence-map:current` when they need file-level detail.\n`agentloop upgrade-harness` is read-only. It tells existing users which generated guidance files need manual review after a CLI upgrade. It does not merge templates or overwrite local edits.\n`agentloop schemastore --json` prints the catalog entry for `agentloop.config.json`. Use it when preparing a SchemaStore contribution; the CLI does not submit that contribution for you. `schemastore --redact-paths` is accepted for consistency; catalog values are not local filesystem paths, so output values do not change.\n`agentloop github import --issue-json issue.json --pr-json pr.json` imports explicit local GitHub metadata into `.agentloop/github/context.json`. `review-context`, `prepare-pr`, and `maintainer-check` use that local context when it exists. Missing metadata does not block the loop. `github import --redact-paths` is accepted for consistency; metadata paths are already repo-relative, so output values do not change. The CLI does not call GitHub APIs, read tokens, or run `gh`.\n`agentloop release-proof` checks post-release evidence for npm, GitHub Releases, GitHub Marketplace, GHCR, and MCP Registry. Use `--only ` to re-check one channel. It can query public metadata or read captured JSON files that you pass explicitly. It does not publish, tag, upload, post comments, or read tokens.\nShell completions include fixed values for task types, task-list status filters, status transitions, the `done` archive status, agent names, policy subcommands, completion shells, artifact types, badge sources, `summarize` and `handoff` formats, and `release-proof --only` channels.\n\n## More Docs\n\n- [Getting started](docs/getting-started.md)\n- [CLI reference](docs/cli-reference.md)\n- [Upgrading existing repos](docs/upgrading-existing-repos.md)\n- [Configuration](docs/configuration.md)\n- [Task contracts](docs/task-contracts.md)\n- [Research tasks](docs/research.md)\n- [AgentLoop Context Contract](docs/context.md)\n- [Evidence map and resume packs](docs/evidence-map.md)\n- [Verification reports](docs/verification-reports.md)\n- [Status and next action](docs/status.md)\n- [Gate checks](docs/check-gates.md)\n- [HTML reports](docs/html-reports.md)\n- [PR summaries and handoffs](docs/pr-summaries.md)\n- [Policies](docs/policies.md)\n- [SchemaStore support](docs/schemastore.md)\n- [GitHub metadata import](docs/github-metadata.md)\n- [Real-repo trials](docs/real-repo-trials.md)\n- [Release proof](docs/release-proof.md)\n- [MCP server](docs/mcp.md)\n- [Template and harness upgrades](docs/template-migrations.md)\n- [GitHub Actions and Marketplace Action](docs/github-actions.md)\n- [Distribution channels](docs/distribution-channels.md)\n- [Comparison](docs/comparison.md)\n\n## Examples\n\nSee `examples/` for sample generated harnesses and CI recipes:\n\n- [End-to-end workflow](examples/end-to-end/README.md)\n- [Bugfix PR](examples/bugfix-pr/README.md)\n- [Next.js app](examples/nextjs-app/README.md)\n- [Node API](examples/node-api/README.md)\n- [Python service](examples/python-service/README.md)\n- [Docs-only repo](examples/docs-only/README.md)\n- [Empty repo](examples/empty-repo/README.md)\n- [GitHub Actions](examples/github-actions/README.md)\n- [GitLab CI](examples/gitlab-ci/README.md)\n- [Buildkite](examples/buildkite/README.md)\n- [Security review](examples/security-review/README.md)\n- [Dependency upgrade](examples/dependency-upgrade/README.md)\n\nSee [docs/stack-recipes.md](docs/stack-recipes.md) for Next.js, React/Vite, Remix, SvelteKit, Node API, Django, FastAPI, Python, docs-only, empty-repo, and monorepo verification recipes.\n\n## Compared With Plain AGENTS.md\n\n`AGENTS.md` gives instructions. AgentLoopKit adds process artifacts: task contracts, gates, policies, verification reports, PR summaries, and rollback notes.\n\nThe result is easier to review because the work produces evidence, not only code.\n\n## Compared With Prompt Collections\n\nPrompt collections help an agent respond better. AgentLoopKit gives the repository a standing workflow that compatible agents can read and follow.\n\n## Compared With Superpowers\n\nSuperpowers is a broader agent methodology and skills system. AgentLoopKit focuses on repo-level engineering loops, task contracts, verification evidence, and handoff artifacts.\n\nThey can be complementary. You can use AgentLoopKit alongside Superpowers. AgentLoopKit has no affiliation with Superpowers.\n\n## Stability\n\nStarting at 1.0, AgentLoopKit's shipped surface — CLI commands and flags,\n`agentloop.config.json`, the MCP tool surface, `--json` output shapes, exit\ncodes, and the generated harness format — is a committed public contract\nunder [SemVer](https://semver.org/). Build CI, an agent workflow, or an\nintegration on it: a 1.x release will not break you.\n\nSee [`docs/stability.md`](docs/stability.md) for the full contract and\ncommand reference, and [`docs/versioning.md`](docs/versioning.md) for the\nSemVer promise, deprecation policy, and experimental-tier rules.\n\nUpgrading from a pre-1.0 install? Run `agentloop upgrade-harness` to check\nyour generated files against the current format.\n\n## Contributing\n\nContributor setup:\n\n```bash\ngit clone https://github.com/abhiyoheswaran1/agentloopkit\ncd agentloopkit\npnpm install\npnpm test\npnpm build\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for local setup and PR expectations.\n\n## License\n\nMIT.\n", "bytes": 36607, "sha": "df18ff2465bc4148c9ca33c173da1636df2622d06b4fd8fee8d6502c96e8be90", "repo_slug": "abhiyoheswaran1/agentloopkit", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_abhiyoheswaran1_agentloopkit_a05164f2/readme" }