@vamsiivarmaa/proofloop 0.0.0-stage → 1.0.0-rc.6

package/examples/protocols/fastapi-feature.yaml

@@ -0,0 +1,28 @@
+# Python/FastAPI feature protocol: migrations and security scans are required earlier than the built-in feature protocol.
+schemaVersion: 1
+id: fastapi-feature
+version: 1.0.0
+title: FastAPI feature protocol
+description: API feature work with contract, migration and dependency-scan gates.
+engine: ">=0.7.0"
+mode: existing-repo
+defaultRisk: medium
+retry: { maxRepairAttempts: 3, stopOnIdenticalFailure: true }
+requiredArtifacts: [intent-brief, impact-map, acceptance-criteria, implementation-plan, test-plan, approved-plan-record]
+gates:
+  - { id: lint, kind: lint, required: true }
+  - { id: typecheck, kind: typecheck, required: true }
+  - { id: unit, kind: unit, required: true }
+  - { id: integration, kind: integration, required: true }
+  - { id: migration, kind: migration, required: true, minRisk: medium }
+  - { id: security-scan, kind: security-scan, required: true, minRisk: medium }
+phases:
+  - { id: intake, title: Classify the request }
+  - { id: reconnaissance, title: "Inspect routers, schemas and migrations" }
+  - { id: plan, title: Plan endpoint contract and tests }
+  - { id: approval, title: Human plan approval }
+  - { id: implementation, title: Implement }
+  - { id: verification, title: Run gates, gates: [lint, typecheck, unit, integration, migration, security-scan] }
+  - { id: repair, title: Bounded repair loop }
+  - { id: review, title: Independent review }
+  - { id: delivery, title: Open the pull request with evidence }

package/examples/protocols/generic-change.yaml

@@ -0,0 +1,23 @@
+# Generic starting point for any repository: copy to .proofloop/protocols/ and adjust.
+schemaVersion: 1
+id: generic-change
+version: 1.0.0
+title: Generic change
+description: Plan, approve, implement, run whatever checks the repository has.
+engine: ">=0.7.0"
+mode: existing-repo
+defaultRisk: medium
+retry: { maxRepairAttempts: 3, stopOnIdenticalFailure: true }
+requiredArtifacts: [intent-brief, acceptance-criteria, implementation-plan, approved-plan-record]
+gates:
+  - { id: lint, kind: lint, required: true }
+  - { id: unit, kind: unit, required: true }
+  - { id: build, kind: build, required: true }
+phases:
+  - { id: intake, title: Capture the request }
+  - { id: plan, title: Plan }
+  - { id: approval, title: Human plan approval }
+  - { id: implementation, title: Implement }
+  - { id: verification, title: Run gates, gates: [lint, unit, build] }
+  - { id: repair, title: Bounded repair loop }
+  - { id: delivery, title: Open the pull request with evidence }

package/examples/protocols/nextjs-feature.yaml

@@ -0,0 +1,29 @@
+# Next.js feature protocol: browser journeys are required from medium risk.
+schemaVersion: 1
+id: nextjs-feature
+version: 1.0.0
+title: Next.js feature protocol
+description: Feature work in a Next.js app; typecheck, unit tests and a Playwright journey gate every UI change.
+engine: ">=0.7.0"
+mode: existing-repo
+defaultRisk: medium
+retry: { maxRepairAttempts: 3, stopOnIdenticalFailure: true }
+requiredArtifacts: [intent-brief, impact-map, acceptance-criteria, implementation-plan, test-plan, approved-plan-record]
+personas: [ordinary-user, impatient-user, unauthorized-user, accessibility]
+gates:
+  - { id: lint, kind: lint, required: true }
+  - { id: typecheck, kind: typecheck, required: true }
+  - { id: unit, kind: unit, required: true }
+  - { id: build, kind: build, required: true }
+  - { id: browser, kind: browser, required: true, minRisk: medium }
+  - { id: security-scan, kind: security-scan, required: true, minRisk: high }
+phases:
+  - { id: intake, title: Classify the request }
+  - { id: reconnaissance, title: "Inspect routes, server actions and components" }
+  - { id: plan, title: Plan UI states and tests }
+  - { id: approval, title: Human plan approval }
+  - { id: implementation, title: Implement in an isolated worktree }
+  - { id: verification, title: Run gates, gates: [lint, typecheck, unit, build, browser, security-scan] }
+  - { id: repair, title: Bounded repair loop }
+  - { id: review, title: Independent review }
+  - { id: delivery, title: Open the pull request with evidence }

package/examples/protocols/node-service-bugfix.yaml

@@ -0,0 +1,24 @@
+# Node service bug protocol: smaller than the built-in bug protocol, still proves the regression test fails first.
+schemaVersion: 1
+id: node-service-bugfix
+version: 1.0.0
+title: Node service bugfix
+description: Reproduce, add a regression test that fails first, fix, verify.
+engine: ">=0.7.0"
+mode: existing-repo
+defaultRisk: low
+retry: { maxRepairAttempts: 2, stopOnIdenticalFailure: true }
+requiredArtifacts: [reproduction-result, root-cause, regression-test, verification-report]
+gates:
+  - { id: regression-test, kind: unit, required: true }
+  - { id: lint, kind: lint, required: true }
+  - { id: unit, kind: unit, required: true }
+phases:
+  - { id: intake, title: Capture observed and expected behavior }
+  - { id: reconnaissance, title: Reproduce first }
+  - { id: plan, title: Smallest correct fix }
+  - { id: approval, title: Human plan approval }
+  - { id: implementation, title: Test then fix }
+  - { id: verification, title: Run gates, gates: [regression-test, lint, unit] }
+  - { id: repair, title: Bounded repair loop }
+  - { id: delivery, title: Open the pull request with evidence }

package/hooks/hooks.json

@@ -0,0 +1,37 @@
+{
+  "description": "ProofLoop guard: agents cannot change approvals or state; protected paths and critical shell commands are policy-checked. A bare \"test\" prompt starts the ProofLoop testing protocol.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit|MultiEdit|NotebookEdit|Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/proofloop",
+            "args": [
+              "hook",
+              "pre-tool-use"
+            ],
+            "timeout": 15,
+            "onFailure": "block"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/proofloop",
+            "args": [
+              "hook",
+              "user-prompt"
+            ],
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@vamsiivarmaa/proofloop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-rc.6",
+  "description": "Protocol-driven, evidence-based engineering harness and Claude Code plugin",
+  "license": "Apache-2.0",
+  "type": "module",
+  "packageManager": "pnpm@10.11.0",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "bin": {
+    "proofloop": "bin/proofloop"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage",
+    "check": "pnpm typecheck && pnpm lint && pnpm test:cov && pnpm build",
+    "prepack": "node scripts/build.mjs"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.64.1",
+    "@types/node": "^26.6.5",
+    "@vitest/coverage-v8": "^5.0.5",
+    "esbuild": "^0.28.2",
+    "eslint": "^10.13.0",
+    "tsx": "^4.23.15",
+    "typescript": "6.0.3",
+    "typescript-eslint": "^8.72.0",
+    "vitest": "^5.0.5"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vamsivarma27/proofloop.git"
+  },
+  "homepage": "https://github.com/vamsivarma27/proofloop#readme",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "agent",
+    "harness",
+    "verification",
+    "evidence",
+    "ai-coding"
+  ],
+  "files": [
+    "dist",
+    "bin",
+    "skills",
+    "agents",
+    "hooks",
+    "protocols",
+    "templates",
+    "examples",
+    ".claude-plugin",
+    "docs/assets/hero.gif",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}

package/protocols/bug.yaml

@@ -0,0 +1,31 @@
+schemaVersion: 1
+id: bug
+version: 1.0.0
+title: Bug protocol
+description: Reproduce, root-cause and fix a defect with a regression test that fails before and passes after.
+engine: ">=0.1.0"
+mode: existing-repo
+defaultRisk: medium
+retry: { maxRepairAttempts: 3, stopOnIdenticalFailure: true }
+requiredArtifacts: [reproduction-result, root-cause, blast-radius-map, regression-test, verification-report]
+gates:
+  - { id: regression-test, kind: unit, required: true, description: Regression test that failed before the fix }
+  - { id: lint, kind: lint, required: true }
+  - { id: typecheck, kind: typecheck, required: true }
+  - { id: unit, kind: unit, required: true }
+  - { id: build, kind: build, required: true }
+  - { id: integration, kind: integration, required: true, minRisk: medium }
+  - { id: browser, kind: browser, required: true, minRisk: high }
+phases:
+  - { id: intake, title: Capture observed and expected behavior }
+  - { id: clarify, title: Request missing reproduction details }
+  - { id: reconnaissance, title: Reproduce before modifying code }
+  - { id: impact, title: Trace blast radius }
+  - { id: plan, title: Plan the smallest correct fix, requiredArtifacts: [root-cause, regression-test] }
+  - { id: approval, title: Human plan approval }
+  - { id: implementation, title: Add regression test then fix }
+  - { id: verification, title: Run regression and relevant gates, gates: [regression-test, lint, typecheck, unit, build, integration, browser] }
+  - { id: repair, title: Bounded repair loop }
+  - { id: review, title: Independent fresh-context review }
+  - { id: delivery, title: Open the pull request with evidence }
+  - { id: retrospective, title: Propose harness improvements, skipped: { reason: Bug fixes rarely need harness changes; raise manually when a pattern recurs } }

package/protocols/feature.yaml

@@ -0,0 +1,34 @@
+schemaVersion: 1
+id: feature
+version: 1.0.0
+title: Feature protocol
+description: Add a user-facing capability to an existing repository with an approved plan and verified gates.
+engine: ">=0.1.0"
+mode: existing-repo
+defaultRisk: medium
+retry: { maxRepairAttempts: 3, stopOnIdenticalFailure: true }
+requiredArtifacts: [intent-brief, impact-map, acceptance-criteria, implementation-plan, dependency-graph, test-plan, approved-plan-record]
+personas: [ordinary-user, unauthorized-user]
+gates:
+  - { id: format, kind: format, required: false }
+  - { id: lint, kind: lint, required: true }
+  - { id: typecheck, kind: typecheck, required: true }
+  - { id: unit, kind: unit, required: true }
+  - { id: build, kind: build, required: true }
+  - { id: integration, kind: integration, required: true, minRisk: medium }
+  - { id: browser, kind: browser, required: true, minRisk: high }
+  - { id: security-scan, kind: security-scan, required: true, minRisk: high }
+  - { id: migration, kind: migration, required: true, minRisk: high }
+phases:
+  - { id: intake, title: Classify the request }
+  - { id: clarify, title: Clarify intent and constraints }
+  - { id: reconnaissance, title: Inspect repository and conventions }
+  - { id: impact, title: Map impact and risk }
+  - { id: plan, title: Plan and design tests, requiredArtifacts: [implementation-plan, test-plan] }
+  - { id: approval, title: Human plan approval, requiredArtifacts: [approved-plan-record] }
+  - { id: implementation, title: Implement in an isolated worktree }
+  - { id: verification, title: Run required gates, gates: [format, lint, typecheck, unit, build, integration, browser, security-scan, migration] }
+  - { id: repair, title: Bounded repair loop }
+  - { id: review, title: Independent fresh-context review }
+  - { id: delivery, title: Open the pull request with evidence }
+  - { id: retrospective, title: Propose harness improvements }

package/protocols/idea-to-product.yaml

@@ -0,0 +1,26 @@
+schemaVersion: 1
+id: idea-to-product
+version: 1.0.0
+title: Idea-to-Product protocol
+description: Discovery and blueprint with cited research and visible assumptions, then approved roadmap issues.
+engine: ">=0.2.0"
+mode: idea-to-product
+defaultRisk: medium
+retry: { maxRepairAttempts: 2, stopOnIdenticalFailure: true }
+requiredArtifacts: [product-blueprint, risk-register, roadmap, adr]
+gates:
+  - { id: blueprint-valid, kind: custom, required: true, description: "Blueprint schema, citations and DAG validate" }
+  - { id: assumptions-visible, kind: custom, required: true }
+phases:
+  - { id: intake, title: Capture the business outcome }
+  - { id: clarify, title: Adaptive one-question-at-a-time interview }
+  - { id: reconnaissance, title: "Research with cited, dated sources" }
+  - { id: impact, title: "Separate facts, assumptions and recommendations" }
+  - { id: plan, title: "Personas, journeys, MVP, stack, data and API, roadmap", requiredArtifacts: [product-blueprint, roadmap] }
+  - { id: approval, title: Human blueprint approval before bulk issue creation }
+  - { id: implementation, title: Create the GitHub hierarchy and first milestone }
+  - { id: verification, title: Validate the blueprint and DAG, gates: [blueprint-valid, assumptions-visible] }
+  - { id: repair, title: Fix validation errors }
+  - { id: review, title: Review assumptions and stack against requirements }
+  - { id: delivery, title: Publish roadmap issues }
+  - { id: retrospective, title: Record decisions }

package/protocols/performance.yaml

@@ -0,0 +1,30 @@
+schemaVersion: 1
+id: performance
+version: 1.0.0
+title: Performance protocol
+description: Measure a baseline, change one thing, and report before/after against a stated target.
+engine: ">=0.1.0"
+mode: existing-repo
+defaultRisk: medium
+retry: { maxRepairAttempts: 3, stopOnIdenticalFailure: true }
+requiredArtifacts: [baseline, measurement-methodology, profiler-evidence, change-hypothesis, before-after-result, regression-checks]
+gates:
+  - { id: baseline-recorded, kind: performance, required: true, description: Baseline with workload and target exists before optimizing }
+  - { id: before-after, kind: performance, required: true }
+  - { id: load, kind: load, required: false, minRisk: high }
+  - { id: lint, kind: lint, required: true }
+  - { id: unit, kind: unit, required: true }
+  - { id: build, kind: build, required: true }
+phases:
+  - { id: intake, title: "Capture workload, target and environment" }
+  - { id: clarify, title: Confirm target and acceptable trade-offs }
+  - { id: reconnaissance, title: Profile and inspect queries }
+  - { id: impact, title: "Separate model, app, database, network and render time" }
+  - { id: plan, title: Plan one measured change, requiredArtifacts: [baseline, change-hypothesis] }
+  - { id: approval, title: Human plan approval }
+  - { id: implementation, title: Apply the change }
+  - { id: verification, title: Re-measure and run regression gates, gates: [baseline-recorded, before-after, load, lint, unit, build] }
+  - { id: repair, title: Bounded repair loop }
+  - { id: review, title: Independent review of methodology }
+  - { id: delivery, title: Report trade-offs and whether the target was met }
+  - { id: retrospective, title: Propose harness improvements }

package/protocols/refactor.yaml

@@ -0,0 +1,31 @@
+schemaVersion: 1
+id: refactor
+version: 1.0.0
+title: Refactor protocol
+description: Change structure without changing behavior; detect contract, export, schema and config drift.
+engine: ">=0.1.0"
+mode: existing-repo
+defaultRisk: medium
+retry: { maxRepairAttempts: 3, stopOnIdenticalFailure: true }
+requiredArtifacts: [behavior-baseline, architecture-target, scope, regression-plan]
+gates:
+  - { id: baseline-green, kind: unit, required: true, description: Tests green before the refactor starts }
+  - { id: lint, kind: lint, required: true }
+  - { id: typecheck, kind: typecheck, required: true }
+  - { id: unit, kind: unit, required: true }
+  - { id: build, kind: build, required: true }
+  - { id: integration, kind: integration, required: true, minRisk: medium }
+  - { id: contract-drift, kind: custom, required: true, description: "Public exports, API contracts, schema and config unchanged" }
+phases:
+  - { id: intake, title: Capture refactor goal and scope }
+  - { id: clarify, title: Confirm behavior must not change }
+  - { id: reconnaissance, title: Record behavior baseline }
+  - { id: impact, title: Map public surface }
+  - { id: plan, title: Plan incremental steps }
+  - { id: approval, title: Human plan approval }
+  - { id: implementation, title: Refactor in small steps }
+  - { id: verification, title: Prove behavior preserved, gates: [baseline-green, lint, typecheck, unit, build, integration, contract-drift] }
+  - { id: repair, title: Bounded repair loop }
+  - { id: review, title: Independent review }
+  - { id: delivery, title: Open the pull request with evidence }
+  - { id: retrospective, title: Propose harness improvements }

package/protocols/security.yaml

@@ -0,0 +1,29 @@
+schemaVersion: 1
+id: security
+version: 1.0.0
+title: Security protocol
+description: Threat-model, test negative paths, scan dependencies; findings cannot be dismissed by an LLM alone.
+engine: ">=0.1.0"
+mode: existing-repo
+defaultRisk: high
+retry: { maxRepairAttempts: 3, stopOnIdenticalFailure: true }
+requiredArtifacts: [threat-model, trust-boundaries, authorization-checks, negative-tests, scan-results, remediation-plan]
+gates:
+  - { id: lint, kind: lint, required: true }
+  - { id: unit, kind: unit, required: true }
+  - { id: build, kind: build, required: true }
+  - { id: negative-tests, kind: integration, required: true }
+  - { id: security-scan, kind: security-scan, required: true }
+phases:
+  - { id: intake, title: Capture the security concern }
+  - { id: clarify, title: Confirm authorization and isolated environment }
+  - { id: reconnaissance, title: Map trust boundaries }
+  - { id: impact, title: Build the threat model }
+  - { id: plan, title: Plan remediation and negative tests, requiredArtifacts: [threat-model, remediation-plan] }
+  - { id: approval, title: Human plan approval }
+  - { id: implementation, title: Remediate }
+  - { id: verification, title: Run negative tests and scans, gates: [lint, unit, build, negative-tests, security-scan] }
+  - { id: repair, title: Bounded repair loop }
+  - { id: review, title: Independent security review }
+  - { id: delivery, title: Open the pull request with evidence }
+  - { id: retrospective, title: Propose harness improvements }

package/protocols/test.yaml

@@ -0,0 +1,23 @@
+schemaVersion: 1
+id: test
+version: 1.0.0
+title: Test protocol
+description: "Full project test on the current commit: static checks, unit and regression suite, integration, browser journeys with personas, security scan, migration, compared with the base branch."
+engine: ">=1.0.0"
+mode: existing-repo
+defaultRisk: medium
+retry: { maxRepairAttempts: 0, stopOnIdenticalFailure: true }
+personas: [ordinary-user, impatient-user, unauthorized-user, accessibility]
+gates:
+  - { id: format, kind: format, required: false }
+  - { id: lint, kind: lint, required: true }
+  - { id: typecheck, kind: typecheck, required: true }
+  - { id: unit, kind: unit, required: true }
+  - { id: build, kind: build, required: true }
+  - { id: integration, kind: integration, required: false }
+  - { id: browser, kind: browser, required: true }
+  - { id: security-scan, kind: security-scan, required: false }
+  - { id: migration, kind: migration, required: false }
+phases:
+  - { id: verification, title: "Run every applicable check on the current commit and on the base branch", gates: [format, lint, typecheck, unit, build, integration, browser, security-scan, migration] }
+  - { id: delivery, title: "Report results, regressions and bugs" }

package/protocols/troubleshooting.yaml

@@ -0,0 +1,26 @@
+schemaVersion: 1
+id: troubleshooting
+version: 1.0.0
+title: Troubleshooting protocol
+description: Read-only evidence first, ranked hypotheses, least destructive experiments, verified recovery.
+engine: ">=0.1.0"
+mode: existing-repo
+defaultRisk: medium
+retry: { maxRepairAttempts: 2, stopOnIdenticalFailure: true }
+requiredArtifacts: [timeline, observations, ranked-hypotheses, diagnostic-commands, cause-or-uncertainty, follow-up-checks]
+gates:
+  - { id: evidence-preserved, kind: custom, required: true, description: Pre-fix evidence recorded }
+  - { id: recovery-verified, kind: custom, required: true }
+phases:
+  - { id: intake, title: "Capture symptom, window and environment" }
+  - { id: clarify, title: Ask for logs and affected services }
+  - { id: reconnaissance, title: Collect read-only evidence }
+  - { id: impact, title: "Classify code, environment, credential, provider or flake" }
+  - { id: plan, title: Rank hypotheses and choose experiments }
+  - { id: approval, title: Approve any mutating remediation }
+  - { id: implementation, title: Apply remediation }
+  - { id: verification, title: Verify recovery, gates: [evidence-preserved, recovery-verified] }
+  - { id: repair, title: Bounded repair loop }
+  - { id: review, title: Review conclusion against evidence, skipped: { reason: Evidence ledger is checked by the engine; reviewer is optional for read-only diagnosis } }
+  - { id: delivery, title: Report cause or explicit uncertainty }
+  - { id: retrospective, title: Propose harness improvements }

package/protocols/verify.yaml

@@ -0,0 +1,18 @@
+schemaVersion: 1
+id: verify
+version: 1.0.0
+title: Verify protocol
+description: Run the repository's detected quality gates against the current commit and report evidence.
+engine: ">=0.1.0"
+mode: existing-repo
+defaultRisk: low
+retry: { maxRepairAttempts: 0, stopOnIdenticalFailure: true }
+gates:
+  - { id: format, kind: format, required: false }
+  - { id: lint, kind: lint, required: true }
+  - { id: typecheck, kind: typecheck, required: true }
+  - { id: unit, kind: unit, required: true }
+  - { id: build, kind: build, required: true }
+phases:
+  - { id: verification, title: Run gates against the current commit, gates: [format, lint, typecheck, unit, build] }
+  - { id: delivery, title: Report evidence }

package/skills/approve/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: approve
+description: Record YOUR approval of a ProofLoop plan. Humans only.
+argument-hint: "<run-id>"
+disable-model-invocation: true
+---
+
+Run `proofloop approve $ARGUMENTS` (no hash) to display the plan and its hash, and show the user the plan in full. If the user already told you to approve this run, run `proofloop approve $ARGUMENTS --plan-hash <hash> --yes` right away; the tool-permission prompt is the one human confirmation, so do not ask again in chat. Otherwise stop after showing the plan and let them decide. Then tell the user to run `proofloop run <run-id>` (in the background) to start execution.

package/skills/audit/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: audit
+description: When the user says "audit" (optionally with a user count and p95/p99 targets, e.g. "audit for 5000 users, p99 under 500ms"), audit the project for scale and system design - measured latency percentiles under load, static scalability findings, and a checklist-driven design review.
+argument-hint: "[--users 2000] [--p95 300] [--p99 800] [--error-rate 0.01] [--path /api/x]"
+allowed-tools: Bash(proofloop *)
+---
+
+Do not ask first; run the audit. Defaults if the user gave no numbers: 2000 users, p95 300 ms, p99 800 ms, errors 1% - say you used defaults.
+
+1. Run in the foreground with the Bash timeout at 600000 ms:
+
+```
+proofloop audit $ARGUMENTS
+```
+
+It sizes the load (users -> concurrent users, rps, in-flight requests, with printed assumptions), scans for scalability smells (unbounded queries, N+1, no timeouts, sync I/O, process-local state, retries without backoff), runs the repository's load test if there is one, and starts the app (`app.start` / `app.url` in `.proofloop/config.json`) to probe each `--path` for p50/p95/p99 and error rate.
+
+2. Report the status exactly: `measured-ok`, `violations`, `needs-review` or `not-measured`. **Never say the app "can handle N users".** The probe is one machine; say what it measured against which targets. If nothing was measured (no app start command, no load test), say so and offer to add a k6 script or the app start config through `/proofloop:feature`.
+3. Then do the design review yourself, read-only: run `proofloop audit --checklist`, read the code, and answer each area (capacity, data-access, caching, concurrency, resilience, scalability, failure-modes, observability) with `file:line` evidence, or say "no evidence found". Mark each answer reviewed, not measured. Check the static findings against the code and say which are real.
+4. Offer fixes as a normal change (`/proofloop:feature` or `/proofloop:performance`) so they get a plan with design decisions, an approved plan hash, and a load check. Do not change code during an audit.

package/skills/bug/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: bug
+description: Run the ProofLoop bug protocol: reproduce first, prove the regression test fails before the fix, then fix and verify.
+argument-hint: "[observed vs expected behavior]"
+disable-model-invocation: true
+allowed-tools: Bash(proofloop *)
+---
+
+Run:
+
+```
+proofloop bug "$ARGUMENTS"
+```
+
+Then show the user the whole plan from the output (at a glance, tasks, acceptance criteria, commands) and the "Gate plan preview", plus any warnings. **Do not approve anything yourself.** Tell them to review and, when satisfied, run `/proofloop:approve <run-id>`. Never describe work as passing unless a gate result in the output says PASS. If the output says BLOCKED, report the reason and evidence path verbatim. If the bug could not be reproduced, ask the user for the missing details instead of proposing a fix.

package/skills/cancel/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: cancel
+description: Cancel a ProofLoop run safely; the branch and worktree are preserved.
+argument-hint: "<run-id>"
+disable-model-invocation: true
+allowed-tools: Bash(proofloop *)
+---
+
+Run `proofloop cancel $ARGUMENTS` and confirm the state.

package/skills/diagnose/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: diagnose
+description: Diagnose a failing or slow workflow with read-only evidence first and ranked hypotheses.
+argument-hint: "[symptom, logs, environment]"
+disable-model-invocation: true
+allowed-tools: Bash(proofloop *)
+---
+
+Run:
+
+```
+proofloop diagnose "$ARGUMENTS"
+```
+
+Then show the user the plan summary and the "Gate plan preview" from the output, plus any warnings. **Do not approve anything yourself.** Tell them to review and, when satisfied, run `/proofloop:approve <run-id>`. Never describe work as passing unless a gate result in the output says PASS. If the output says BLOCKED, report the reason and evidence path verbatim. Do not restart, mutate or delete anything without explicit approval.

package/skills/feature/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: feature
+description: Run the ProofLoop feature protocol: discover, plan, wait for approval, implement in an isolated worktree, verify with real gates.
+argument-hint: "[what to build]"
+disable-model-invocation: true
+allowed-tools: Bash(proofloop *)
+---
+
+Run this and wait for it to finish (it can take several minutes; use a long timeout or run it in the background and poll):
+
+```
+proofloop feature "$ARGUMENTS"
+```
+
+Then show the user the whole plan from the output (at a glance, tasks, acceptance criteria, commands) and the "Gate plan preview", plus any warnings. **Do not approve anything yourself.** Tell them to review and, when satisfied, run `/proofloop:approve <run-id>`. Never describe work as passing unless a gate result in the output says PASS. If the output says BLOCKED, report the reason and evidence path verbatim.

package/skills/ledger/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: ledger
+description: Export the Proof Ledger for a run (JSON or Markdown), or show the history ProofLoop retrieved before planning.
+argument-hint: "<run-id> [json|markdown]"
+disable-model-invocation: true
+allowed-tools: Bash(proofloop *)
+---
+
+Run `proofloop ledger export $ARGUMENTS` (default JSON; add `--format markdown` for the readable form). Report the disposition, the criteria that are verified, failed or unverified, and any stale or missing evidence. To see the retrieved history, run `proofloop memory <run-id>`; to inspect past incidents, run `proofloop incident list`. Do not edit or summarize away failed attempts.

package/skills/performance/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: performance
+description: Run the ProofLoop performance protocol: baseline, one change, before/after against a stated target.
+argument-hint: "[slow operation, workload, target]"
+disable-model-invocation: true
+allowed-tools: Bash(proofloop *)
+---
+
+Run:
+
+```
+proofloop performance "$ARGUMENTS"
+```
+
+Then show the user the plan summary and the "Gate plan preview" from the output, plus any warnings. **Do not approve anything yourself.** Tell them to review and, when satisfied, run `/proofloop:approve <run-id>`. Never describe work as passing unless a gate result in the output says PASS. If the output says BLOCKED, report the reason and evidence path verbatim. Never claim an improvement without recorded before/after numbers and a stated target.

package/skills/protocols/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: protocols
+description: List installed ProofLoop protocols and versions.
+argument-hint: ""
+disable-model-invocation: true
+allowed-tools: Bash(proofloop *)
+---
+
+Run `proofloop protocols` and show the table, including any diagnostics for invalid project-local protocols.

package/skills/resume/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: resume
+description: Resume an interrupted, paused or blocked ProofLoop run after reconciling Git state.
+argument-hint: "<run-id> [--retry]"
+disable-model-invocation: true
+allowed-tools: Bash(proofloop *)
+---
+
+Run `proofloop resume $ARGUMENTS` and report the outcome. Use --retry only after the user confirms the blocker is resolved.

package/skills/setup/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: setup
+description: Check the environment and create a minimal .proofloop config (asks before writing).
+argument-hint: ""
+disable-model-invocation: true
+allowed-tools: Bash(proofloop *)
+---
+
+Run `proofloop setup` (read-only). Show the self-check and what would be written. Only if the user agrees, run `proofloop setup --yes`. Do not install dependencies or change repository files.