@ilbie/capybara-code-darwin-arm64 0.1.0-alpha.3

package/share/capybara/schemas/tools/tool.schema.json

@@ -0,0 +1,270 @@
+{
+  "x-dialect": "json-schema-draft-2020-12",
+  "$id": "cbc:tools/tool",
+  "title": "Capybara Code tool contract",
+  "description": "PRD 12.2, 12.4, 13.2. Describes a tool definition, the common result envelope, and the P0 native catalog. 12.4's schema rules are asserted structurally here: a tool's own parameter schema must be strict, must reject unknown keys, and a mutation tool must carry either an expected hash or an explicit create policy.",
+  "type": "object",
+  "$defs": {
+    "riskClass": {
+      "description": "13.2. R4 through R6 may never receive a session-wide or project-wide allow rule.",
+      "type": "string",
+      "enum": [
+        "R0",
+        "R1",
+        "R2",
+        "R3",
+        "R4",
+        "R5",
+        "R6"
+      ]
+    },
+    "toolSource": {
+      "type": "string",
+      "enum": [
+        "native",
+        "skill",
+        "mcp"
+      ]
+    },
+    "toolDefinition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title",
+        "description",
+        "source",
+        "defaultRisk",
+        "maxRisk",
+        "parameters",
+        "alwaysActive",
+        "mutates",
+        "network",
+        "keywords"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "$ref": "#/$defs/toolSource"
+        },
+        "defaultRisk": {
+          "$ref": "#/$defs/riskClass"
+        },
+        "maxRisk": {
+          "description": "The highest risk this tool can reach once arguments are considered. The classifier may promote up to this, never above it.",
+          "$ref": "#/$defs/riskClass"
+        },
+        "parameters": {
+          "$ref": "#/$defs/strictParameterSchema"
+        },
+        "alwaysActive": {
+          "description": "6.9: an always-active tool is offered without discovery and is excluded from the activation budget.",
+          "type": "boolean"
+        },
+        "mutates": {
+          "type": "boolean"
+        },
+        "network": {
+          "type": "boolean"
+        },
+        "keywords": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1
+        }
+      }
+    },
+    "strictParameterSchema": {
+      "description": "12.4: a tool's argument schema is a strict object that rejects unknown keys, so a hallucinated argument fails validation instead of being silently dropped.",
+      "type": "object",
+      "required": [
+        "type",
+        "properties",
+        "required",
+        "additionalProperties"
+      ],
+      "properties": {
+        "type": {
+          "const": "object"
+        },
+        "properties": {
+          "type": "object"
+        },
+        "required": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": {
+          "const": false
+        }
+      }
+    },
+    "artifactRef": {
+      "description": "18.17. A handle, never inline content. redaction records what was done to the bytes before they were stored.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "digest",
+        "mediaType",
+        "bytes",
+        "redaction",
+        "retentionClass"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "digest": {
+          "type": "string",
+          "minLength": 1
+        },
+        "mediaType": {
+          "type": "string",
+          "minLength": 1
+        },
+        "bytes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "redaction": {
+          "type": "string",
+          "enum": [
+            "raw",
+            "redacted",
+            "derived"
+          ]
+        },
+        "displayName": {
+          "type": "string"
+        },
+        "retentionClass": {
+          "type": "string",
+          "enum": [
+            "session",
+            "temporary",
+            "pinned"
+          ]
+        }
+      }
+    },
+    "toolResult": {
+      "description": "12.4's common result envelope. summary is always present so an observation can be rendered even when data is absent.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ok",
+        "summary"
+      ],
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "summary": {
+          "type": "string"
+        },
+        "artifacts": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/artifactRef"
+          }
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "error": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "code",
+            "message",
+            "retryable"
+          ],
+          "properties": {
+            "code": {
+              "$ref": "cbc:protocol/rpc#/$defs/toolErrorCode"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "description": "10.13: a timeout may be retried; a validation or permission failure may not, because the model must observe it and choose differently.",
+              "type": "boolean"
+            },
+            "details": {
+              "type": "object"
+            }
+          }
+        },
+        "data": true
+      }
+    },
+    "nativeToolId": {
+      "description": "12.2's P0 catalog, in declaration order.",
+      "type": "string",
+      "enum": [
+        "fs.read",
+        "fs.read_many",
+        "fs.list",
+        "fs.glob",
+        "fs.search",
+        "fs.apply_patch",
+        "fs.write",
+        "fs.move",
+        "fs.delete",
+        "process.run",
+        "process.start",
+        "process.input",
+        "process.stop",
+        "shell.run",
+        "artifact.read",
+        "git.status",
+        "git.diff",
+        "git.log",
+        "git.show",
+        "git.checkpoint",
+        "user.ask",
+        "task.search",
+        "task.spawn",
+        "task.status",
+        "task.cancel",
+        "skill.search",
+        "skill.load",
+        "mcp.search",
+        "mcp.call",
+        "mcp.read_resource",
+        "todo.write",
+        "tool.discover",
+        "repo.investigate",
+        "verification.run_many"
+      ]
+    }
+  },
+  "oneOf": [
+    {
+      "$ref": "#/$defs/toolDefinition"
+    },
+    {
+      "$ref": "#/$defs/toolResult"
+    }
+  ]
+}

package/share/capybara/skills/code-review/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: code-review
+description: Review the current diff for correctness, regressions, security, and test gaps.
+version: 1.0.0
+tools:
+  - git.diff
+  - git.status
+  - fs.read
+  - fs.search
+risk: read
+tags:
+  - review
+  - diff
+  - quality
+  - security
+user_invocable: true
+---
+
+# Code review
+
+Read the change before judging it. `git.diff` gives you the change; `fs.read` gives you the surrounding code that tells you whether the change is correct in context.
+
+## What to look for, in order
+
+1. **Correctness.** Does the code do what the diff claims? Check boundary conditions, empty inputs, and error paths — not just the happy path the author was thinking about.
+2. **Regressions.** What else calls this? Use `fs.search` on the changed symbol names. A signature change with one updated call site is a finding.
+3. **Security.** Untrusted input reaching a query, a path, a command, or a deserializer. Credentials or tokens in new code. Authorization checks that moved or disappeared.
+4. **Test gaps.** Does a new behaviour have a test? Does a fixed bug have a regression test? Name the specific case that is missing.
+5. **Data and migrations.** Irreversible operations, lock duration, and rollback.
+
+## What to report
+
+For each finding: severity, file and line, what goes wrong, and the smallest fix.
+
+Do not report formatting, naming preferences, or a restatement of what the code does. If the change is sound, say so plainly and stop — a review that invents findings to look thorough costs the reader more than it gives them.

package/share/capybara/skills/commit-message/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: commit-message
+description: Write a commit message for the current change. Does not commit.
+version: 1.0.0
+tools:
+  - git.diff
+  - git.status
+  - fs.read
+risk: read
+tags:
+  - git
+  - commit
+  - message
+user_invocable: true
+---
+
+# Commit message
+
+Produce a message for the staged or working-tree change. **Do not commit.** There is no commit tool, and running `git commit` through a shell would need its own approval (§12.2).
+
+## Read the change first
+
+`git.status` for scope, `git.diff` for content. Write about what the change does, not what the request asked for — those differ more often than you would expect.
+
+## Shape
+
+```text
+<subject: imperative, under 72 characters, no trailing period>
+
+<body: why this change, and anything a reader could not infer from the diff>
+```
+
+Match the repository's existing convention. If the log uses Conventional Commits, use it. Check `git.log` rather than guessing.
+
+## Subject line
+
+Imperative mood: "Fix the parser", not "Fixed" or "Fixes". Name the thing that changed. "Update code" says nothing.
+
+## Body
+
+Explain the reasoning the diff cannot: why this approach, what was rejected, what a reviewer should look at. Skip the body entirely for a genuinely trivial change rather than padding it.
+
+Return the message as text for the user to use. Say explicitly that nothing was committed.

package/share/capybara/skills/dependency-audit-lite/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: dependency-audit-lite
+description: Review declared dependencies for risk without installing anything.
+version: 1.0.0
+tools:
+  - fs.read
+  - fs.glob
+  - fs.search
+risk: read
+tags:
+  - dependencies
+  - supply-chain
+  - audit
+  - security
+user_invocable: true
+---
+
+# Dependency audit (lite)
+
+A read-only review of what the project declares. Install nothing and run no package-manager command — that would be a network side effect requiring its own approval (§13.2 R3).
+
+## Read the manifests and the lockfile
+
+Manifests state intent; the lockfile states what is actually resolved. Both matter, and they can disagree.
+
+## What to flag
+
+- **Unpinned ranges** on anything security-relevant. A caret range on an auth or crypto library is a supply-chain decision made by whoever publishes next.
+- **Typosquat shapes.** A name one character from a popular package, or an unexpected scope.
+- **Abandoned packages.** No release in years, sitting on a critical path.
+- **Duplicated functionality.** Three HTTP clients is three attack surfaces.
+- **Install scripts.** A `postinstall` runs arbitrary code at install time (§T9).
+- **Direct dependencies that should be dev-only**, shipping to production for no reason.
+
+## What to report
+
+Group by severity. For each item: the package, the version or range, why it is a risk, and the concrete change — pin, replace, or remove.
+
+State clearly that this is a static review of declared dependencies, not a vulnerability scan against an advisory database.

package/share/capybara/skills/repo-onboarding/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: repo-onboarding
+description: Explain an unfamiliar repository's structure, entry points, and how to run it.
+version: 1.0.0
+tools:
+  - fs.read
+  - fs.list
+  - fs.glob
+  - fs.search
+  - git.log
+risk: read
+tags:
+  - onboarding
+  - explain
+  - structure
+  - architecture
+user_invocable: true
+---
+
+# Repository onboarding
+
+Answer the questions a new contributor actually has, in this order.
+
+## 1. What is this?
+
+Read the README and the root manifest. State the purpose in one or two sentences.
+
+## 2. How is it laid out?
+
+Name the top-level directories and what each holds. Skip vendored and generated trees. Do not list every file.
+
+## 3. Where does execution start?
+
+Find the real entry points: `bin` and `scripts` in a manifest, a `main`, a server bootstrap. Trace one representative request or command end to end so the reader has a spine to hang everything else on.
+
+## 4. How do I build, run, and test it?
+
+Quote the exact commands from the manifest. If they need a toolchain or a service, say so.
+
+## 5. What should I know before changing anything?
+
+Conventions from `AGENTS.md` or a contributing guide. Areas that look load-bearing. Recent churn from `git.log`, which tells you where the work is happening.
+
+## Be honest about gaps
+
+If you could not determine how to run the tests, say that. A confident wrong build command costs more than an admitted gap.

package/share/capybara/skills/test-triage/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: test-triage
+description: Run the tests closest to a change and explain each failure.
+version: 1.0.0
+tools:
+  - fs.read
+  - fs.search
+  - fs.glob
+  - process.run
+  - git.diff
+risk: process
+tags:
+  - test
+  - failure
+  - triage
+  - debug
+user_invocable: true
+---
+
+# Test triage
+
+## Select before you run
+
+Find the narrowest command that covers the change. Look for the project's own runner in its manifest — `package.json` scripts, `Cargo.toml`, `pyproject.toml`, `Makefile` — rather than assuming one.
+
+Prefer a single file or filtered suite over the whole matrix. A full run that takes ten minutes to tell you the same thing is a worse answer.
+
+## Read the failure, not the log
+
+For each failing test, report:
+
+- the test name and its file
+- what was expected and what actually happened
+- the specific line that raised
+- whether the cause is the change under test or the environment
+
+## Distinguish the two failure kinds
+
+A **genuine failure** means the code is wrong. An **environment failure** — a missing binary, an absent dependency, no network — means the suite could not answer the question. Say which one you are looking at. "The suite could not run because X" is a useful result; a pass you did not observe is not.
+
+## Before concluding
+
+If a test fails, confirm it also fails without the change when that is cheap to check. A test that was already red is not evidence about this change.

package/share/capybara/skills/write-agents-md/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: write-agents-md
+description: Draft or update an AGENTS.md capturing this project's real conventions.
+version: 1.0.0
+tools:
+  - fs.read
+  - fs.list
+  - fs.glob
+  - fs.search
+  - fs.write
+risk: write
+tags:
+  - agents
+  - conventions
+  - documentation
+user_invocable: true
+---
+
+# Writing AGENTS.md
+
+`AGENTS.md` tells an agent how to work in *this* repository. It shapes behaviour; it grants no permission (§18.2).
+
+## Derive it from the code, not from habit
+
+Before writing a rule, confirm the repository follows it. Read the manifest for the real scripts. Read a few source files for the real style. A rule the code contradicts is worse than no rule, because it will be followed.
+
+## Cover what an agent actually needs
+
+- **Build, test, lint.** The exact commands, copied from the manifest.
+- **Layout.** Where source, tests, and generated output live.
+- **Conventions the code demonstrates.** Formatting, error handling, logging, naming.
+- **Things not to touch.** Generated files, vendored trees, anything with its own pipeline.
+- **Testing expectations.** Where a test goes and what shape it takes.
+
+## Keep it short
+
+Aim for something a reader finishes. Every line competes for the same context budget as the code. Prefer one accurate command over a paragraph describing it.
+
+Write to `AGENTS.md` at the repository root unless a nearer scope is clearly meant.