agentloopkit 0.1.0 → 0.24.0

package/dist/schema/agentloop.config.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentloopkit.dev/schema/agentloop.config.schema.json",
+  "$id": "https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/schema/agentloop.config.schema.json",
   "title": "AgentLoopKit Configuration",
   "type": "object",
   "additionalProperties": false,

package/dist/templates/agents/claude-code.md

@@ -7,6 +7,12 @@ Before editing:
 - Read AGENTS.md and AGENTLOOP.md.
 - Read harness files under .agentloop/harness/.
 - Check .agentloop/tasks/ for current work.
+- Run `agentloop task list` when current work is unclear.
+- Run `agentloop task show <path>` before implementing a selected task.
+- Run `agentloop task status <path> in-progress` when implementation starts.
+- Run `agentloop task archive <path>` only after verification and handoff are complete.
+- Run `agentloop policy list`, `agentloop policy show <policy>`, and `agentloop policy status` before risky edits.
+- Run `agentloop check-gates` before stopping to check review evidence.
 
 Rules:
 

package/dist/templates/agents/codex.md

@@ -7,6 +7,12 @@ Before editing:
 - Read AGENTS.md.
 - Read AGENTLOOP.md.
 - Check .agentloop/tasks/ for the active task contract.
+- Run `agentloop task list` when the active task is unclear.
+- Run `agentloop task show <path>` before implementing a selected task.
+- Run `agentloop task status <path> in-progress` when implementation starts.
+- Run `agentloop task archive <path>` only after verification and handoff are complete.
+- Run `agentloop policy list`, `agentloop policy show <policy>`, and `agentloop policy status` before risky edits.
+- Run `agentloop check-gates` before stopping to check review evidence.
 - Review .agentloop/harness/commands.md.
 
 Work loop:

package/dist/templates/agents/cursor.md

@@ -6,6 +6,12 @@ Before editing:
 
 - Read AGENTS.md and AGENTLOOP.md.
 - Use the active task contract when present.
+- Run `agentloop task list` when several task contracts exist.
+- Run `agentloop task show <path>` before implementing a selected task.
+- Run `agentloop task status <path> in-progress` when implementation starts.
+- Run `agentloop task archive <path>` only after verification and handoff are complete.
+- Run `agentloop policy list`, `agentloop policy show <policy>`, and `agentloop policy status` before risky edits.
+- Run `agentloop check-gates` before stopping to check review evidence.
 - Keep diffs focused on acceptance criteria.
 
 Verification:

package/dist/templates/agents/gemini-cli.md

@@ -8,6 +8,12 @@ Before editing:
 - Read AGENTLOOP.md.
 - Read .agentloop/harness/commands.md.
 - Check .agentloop/tasks/ for active work.
+- Run `agentloop task list` when active work is unclear.
+- Run `agentloop task show <path>` before implementing a selected task.
+- Run `agentloop task status <path> in-progress` when implementation starts.
+- Run `agentloop task archive <path>` only after verification and handoff are complete.
+- Run `agentloop policy list`, `agentloop policy show <policy>`, and `agentloop policy status` before risky edits.
+- Run `agentloop check-gates` before stopping to check review evidence.
 
 Rules:
 

package/dist/templates/agents/generic.md

@@ -7,6 +7,12 @@ Before editing:
 - Read AGENTS.md.
 - Read AGENTLOOP.md.
 - Check .agentloop/tasks/.
+- Run `agentloop task list` when several task contracts exist.
+- Run `agentloop task show <path>` before implementing a selected task.
+- Run `agentloop task status <path> in-progress` when implementation starts.
+- Run `agentloop task archive <path>` only after verification and handoff are complete.
+- Run `agentloop policy list`, `agentloop policy show <policy>`, and `agentloop policy status` before risky edits.
+- Run `agentloop check-gates` before stopping to check review evidence.
 
 Loop:
 

package/dist/templates/agents/github-copilot-cli.md

@@ -7,6 +7,12 @@ Before editing:
 - Read AGENTS.md.
 - Read AGENTLOOP.md.
 - Check task contracts in .agentloop/tasks/.
+- Run `agentloop task list` when current work is unclear.
+- Run `agentloop task show <path>` before implementing a selected task.
+- Run `agentloop task status <path> in-progress` when implementation starts.
+- Run `agentloop task archive <path>` only after verification and handoff are complete.
+- Run `agentloop policy list`, `agentloop policy show <policy>`, and `agentloop policy status` before risky edits.
+- Run `agentloop check-gates` before stopping to check review evidence.
 
 Rules:
 

package/dist/templates/agents/opencode.md

@@ -7,6 +7,12 @@ Before editing:
 - Read AGENTS.md.
 - Read AGENTLOOP.md.
 - Check .agentloop/tasks/.
+- Run `agentloop task list` when current work is unclear.
+- Run `agentloop task show <path>` before implementing a selected task.
+- Run `agentloop task status <path> in-progress` when implementation starts.
+- Run `agentloop task archive <path>` only after verification and handoff are complete.
+- Run `agentloop policy list`, `agentloop policy show <policy>`, and `agentloop policy status` before risky edits.
+- Run `agentloop check-gates` before stopping to check review evidence.
 
 Rules:
 

package/dist/templates/harness/commands.md

@@ -10,7 +10,48 @@ Detected during AgentLoopKit init:
 
 Rules:
 
+- Use `agentloop task list` to inspect task contracts before pinning one.
+- Use `agentloop task show <path>` to read a task contract without changing active state.
+- Use `agentloop task set <path>` when the active task is ambiguous.
+- Use `agentloop task status <path> <status>` to update task state without hand-editing Markdown.
+- Use `agentloop task archive <path>` only after verification and handoff are complete.
+- Use `agentloop status` to inspect active task, latest report, dirty files, and next action.
+- Use `agentloop next` when you only need the next recommended loop command.
+- Use `agentloop policy list`, `agentloop policy show <policy>`, and `agentloop policy status` to inspect local safety guidance and template drift before risky edits.
+- Follow local `.agentloop/policies/*.md` files as repo policy. Treat `modified` as a reviewed local rule, not an error.
+- Use `agentloop check-gates` to check task, verification, handoff, harness, policy, and git evidence before review.
+- Use `agentloop check-gates --strict` in CI when warning gates should fail.
+- Use `agentloop report` after verification and handoff when reviewers need one local HTML evidence artifact.
+- Use `agentloop badge` when reviewers or CI need a local SVG evidence badge.
+- Use `agentloop ci-summary --write` in CI when reviewers need a compact provenance and evidence summary.
+- Use `agentloop release-notes --write` before a release when reviewers need local release-note evidence.
+- Use `agentloop npm-status` after release attempts to check whether npm latest matches local package metadata.
+- Use `agentloop npm-status --expect-current` as a post-publish smoke check. It never publishes or reads credentials.
 - Run targeted checks while developing.
 - Run configured verification before claiming completion.
 - If a command fails, report the failure and fix it when reasonable.
 - If a command is not configured, say so in the handoff.
+
+## CI Usage
+
+Use `agentloop check-gates --strict` in CI after task, verification, and handoff evidence exists. If CI generates reports and handoffs, upload `.agentloop/reports/*.md`, `.agentloop/reports/*.html`, `.agentloop/reports/*.svg`, and `.agentloop/handoffs/*.md` as build artifacts instead of committing them automatically.
+
+When `agentloop verify` runs in GitHub Actions, the verification report records allowlisted CI provenance fields such as workflow, event, ref, commit, run URL, and run attempt. It does not dump arbitrary environment variables.
+
+Use `agentloop ci-summary --write` after verification and handoff when CI should upload one compact Markdown summary of CI provenance, AgentLoop evidence, and gate status. It does not run checks or replace the verification report.
+
+Use `agentloop release-notes --write` after verification when a release workflow needs a local release-note draft from changelog, git, task, verification, and CI-summary evidence. It does not create tags, publish packages, call provider APIs, or read tokens.
+
+Use `agentloop npm-status` when release docs mention npm availability. It runs `npm view` only when invoked, or reads captured registry JSON with `--registry-json`. It does not publish packages, read tokens, read `.env` files, or change package metadata.
+
+`check-gates` checks evidence. It does not prove the code is correct and does not replace review.
+
+## Monorepos
+
+If `agentloop doctor` reports workspace or monorepo markers, treat root commands as coverage clues, not proof that every package was checked.
+
+- Add package-specific verification commands to the task contract when a change is scoped to one package.
+- Prefer the repo's existing command style, such as `pnpm --filter <package> test`, `npm --workspace <package> test`, or a package-local command.
+- Run root checks when they cover the touched area.
+- In the handoff, separate root checks, package-level checks, and checks that were not run.
+- Do not claim full monorepo verification from a root-only command unless the repo documentation says that command covers all affected packages.

package/dist/templates/harness/review-checklist.md

@@ -6,4 +6,5 @@
 - [ ] Tests or documented verification cover the change.
 - [ ] Docs were updated when behavior changed.
 - [ ] Protected areas were reviewed.
+- [ ] Policy changes were reviewed when `.agentloop/policies/` changed.
 - [ ] Rollback notes are clear.

package/dist/templates/root/AGENTLOOP.md

@@ -21,6 +21,7 @@ AgentLoopKit gives coding agents a repeatable engineering loop inside this repo.
 - .agentloop/reports/: verification reports generated by `agentloop verify`.
 - .agentloop/handoffs/: PR summaries and reviewer handoffs.
 - .agentloop/harness/: repo-specific working agreement, commands, and checklists.
+- .agentloop/state.json: active task pointer created by `agentloop task set`.
 
 ## Commands Detected During Init
 
@@ -32,6 +33,10 @@ AgentLoopKit gives coding agents a repeatable engineering loop inside this repo.
 - Build: {{ buildCommand }}
 - Format: {{ formatCommand }}
 
+Use `agentloop task list` to inspect available task contracts. Use `agentloop task show <path>` to read one without changing active state. Use `agentloop task set <path>` to pin the active task when a repo has multiple contracts. Use `agentloop task status <path> <status>` to update the task contract state. Use `agentloop task archive <path>` after verification and handoff to move a finished contract into `.agentloop/tasks/archive/` without deleting it. Use `agentloop status` to inspect the active task, latest verification report, working tree state, and next suggested command. Use `agentloop next` when an agent or script only needs the next recommended loop command. Use `agentloop policy list`, `agentloop policy show <policy>`, and `agentloop policy status` to inspect local safety guidance and template drift before risky edits. Use `agentloop check-gates` before review to check task, verification, handoff, harness, policy, and git evidence. Use `agentloop check-gates --strict` in CI when warning gates should fail. Use `agentloop report` after verification and handoff when reviewers need one local HTML evidence artifact. Use `agentloop badge` when reviewers or CI need a local SVG status badge. Use `agentloop ci-summary --write` in CI when reviewers need a compact provenance and evidence summary. Use `agentloop release-notes --write` before a release when reviewers need local release-note evidence. Use `agentloop npm-status` before claiming npm availability in release notes or docs.
+
+Local files under `.agentloop/policies/` are the repo's policy source of truth. Bundled templates are comparison material. Treat `modified` policy status as a prompt to read the local rule, not as a reason to overwrite it.
+
 ## Autonomous Work
 
 Agents may work autonomously inside the task contract. They should stop and ask before changing protected areas, adding dependencies, introducing breaking public APIs, or taking destructive actions.

package/dist/templates/root/AGENTS.md

@@ -8,6 +8,21 @@ Before changing code:
 
 - Read AGENTLOOP.md.
 - Check .agentloop/tasks/ for an active task contract.
+- Use `agentloop task list` to inspect available task contracts before choosing one.
+- Use `agentloop task show <path>` to read a task contract without changing active state.
+- Use `agentloop task set <path>` when the active task is ambiguous.
+- Use `agentloop task status <path> <status>` to update task state without hand-editing Markdown.
+- Use `agentloop task archive <path>` only after verification and handoff are complete.
+- Run `agentloop status` when you need the current task, verification, dirty-file, and next-action state.
+- Run `agentloop next` when you only need the next recommended loop command.
+- Run `agentloop policy list`, `agentloop policy show <policy>`, and `agentloop policy status` before touching security, dependency, database, git, public API, or secret-handling areas.
+- Treat local `.agentloop/policies/*.md` files as the repo's safety guidance. A `modified` policy is a local decision to review, not a failure.
+- Run `agentloop check-gates` before stopping to check review evidence.
+- Run `agentloop report` after verification and handoff when a local HTML evidence artifact helps review.
+- Run `agentloop badge` when a local SVG evidence badge helps review or CI artifact uploads.
+- Run `agentloop ci-summary --write` in CI when reviewers need a compact provenance and evidence summary.
+- Run `agentloop release-notes --write` before a release when reviewers need local release-note evidence.
+- Run `agentloop npm-status` before claiming npm availability in release notes or docs.
 - Follow the Specify, Constrain, Plan, Implement, Verify, Review, Handoff loop.
 - Keep changes small and tied to the task contract.
 - Do not run destructive git or filesystem commands unless the user asks for them.

package/dist/templates/root/agentloop-directory-readme.md

@@ -2,6 +2,8 @@
 
 This directory contains repo-local engineering loop artifacts for coding agents and reviewers.
 
+`manifest.json` records the AgentLoopKit template generation used to create this harness. `agentloop doctor` reads it and warns when the local harness is missing template metadata, older than the current CLI, invalid, or newer than the CLI supports.
+
 ## Start Here
 
 1. Read `../AGENTS.md`.
@@ -10,23 +12,107 @@ This directory contains repo-local engineering loop artifacts for coding agents
 
 ```bash
 agentloop create-task --title "Describe the next focused change" --type feature
+agentloop task list
+agentloop task show .agentloop/tasks/<task-file>.md
+agentloop task set .agentloop/tasks/<task-file>.md
+agentloop task status .agentloop/tasks/<task-file>.md in-progress
+agentloop task archive .agentloop/tasks/<task-file>.md
+```
+
+Archive only after verification and handoff. The archive command moves one named Markdown file into `.agentloop/tasks/archive/` and keeps normal task lists focused.
+
+4. Check current loop state:
+
+```bash
+agentloop status
+agentloop next
 ```
 
-4. Run verification when work is ready:
+5. Inspect safety policies when the task touches protected areas:
+
+```bash
+agentloop policy list
+agentloop policy show security
+agentloop policy status
+```
+
+Local policy files are repo guidance. If `policy status` reports `modified`, read the local file and follow the repo-specific rule. Do not overwrite customized policy text just to match the bundled template.
+
+6. Run verification when work is ready:
 
 ```bash
 agentloop verify
 ```
 
-5. Generate a reviewer handoff:
+7. Generate a reviewer handoff:
+
+```bash
+agentloop handoff
+```
+
+8. Optional: write a local HTML evidence report:
+
+```bash
+agentloop report
+```
+
+9. Optional: write a local SVG evidence badge:
+
+```bash
+agentloop badge
+agentloop badge --source gates
+```
+
+10. Optional: write a CI summary:
+
+```bash
+agentloop ci-summary
+agentloop ci-summary --write
+```
+
+11. Optional: draft release notes:
+
+```bash
+agentloop release-notes
+agentloop release-notes --write
+```
+
+12. Optional: check npm registry catch-up:
+
+```bash
+agentloop npm-status
+agentloop npm-status --expect-current
+```
+
+13. Check review gates:
 
 ```bash
-agentloop summarize --write
+agentloop check-gates
+agentloop check-gates --strict
 ```
 
+`check-gates` inspects local evidence. It does not run tests or call an LLM.
+`report` reads local evidence and writes one static HTML file under `reports/`.
+`badge` reads local evidence and writes SVG files under `reports/`.
+`ci-summary` reads allowlisted CI provenance and local evidence, then writes Markdown under `reports/` when `--write` is passed.
+`release-notes` reads local package, changelog, git, task, verification, and CI-summary evidence, then writes Markdown under `handoffs/` when `--write` is passed.
+`npm-status` compares local package metadata with npm registry metadata. It does not publish packages or read credentials.
+Use `--strict` in CI when warning gates should fail.
+
+CI can either check committed AgentLoop evidence or generate reports and handoffs as build artifacts. Do not let CI commit generated files unless maintainers explicitly want that behavior.
+
+When GitHub Actions runs `agentloop verify`, the report records allowlisted CI provenance fields such as workflow, event, ref, commit, run URL, and run attempt. AgentLoopKit does not print arbitrary environment variables.
+
+Use `agentloop ci-summary --write` after verification and handoff when CI should upload one compact Markdown summary. It does not run checks or replace the verification report.
+
+Use `agentloop release-notes --write` before a release when CI or maintainers need a local release-note draft. It does not create tags, publish packages, call provider APIs, or read tokens.
+
+Use `agentloop npm-status --expect-current` after npm publish when CI or maintainers need proof that npm latest matches local package metadata. It does not publish packages, read tokens, read `.env` files, or change package metadata.
+
 ## Directories
 
 - `loops/`: task-specific workflows
+- `manifest.json`: generated template version metadata
 - `gates/`: pass/fail checklists
 - `policies/`: safety rules
 - `tasks/`: task contracts
@@ -34,3 +120,17 @@ agentloop summarize --write
 - `handoffs/`: PR summaries and reviewer briefs
 - `agents/`: agent-specific instructions
 - `harness/`: repo working agreement and commands
+
+## Monorepo Notes
+
+When this repository has workspace markers, use both root and package-level checks as needed. Put package-specific verification commands in the task contract so agents and reviewers can see what the change requires.
+
+Examples:
+
+```bash
+pnpm --filter <package> test
+npm --workspace <package> test
+cd packages/<name> && npm test
+```
+
+Root checks are useful when they cover the touched package. If they do not, say what was not verified in the handoff.

package/dist/templates/root/agentloop.config.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://agentloopkit.dev/schema/agentloop.config.schema.json",
+  "$schema": "https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/schema/agentloop.config.schema.json",
   "version": 1,
   "project": {
     "name": "{{ projectName }}",

package/dist/templates/tasks/README.md

@@ -4,6 +4,32 @@ Create task contracts with:
 
 ```bash
 agentloop create-task
+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"
 ```
 
 Task contracts turn fuzzy requests into scoped engineering work. A good contract names the desired outcome, constraints, non-goals, likely files, files not to touch, acceptance criteria, verification commands, and rollback notes.
+
+In monorepos, include package-specific verification commands when root commands do not prove the touched package. Examples include `pnpm --filter <package> test`, `npm --workspace <package> test`, or a package-local command from inside `packages/<name>`.
+
+When several task contracts exist, pin the one in progress:
+
+```bash
+agentloop task list
+agentloop task show .agentloop/tasks/<task-file>.md
+agentloop task set .agentloop/tasks/<task-file>.md
+agentloop task status .agentloop/tasks/<task-file>.md in-progress
+agentloop task archive .agentloop/tasks/<task-file>.md
+```
+
+`agentloop task list --json` is safe for agents and scripts. It reads task files and does not create or update `.agentloop/state.json`.
+`agentloop create-task --json` returns the created task path and Markdown content for scripts and agents.
+`agentloop task show --json` returns one task contract's metadata and Markdown content without changing active state.
+`agentloop task status --json` updates only the task contract's `- Status:` line. Supported statuses are `proposed`, `in-progress`, `blocked`, `review`, and `done`.
+`agentloop task archive --json` moves one named task contract into `.agentloop/tasks/archive/` after verification and handoff. It preserves the Markdown file and refuses to overwrite an existing archive file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentloopkit",
-  "version": "0.1.0",
+  "version": "0.24.0",
   "description": "A drop-in engineering loop for coding agents.",
   "type": "module",
   "bin": {
@@ -45,10 +45,11 @@
     "dev": "tsx src/cli/index.ts",
     "test": "vitest run",
     "test:watch": "vitest",
+    "check:links": "tsx scripts/check-markdown-links.ts",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "format": "prettier --write .",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+    "prepublishOnly": "node scripts/prepublish-check.mjs && npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
     "commander": "^14.0.2",

package/schema/agentloop.config.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentloopkit.dev/schema/agentloop.config.schema.json",
+  "$id": "https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/schema/agentloop.config.schema.json",
   "title": "AgentLoopKit Configuration",
   "type": "object",
   "additionalProperties": false,