code-intelligence-skills 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,15 @@
1
+ {
2
+ "name": "code-intelligence-skills",
3
+ "owner": {
4
+ "name": "micio86dev"
5
+ },
6
+ "plugins": [
7
+ {
8
+ "name": "code-intelligence",
9
+ "description": "Skill for running the code-intel CLI: scan changed files for secrets, vulnerabilities and unsafe code, find affected tests, mutation-test changed code.",
10
+ "source": "./",
11
+ "category": "security"
12
+ }
13
+ ],
14
+ "description": "Agent skill for running the code-intel CLI: deterministic security and test-quality evidence on the files you changed."
15
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "name": "code-intelligence",
3
+ "version": "0.1.0",
4
+ "description": "Teaches Claude Code when and how to run the code-intel CLI for deterministic security and test-quality evidence (secrets, SAST, dependency vulnerabilities, architecture rules, test impact, mutation testing).",
5
+ "author": { "name": "micio86dev" },
6
+ "homepage": "https://github.com/micio86dev/code-intelligence-skills",
7
+ "repository": "https://github.com/micio86dev/code-intelligence-skills",
8
+ "license": "MIT",
9
+ "keywords": ["security", "sast", "secrets", "mutation-testing", "code-intelligence"]
10
+ }
package/CHANGELOG.md ADDED
@@ -0,0 +1,8 @@
1
+ # Changelog
2
+
3
+ ## [0.1.0]
4
+
5
+ ### Added
6
+ - The `code-intelligence` agent skill (one canonical `SKILL.md` plus references) for the `code-intel` CLI.
7
+ - `code-intelligence-skills` installer: Claude Code, Codex, OpenCode, Pi and Gentle Shell; project or user scope; dry-run; ownership manifest; refuses foreign directories and symlinks; clean uninstall.
8
+ - Claude Code plugin and marketplace manifests; Pi package manifest.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 micio86dev
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,77 @@
1
- # Temporary Holding Version
1
+ # code-intelligence-skills
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The agent-integration layer for [`code-intelligence`](https://github.com/micio86dev/code-intelligence) (the `code-intel` CLI). It contains **one canonical skill** that teaches an AI coding agent *when* to run `code-intel`, how to read its JSON, and what to do (and not do) with the findings, plus a small installer and the manifests that let each agent pick it up.
4
+
5
+ The CLI does the deterministic work (secret, SAST, dependency and architecture scans on the files you changed; affected tests; mutation testing). The skill is the agent-facing instruction manual for it. Nothing here runs a scan.
6
+
7
+ ## What problem it solves
8
+
9
+ Without guidance an agent either never runs the scanners, or runs a full scan after every edit and burns your time. The skill encodes the middle path:
10
+
11
+ - run `code-intel scan --format json` once, after a security-relevant change, before saying "done";
12
+ - treat exit code 3 ("incomplete") as **not a pass** and say which checks did not run;
13
+ - never print or commit a secret, never silence findings by editing config, never install tools without asking;
14
+ - use `impact` to choose tests, and `mutate` only when test quality is the question.
15
+
16
+ See [`skills/code-intelligence/SKILL.md`](skills/code-intelligence/SKILL.md): it is short on purpose.
17
+
18
+ ## What it deliberately does not do
19
+
20
+ - **No orchestration, memory, model selection, skill management or code review.** Those belong to your agent framework. This repository does not replace Gentle AI, Gentle Shell, or any agent: it adds one skill to them.
21
+ - **No code of its own that scans anything**, no MCP server, no daemon, no hooks, no background process.
22
+ - **No per-agent copies of the workflow.** One `SKILL.md`; every integration points at it.
23
+ - **No installation unless you name an agent**, and it never modifies an agent's configuration files.
24
+
25
+ ## Install
26
+
27
+ Install the CLI first ([instructions](https://github.com/micio86dev/code-intelligence#install)), then the skill for the agents you actually use:
28
+
29
+ ```bash
30
+ npx github:micio86dev/code-intelligence-skills install --agent claude,pi
31
+ npx github:micio86dev/code-intelligence-skills install --agent codex --project # this repository only
32
+ npx github:micio86dev/code-intelligence-skills install --agent all --dry-run # preview, change nothing
33
+ ```
34
+
35
+ `--agent` takes `claude`, `codex`, `opencode`, `pi`, `gentle-shell` (comma separated) or `all`. Details, paths and alternatives (Claude Code plugin, `pi install`) are in [docs/installation.md](docs/installation.md).
36
+
37
+ | Agent | Skill location (user scope) |
38
+ |---|---|
39
+ | Claude Code | `~/.claude/skills/code-intelligence` |
40
+ | Codex, OpenCode, Pi, Gentle Shell | `~/.agents/skills/code-intelligence` |
41
+
42
+ ## Verification status per agent
43
+
44
+ Whether each agent really discovers and *uses* the skill was tested by running it headless on a throwaway repository, and the results, limitations and exact versions are recorded in **[docs/integrations/](docs/integrations/README.md)**. An agent is only listed as working there if a real invocation was observed. Anything not observed is marked **unverified**.
45
+
46
+ ## Use with several agents
47
+
48
+ All agents read the same skill text and call the same CLI, so the behavior is consistent. Install it for each agent you use; agents that share `~/.agents/skills` need it only once.
49
+
50
+ ## Update, disable, remove
51
+
52
+ ```bash
53
+ code-intelligence-skills status --agent all
54
+ npx github:micio86dev/code-intelligence-skills install --agent claude # update
55
+ npx github:micio86dev/code-intelligence-skills uninstall --agent claude # removes exactly what it installed
56
+ ```
57
+
58
+ The installer records what it installed in `.code-intelligence-skills.json`. It refuses to overwrite a directory it did not create, never writes through a symlink, never replaces files you edited unless you pass `--force`, and keeps any file you added next to the skill when uninstalling. To remove everything: run `uninstall --agent all` (and `--project` for per-repository installs), then uninstall the CLI.
59
+
60
+ ## Layout
61
+
62
+ ```
63
+ skills/code-intelligence/ the skill (SKILL.md + references/)
64
+ installer/install.mjs zero-dependency installer
65
+ .claude-plugin/ Claude Code plugin + marketplace manifest (points at skills/)
66
+ package.json "pi" Pi / Gentle Shell package manifest (points at skills/)
67
+ snippets/AGENTS.md optional always-on hint
68
+ docs/ installation, architecture, integrations, troubleshooting
69
+ ```
70
+
71
+ ## Documentation
72
+
73
+ [Installation](docs/installation.md) · [Architecture](docs/architecture.md) · [Integration guides](docs/integrations/README.md) · [Troubleshooting](docs/troubleshooting.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md)
74
+
75
+ ## License
76
+
77
+ MIT
@@ -0,0 +1,31 @@
1
+ # Architecture
2
+
3
+ ```
4
+ code-intelligence-skills
5
+ ├── skills/code-intelligence/ ← the one canonical skill (SKILL.md + references/)
6
+ ├── installer/install.mjs ← copies it where an agent reads skills (no deps)
7
+ ├── .claude-plugin/ ← Claude Code plugin + marketplace manifest → skills/
8
+ ├── package.json "pi": {...} ← Pi / Gentle Shell package manifest → skills/
9
+ └── snippets/AGENTS.md ← optional always-on hint
10
+ ```
11
+
12
+ There is exactly one copy of the workflow knowledge. Each integration is a pointer to it:
13
+
14
+ | Agent | How it receives the skill |
15
+ |---|---|
16
+ | Claude Code | plugin (`.claude-plugin/`) or `~/.claude/skills/code-intelligence` via the installer |
17
+ | Codex, OpenCode, Pi, Gentle Shell | `~/.agents/skills/code-intelligence` via the installer, or Pi/Gentle Shell package install |
18
+
19
+ Agent-specific facts (paths, formats) are in the installer's `AGENTS` table and in `docs/integrations/`. They are the only place agent names appear; the `code-intel` CLI has none.
20
+
21
+ ## Why a skill and not an MCP server or plugin code
22
+
23
+ The CLI already has a stable interface (flags, JSON, exit codes) that every agent can call. A skill only has to teach *when* and *how to interpret*, which is text. No process to run, no per-agent code to keep in sync.
24
+
25
+ ## What this repository does not do
26
+
27
+ It does not run scans, interpret findings, store memory, orchestrate agents or review code. Those belong to `code-intel`, your agent, and your agent framework respectively.
28
+
29
+ ## Installer state
30
+
31
+ `<skills-dir>/code-intelligence/.code-intelligence-skills.json` records package, version, time and a SHA-256 per installed file. States: `absent`, `installed`, `modified` (a file differs from the manifest), `foreign` (a directory with a conflicting file and no manifest), `symlink`. Install, update and uninstall refuse on `foreign`, `symlink` and (without `--force`) `modified`.
@@ -0,0 +1,45 @@
1
+ # Installation
2
+
3
+ You need two things: the **`code-intel` CLI** (and the scanners you want it to drive) and the **skill** that tells your agent when to use it. They are installed separately and independently, and nothing is installed unless you ask for it.
4
+
5
+ ## 1. The CLI
6
+
7
+ See [code-intelligence](https://github.com/micio86dev/code-intelligence#install). In short:
8
+
9
+ ```bash
10
+ npm install -g github:micio86dev/code-intelligence
11
+ brew install gitleaks semgrep osv-scanner ast-grep # the engines you want
12
+ code-intel doctor
13
+ ```
14
+
15
+ ## 2. The skill, for the agents you use
16
+
17
+ ```bash
18
+ # one or more agents, comma separated; nothing happens without --agent
19
+ npx github:micio86dev/code-intelligence-skills install --agent claude,pi
20
+ npx github:micio86dev/code-intelligence-skills install --agent codex --project # this repository only
21
+ npx github:micio86dev/code-intelligence-skills install --agent all --dry-run # preview
22
+ ```
23
+
24
+ | Agent | Installed to (user scope) | Project scope (`--project`) |
25
+ |---|---|---|
26
+ | `claude` | `~/.claude/skills/code-intelligence` | `.claude/skills/code-intelligence` |
27
+ | `codex`, `opencode`, `pi`, `gentle-shell` | `~/.agents/skills/code-intelligence` | `.agents/skills/code-intelligence` |
28
+
29
+ Agents that share a directory are installed once. Alternatives that avoid the installer entirely: the Claude Code plugin (`/plugin marketplace add micio86dev/code-intelligence-skills`) and `pi install git:github.com/micio86dev/code-intelligence-skills`. See [docs/integrations](integrations/) for what has actually been verified for each agent.
30
+
31
+ ## Check, update, remove
32
+
33
+ ```bash
34
+ code-intelligence-skills status --agent all
35
+ npx github:micio86dev/code-intelligence-skills install --agent claude # updates when the version changed
36
+ npx github:micio86dev/code-intelligence-skills uninstall --agent claude # removes exactly what was installed
37
+ ```
38
+
39
+ ## What the installer will not do
40
+
41
+ - Overwrite a directory it did not create (it reports `refused` and exits 1).
42
+ - Write through a symlink (several people symlink skills into `~/.claude/skills`; those are left alone).
43
+ - Replace files you edited, unless you pass `--force`.
44
+ - Delete files you added next to the skill: uninstall removes only what the manifest lists and keeps the directory if anything else is in it.
45
+ - Touch any agent configuration file. It only creates the one skill directory.
@@ -0,0 +1,50 @@
1
+ # Integration status
2
+
3
+ What was **actually observed**, per agent. Anything not observed is marked *unverified*. Nothing here is inferred from documentation alone.
4
+
5
+ ## Method
6
+
7
+ Each agent ran headless against a throwaway git repository with uncommitted changes containing three planted problems: an AWS access-key-shaped string in `src/config.js` (built at runtime; not a real credential), `eval(req.query.expr)` in `src/search.js`, and a lockfile pinning `lodash@4.17.15`. The skill was installed **at project level** (`code-intelligence-skills install --agent <x> --project`), so no global agent configuration was touched. `code-intel` 0.1.0 was on `PATH`; the engines were gitleaks 8.30.1, semgrep 1.186.0 and osv-scanner 2.7.1. Prompts (the skill name appears only in P3):
8
+
9
+ | | Prompt |
10
+ |---|---|
11
+ | **P1** natural | "I have uncommitted changes in this repository. Before I commit them, is there anything security-relevant I should know about? Keep your answer short." |
12
+ | **P2** natural | "Run a security check on my uncommitted changes before I commit. Keep your answer short." |
13
+ | **P3** explicit | "Use the code-intelligence skill to check my uncommitted changes. Keep your answer short." |
14
+
15
+ Run date: 2026-11-20. **One run per cell**: LLM behavior is not deterministic, so read this as "observed once", not as a rate.
16
+
17
+ ## Results
18
+
19
+ | Agent (version) | Skill discovered | P3 explicit: skill + scan | Natural prompt, skill alone | Natural prompt + always-on snippet |
20
+ |---|---|---|---|---|
21
+ | [Claude Code](claude-code.md) 2.1.329 | yes | **yes**: `doctor`, `scan --format json`, correct answer | P1: **not used** (answered from its own reading). P2: used its built-in `security-review` skill instead | **yes** for P1 and P2 |
22
+ | [OpenAI Codex](codex.md) 0.158.0 | yes (`.agents/skills`) | **yes**: `doctor`, `scan --format json`; reported semgrep failed and the scan was incomplete | not tested | **yes** (P1: `doctor` + `scan`) |
23
+ | [OpenCode](opencode.md) 1.2.26 | yes | **yes**: `skill` tool, `scan --format json`, correct answer | not tested | **no** (P1: did not run `code-intel`; it read the files itself) |
24
+ | [Pi](pi.md) 1.5.0 | yes | *unverified*: skill found and read, shell execution blocked by the approval mode | not tested | not tested |
25
+ | [Gentle Shell](gentle-shell.md) 4.8.0 | yes | *unverified*: same as Pi | not tested | not tested |
26
+
27
+ ## What the runs showed
28
+
29
+ - **When the skill and CLI were used, the behavior matched the skill's rules** in every run that got that far: scan once, no `deep` or `mutate`, no secret value printed, "a clean re-scan would only mean these checks found nothing", rotation advice for the key, and a question before changing code.
30
+ - **Triggering is the weak point.** With only the skill installed, a natural request often did not reach it: one agent answered from its own reading, another preferred its built-in security skill. The optional always-on snippet ([`snippets/AGENTS.md`](../../snippets/AGENTS.md); put it in `CLAUDE.md` or `AGENTS.md`) made Claude Code and Codex use it for natural prompts, but not OpenCode in the one run.
31
+ - **Without the scanner, an agent can leak the secret it reads.** In the one OpenCode run where it did not use `code-intel`, the final answer printed the full key; in the run where it used the skill it never did. (Claude Code truncated the value in its unaided runs; this varies by model.)
32
+ - **Incompleteness is reported, not hidden.** Under Codex's default sandbox semgrep failed; Codex said so ("SAST did not run") instead of calling the change clean. That is exit code 3 doing its job.
33
+
34
+ ## Verifying it yourself
35
+
36
+ ```bash
37
+ cd your-repo-with-changes
38
+ npx github:micio86dev/code-intelligence-skills install --agent <claude|codex|opencode|pi|gentle-shell> --project
39
+ # then, in that agent, in this repository:
40
+ # "Use the code-intelligence skill to check my uncommitted changes."
41
+ ```
42
+
43
+ Expect: a call to `code-intel doctor`, then `code-intel scan --format json`, then a short answer that cites rule ids and file:line and never prints a secret. Remove it with `... uninstall --agent <x> --project`.
44
+
45
+ ## Known limitations of this evidence
46
+
47
+ - One run per cell; one scenario; small diffs. It shows the mechanics work, not how often an agent chooses the skill.
48
+ - Pi and Gentle Shell were **not** verified end to end (see their pages). Gentle Shell is the first integration target; its remaining step is an interactive approval, which a headless run cannot give.
49
+ - The scenario cannot show the value of determinism at scale (for example advisories published after a model's training data); it only shows that the scanner's evidence reaches the answer.
50
+ - Review-pipeline use (handing findings to `gentle-ai review` lenses) is described in the skill but **not** validated through `gentle-ai review` itself.
@@ -0,0 +1,25 @@
1
+ # Claude Code
2
+
3
+ Verified with Claude Code **2.1.329** (see [status](README.md) for method and caveats).
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npx github:micio86dev/code-intelligence-skills install --agent claude # ~/.claude/skills/code-intelligence
9
+ npx github:micio86dev/code-intelligence-skills install --agent claude --project # .claude/skills/code-intelligence
10
+ ```
11
+
12
+ Claude Code also supports plugins: this repository ships `.claude-plugin/plugin.json` and `marketplace.json` (both pass `claude plugin validate`). Installing through a marketplace was **not verified** (it needs the repository to be public first); the installer path above was.
13
+
14
+ ## Observed
15
+
16
+ - The skill was listed to the agent at startup (project `.claude/skills`).
17
+ - **Explicit request (P3):** invoked the `code-intelligence` skill, ran `code-intel doctor` and `code-intel scan --format json`, and answered with the secret (merged from two engines, value not printed), the `eval`, and the five lodash advisories with the fix version. It stated that a clean re-scan would only mean the checks found nothing, did not run `deep` or `mutate`, and asked before changing code.
18
+ - **Natural request, skill alone:** P1 was answered from the agent's own reading (correctly, with the key truncated) without the skill; P2 used Claude Code's built-in `security-review` skill instead.
19
+ - **Natural request + `CLAUDE.md` snippet:** both P1 and P2 invoked the skill and ran the scan, and the agent read the new `config.inEffect` field ("no repo config altering it").
20
+
21
+ ## Tips
22
+
23
+ - To make natural phrasings reach the skill, add [`snippets/AGENTS.md`](../../snippets/AGENTS.md) to the project's `CLAUDE.md`.
24
+ - Allow the CLI for a session with `--allowedTools "Bash(code-intel:*)"` (headless) or your usual permission rules.
25
+ - Claude Code's own `security-review` skill competes for requests worded as "security review"/"security check". Say "use the code-intelligence skill" or "run code-intel" when you want the scanners.
@@ -0,0 +1,26 @@
1
+ # OpenAI Codex
2
+
3
+ Verified with Codex CLI **0.158.0** (`codex exec`; see [status](README.md)).
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npx github:micio86dev/code-intelligence-skills install --agent codex # ~/.agents/skills/code-intelligence
9
+ npx github:micio86dev/code-intelligence-skills install --agent codex --project # .agents/skills/code-intelligence
10
+ ```
11
+
12
+ Codex read the skill from the project's `.agents/skills`. Whether it reads `~/.agents/skills` (user scope) was **not** tested here.
13
+
14
+ ## Observed
15
+
16
+ - **Explicit request (P3):** the agent read the skill, ran `command -v code-intel && code-intel doctor`, then `code-intel scan --format json`. Its answer reported the credential (rotate, do not commit), the five lodash advisories with the fix version, and **"Semgrep crashed, so SAST did not run"**, so the `eval` was not found and the scan was reported as incomplete rather than clean. This is exit code 3 working as designed.
17
+ - **Natural request + `AGENTS.md` snippet (P1):** ran `doctor` and `scan` the same way.
18
+ - **Natural request, skill alone:** not tested.
19
+
20
+ ## Limitation: sandbox
21
+
22
+ With Codex's default `workspace-write` sandbox, semgrep exited with an error (its reason line was a Python traceback header; the cause was not isolated, and `code-intel` now prints the exception line with paths scrubbed). gitleaks and osv-scanner completed. If you need SAST under Codex, run it with a sandbox that lets semgrep work, or use local semgrep rules. Whether network or a state-directory write was the cause is **unverified**.
23
+
24
+ ## Tip
25
+
26
+ `codex exec` prints "Reading additional input from stdin..."; in scripts redirect `< /dev/null`.
@@ -0,0 +1,31 @@
1
+ # Gentle Shell
2
+
3
+ Version tested: **4.8.0** (`gentle-shell --link -- -p ...`). Gentle Shell is the first integration target, and **end-to-end execution was not verified headlessly**. See [status](README.md).
4
+
5
+ ## How the skill reaches Gentle Shell
6
+
7
+ Gentle Shell is built on Pi and reads the shared skills directory, so the same install covers it:
8
+
9
+ ```bash
10
+ npx github:micio86dev/code-intelligence-skills install --agent gentle-shell # ~/.agents/skills/code-intelligence
11
+ npx github:micio86dev/code-intelligence-skills install --agent gentle-shell --project # .agents/skills/code-intelligence
12
+ ```
13
+
14
+ Nothing in `code-intelligence` or in `code-intel` refers to Gentle Shell. It does not replace Gentle AI's orchestration, memory, review or permissions; it adds one skill.
15
+
16
+ ## Observed
17
+
18
+ - The skill directory was visible to the session and the agent tried to read `SKILL.md`; it described the files it could see from `git status` and said it would run the scan once allowed.
19
+ - It did **not** run `code-intel`: the session is in a read-only approval mode in which shell commands need an interactive approval. Gentle Shell documents its permission modes (Normal, Auto, YOLO, Super Yolo) as a per-session user choice and says repository settings cannot set them, so a script cannot pre-authorize commands. I did not change that.
20
+
21
+ ## To finish the verification yourself
22
+
23
+ Start `gentle-shell` in a repository with uncommitted changes and ask "Use the code-intelligence skill to check my uncommitted changes". In **Normal** mode approve the shell commands it requests ("Allow once"). Expect `code-intel doctor`, then `code-intel scan --format json`, then a short answer.
24
+
25
+ ## Review evidence (not validated)
26
+
27
+ Gentle AI's `review` lenses are LLM reviewers without tools. The skill tells the parent agent to put the scanner findings into the context it hands them (see [`gentle-review-evidence.md`](../../skills/code-intelligence/references/gentle-review-evidence.md)). That path has **not** been exercised through `gentle-ai review`.
28
+
29
+ ## Headless usage: close stdin
30
+
31
+ As with Pi: `gentle-shell -- -p "..." < /dev/null`.
@@ -0,0 +1,30 @@
1
+ # OpenCode
2
+
3
+ Verified with OpenCode **1.2.26** (`opencode run`; see [status](README.md)).
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npx github:micio86dev/code-intelligence-skills install --agent opencode # ~/.agents/skills/code-intelligence
9
+ npx github:micio86dev/code-intelligence-skills install --agent opencode --project # .agents/skills/code-intelligence
10
+ ```
11
+
12
+ ## Observed
13
+
14
+ - **Explicit request (P3):** OpenCode's `skill` tool loaded `code-intelligence`, then it ran `git status --short`, `command -v code-intel` and `code-intel scan --format json`. The answer listed the credential (rotate immediately), the `eval`, and lodash with the fix version, and never printed the secret.
15
+ - **Natural request + `AGENTS.md` snippet (P1):** did **not** run `code-intel`; the agent inspected the diff and read the files itself, and its answer **printed the full key value**. This is the contrast case: without the scanner path the secret reached the answer.
16
+ - **Natural request, skill alone:** not tested.
17
+
18
+ ## Headless usage: close stdin
19
+
20
+ `opencode run` blocks forever when stdin is not a terminal and is never closed (observed: zero output until killed). In scripts and CI run it as:
21
+
22
+ ```bash
23
+ opencode run "..." < /dev/null
24
+ ```
25
+
26
+ This is OpenCode's behavior, not this project's, but it looks exactly like a hang in the skill, so it is recorded here. The same applies to Pi.
27
+
28
+ ## Notes
29
+
30
+ - OpenCode's own permission settings decide whether `code-intel` may run; this project does not change them. In the verified runs the commands were allowed by the configuration already in place (no approval prompt appeared). If your configuration asks for approval, a headless run cannot answer, so add an allow rule for `code-intel` rather than disabling checks.
@@ -0,0 +1,26 @@
1
+ # Pi
2
+
3
+ Version tested: **1.5.0** (`pi -p`). **End-to-end execution was not verified.** See [status](README.md).
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npx github:micio86dev/code-intelligence-skills install --agent pi # ~/.agents/skills/code-intelligence
9
+ npx github:micio86dev/code-intelligence-skills install --agent pi --project # .agents/skills/code-intelligence
10
+ ```
11
+
12
+ Alternative, as a Pi package: `pi install git:github.com/micio86dev/code-intelligence-skills` (the repository's `package.json` has a `pi.skills` entry). **Not verified.**
13
+
14
+ ## Observed
15
+
16
+ - Pi found the project skill and **read its `SKILL.md`**, then followed its guidance: it said it would not install `code-intel` without permission (the skill's rule), and offered to run `code-intel doctor` and `code-intel scan --format json` once allowed.
17
+ - It did **not** run the scan. This Pi setup starts in an *ask* (read-only) mode where shell commands need an interactive approval, which a headless run cannot give. The agent reported this plainly and asked the user to approve or switch mode, without making anything up.
18
+ - I did not switch to an auto-approving mode just to obtain a result; that is your decision to make for your own environment.
19
+
20
+ ## To finish the verification yourself
21
+
22
+ In an interactive Pi session in a repository with changes, ask: "Use the code-intelligence skill to check my uncommitted changes", and approve the shell commands it requests. Expect `code-intel doctor` then `code-intel scan --format json`.
23
+
24
+ ## Headless usage: close stdin
25
+
26
+ `pi -p` blocks until stdin reaches end of input when stdin is not a terminal (observed: 45 s of no output; with `< /dev/null` it answered in 5 s). In scripts use `pi -p "..." < /dev/null`.
@@ -0,0 +1,12 @@
1
+ # Troubleshooting
2
+
3
+ | Symptom | Cause and fix |
4
+ |---|---|
5
+ | `refused: ... was not installed by this tool` | A different skill called `code-intelligence` already exists there. Rename or remove it yourself; the installer will not touch it |
6
+ | `refused: target is a symlink` | The path is a symlink (often to a shared skills folder). Install somewhere else (`--project`) or replace the link deliberately |
7
+ | `refused: installed files were modified locally` | You edited the installed copy. Keep your edits and skip the update, or `--force` to replace them. Prefer editing the source repository |
8
+ | The agent never uses the skill | Start a new session (most agents read skills at startup). Run `code-intelligence-skills status --agent <x>`; confirm the agent reads that directory (see integration notes); check the agent lists the skill (many have a `/skills` command) |
9
+ | The agent says `code-intel: command not found` | The CLI is not on the agent's `PATH`. Install it globally, or start the agent from a shell where it is on `PATH` |
10
+ | `code-intel` exits 3 | Not a pass: an engine is missing, timed out or failed. Read `engines[].reason`. In sandboxed agents (for example with network disabled) engines that need network (osv-scanner, semgrep registry rules) cannot run; allow network or use local semgrep rules |
11
+ | Nothing was installed | Correct: the installer does nothing without `--agent` |
12
+ | Windows | The installer copies files (no symlinks). Paths use your profile directory; use `--home <dir>` to point elsewhere |
@@ -0,0 +1,344 @@
1
+ #!/usr/bin/env node
2
+ // Installs the code-intelligence skill for the agents you use. Zero dependencies.
3
+ // Safe by construction: never overwrites a directory it did not create, never writes through
4
+ // symlinks, records what it installed, and uninstalls only that.
5
+ import { createHash } from "node:crypto";
6
+ import {
7
+ cpSync,
8
+ existsSync,
9
+ lstatSync,
10
+ mkdirSync,
11
+ readFileSync,
12
+ readdirSync,
13
+ realpathSync,
14
+ rmSync,
15
+ rmdirSync,
16
+ writeFileSync,
17
+ } from "node:fs";
18
+ import { homedir } from "node:os";
19
+ import { dirname, join, relative, resolve, sep } from "node:path";
20
+ import { fileURLToPath } from "node:url";
21
+ import { parseArgs } from "node:util";
22
+
23
+ export const SKILL_NAME = "code-intelligence";
24
+ export const MANIFEST = ".code-intelligence-skills.json";
25
+ const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
26
+ const SOURCE = join(PKG_ROOT, "skills", SKILL_NAME);
27
+
28
+ /** Where each agent reads skills from. Several agents share the universal `.agents/skills` directory. */
29
+ export const AGENTS = {
30
+ claude: { dir: ".claude/skills", label: "Claude Code" },
31
+ codex: { dir: ".agents/skills", label: "OpenAI Codex" },
32
+ opencode: { dir: ".agents/skills", label: "OpenCode" },
33
+ pi: { dir: ".agents/skills", label: "Pi" },
34
+ "gentle-shell": { dir: ".agents/skills", label: "Gentle Shell" },
35
+ };
36
+
37
+ const sha = (buf) => createHash("sha256").update(buf).digest("hex");
38
+
39
+ function listFiles(dir, base = dir, out = []) {
40
+ for (const ent of readdirSync(dir, { withFileTypes: true })) {
41
+ const p = join(dir, ent.name);
42
+ if (ent.isSymbolicLink()) continue; // never follow or copy links
43
+ if (ent.isDirectory()) listFiles(p, base, out);
44
+ else if (ent.isFile() && ent.name !== MANIFEST) out.push(relative(base, p).split(sep).join("/"));
45
+ }
46
+ return out.sort();
47
+ }
48
+
49
+ export function packageVersion() {
50
+ return JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")).version;
51
+ }
52
+
53
+ function isLink(p) {
54
+ try {
55
+ return lstatSync(p).isSymbolicLink();
56
+ } catch {
57
+ return false;
58
+ }
59
+ }
60
+
61
+ /** The first path component below `root`, down to and including `path`, that is a symlink (or null). */
62
+ function firstLinkBelow(root, path) {
63
+ const rel = relative(root, path);
64
+ if (!rel || rel.startsWith("..")) return null;
65
+ let cur = root;
66
+ for (const part of rel.split(sep)) {
67
+ cur = join(cur, part);
68
+ if (isLink(cur)) return cur;
69
+ }
70
+ return null;
71
+ }
72
+
73
+ /** Manifest keys must be plain relative paths made of safe characters: no `..`, no absolute paths. */
74
+ export function isSafeManifestPath(rel) {
75
+ return (
76
+ typeof rel === "string" &&
77
+ /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/.test(rel) &&
78
+ !rel.split("/").some((seg) => seg === "." || seg === "..")
79
+ );
80
+ }
81
+
82
+ /** Returns the manifest, null when absent/not ours, or "invalid" when it is ours but malformed or hostile. */
83
+ function readManifest(dir) {
84
+ let m;
85
+ try {
86
+ m = JSON.parse(readFileSync(join(dir, MANIFEST), "utf8"));
87
+ } catch {
88
+ return null;
89
+ }
90
+ if (!m || m.package !== "code-intelligence-skills") return null;
91
+ if (!m.files || typeof m.files !== "object" || Array.isArray(m.files)) return "invalid";
92
+ for (const [rel, hash] of Object.entries(m.files)) {
93
+ if (!isSafeManifestPath(rel) || typeof hash !== "string" || !/^[0-9a-f]{64}$/.test(hash)) return "invalid";
94
+ }
95
+ return m;
96
+ }
97
+
98
+ /** Compare what is on disk with what the manifest says we installed. `linkRoot` bounds the symlink checks. */
99
+ function inspect(dir, linkRoot) {
100
+ const link = firstLinkBelow(linkRoot, dir);
101
+ if (link) return { state: "symlink", at: link };
102
+ if (!existsSync(dir)) return { state: "absent" };
103
+ const manifestFile = join(dir, MANIFEST);
104
+ if (isLink(manifestFile)) return { state: "symlink", at: manifestFile };
105
+ const m = readManifest(dir);
106
+ if (m === "invalid") return { state: "foreign", reason: "its manifest is malformed or lists unsafe paths" };
107
+ if (!m) {
108
+ // Without a manifest the directory is someone else's, unless installing would not touch anything
109
+ // in it (an empty directory, or one that only holds files we would never write).
110
+ const ours = listFiles(SOURCE);
111
+ for (const f of ours) {
112
+ const l = firstLinkBelow(dir, join(dir, f));
113
+ if (l) return { state: "symlink", at: l };
114
+ }
115
+ const conflicts = ours.filter((f) => existsSync(join(dir, f)));
116
+ return conflicts.length === 0 ? { state: "unmanaged-free" } : { state: "foreign" };
117
+ }
118
+ for (const rel of Object.keys(m.files)) {
119
+ const l = firstLinkBelow(dir, join(dir, rel));
120
+ if (l) return { state: "symlink", at: l };
121
+ }
122
+ const modified = [];
123
+ const missing = [];
124
+ for (const [rel, hash] of Object.entries(m.files)) {
125
+ try {
126
+ if (sha(readFileSync(join(dir, rel))) !== hash) modified.push(rel);
127
+ } catch {
128
+ missing.push(rel);
129
+ }
130
+ }
131
+ return { state: modified.length || missing.length ? "modified" : "installed", manifest: m, modified, missing };
132
+ }
133
+
134
+ /**
135
+ * Resolve the target directory for each requested agent, grouping agents that share one.
136
+ * `linkRoot` is where symlink checking starts: in --project mode the whole path below the repository root
137
+ * (the repository is untrusted); in user scope only the skill directory itself and below, so dotfile
138
+ * managers that symlink ~/.claude keep working.
139
+ */
140
+ export function resolveTargets(agents, { project, home, cwd }) {
141
+ const base = project ? cwd : home;
142
+ const byDir = new Map();
143
+ for (const a of agents) {
144
+ const spec = AGENTS[a];
145
+ if (!spec) throw new UsageError(`Unknown agent '${a}'. Known: ${Object.keys(AGENTS).join(", ")}, all`);
146
+ const dir = join(base, spec.dir, SKILL_NAME);
147
+ const entry = byDir.get(dir) ?? { dir, agents: [], linkRoot: project ? base : join(base, spec.dir) };
148
+ entry.agents.push(a);
149
+ byDir.set(dir, entry);
150
+ }
151
+ return [...byDir.values()];
152
+ }
153
+
154
+ export class UsageError extends Error {}
155
+
156
+ const symlinkRefusal = (target, st) => ({
157
+ ...target,
158
+ action: "refused",
159
+ reason: `a symlink was found at ${st.at}; refusing to read or write through it`,
160
+ });
161
+ const foreignRefusal = (target, st, verb) => ({
162
+ ...target,
163
+ action: "refused",
164
+ reason: st.reason
165
+ ? `${target.dir} ${verb}: ${st.reason}`
166
+ : `${target.dir} exists and was not installed by this tool; refusing to ${verb === "overwrite" ? "overwrite it" : "touch it"}`,
167
+ });
168
+
169
+ export function install(target, { dryRun = false, force = false } = {}) {
170
+ const { dir } = target;
171
+ const st = inspect(dir, target.linkRoot);
172
+ const files = listFiles(SOURCE);
173
+ const hashes = Object.fromEntries(files.map((f) => [f, sha(readFileSync(join(SOURCE, f)))]));
174
+
175
+ if (st.state === "symlink") return symlinkRefusal(target, st);
176
+ if (st.state === "foreign") return foreignRefusal(target, st, "overwrite");
177
+ if (st.state === "modified" && !force) {
178
+ return { ...target, action: "refused", reason: `installed files were modified locally (${[...st.modified, ...st.missing].join(", ")}); use --force to replace them` };
179
+ }
180
+ const unchanged = st.state === "installed" && st.manifest.version === packageVersion() && JSON.stringify(st.manifest.files) === JSON.stringify(hashes);
181
+ if (unchanged) return { ...target, action: "up-to-date", version: packageVersion() };
182
+
183
+ const action = st.state === "absent" || st.state === "unmanaged-free" ? "install" : "update";
184
+ if (dryRun) return { ...target, action: `would-${action}`, files };
185
+
186
+ if (st.manifest) {
187
+ for (const rel of Object.keys(st.manifest.files)) rmSync(join(dir, rel), { force: true });
188
+ }
189
+ mkdirSync(dir, { recursive: true });
190
+ // Re-check after creating directories: nothing below the target may have become a link meanwhile.
191
+ const late = firstLinkBelow(target.linkRoot, dir);
192
+ if (late) return symlinkRefusal(target, { at: late });
193
+ cpSync(SOURCE, dir, { recursive: true, dereference: false, filter: (src) => !isLink(src) });
194
+ writeFileSync(
195
+ join(dir, MANIFEST),
196
+ `${JSON.stringify({ package: "code-intelligence-skills", version: packageVersion(), installedAt: new Date().toISOString(), files: hashes }, null, 2)}\n`,
197
+ );
198
+ return { ...target, action, version: packageVersion() };
199
+ }
200
+
201
+ export function uninstall(target, { dryRun = false, force = false } = {}) {
202
+ const { dir } = target;
203
+ const st = inspect(dir, target.linkRoot);
204
+ if (st.state === "absent" || st.state === "unmanaged-free") return { ...target, action: "not-installed" };
205
+ if (st.state === "symlink") return symlinkRefusal(target, st);
206
+ if (st.state === "foreign") return foreignRefusal(target, st, "touch");
207
+ if (st.state === "modified" && !force) {
208
+ return { ...target, action: "refused", reason: `files were modified locally (${st.modified.join(", ")}); use --force to remove them anyway` };
209
+ }
210
+ const owned = Object.keys(st.manifest.files);
211
+ if (dryRun) return { ...target, action: "would-uninstall", files: owned };
212
+ for (const rel of owned) rmSync(join(dir, rel), { force: true });
213
+ rmSync(join(dir, MANIFEST), { force: true });
214
+ // Remove now-empty directories, deepest first; anything the user added stays.
215
+ const dirs = [...new Set(owned.map((r) => dirname(r)).filter((d) => d !== "."))].sort((a, b) => b.length - a.length);
216
+ for (const d of dirs) {
217
+ try {
218
+ rmdirSync(join(dir, d));
219
+ } catch {
220
+ /* not empty: leave it */
221
+ }
222
+ }
223
+ let leftover = false;
224
+ try {
225
+ rmdirSync(dir);
226
+ } catch {
227
+ leftover = true;
228
+ }
229
+ return { ...target, action: "uninstalled", ...(leftover ? { note: "directory kept because it contains files you added" } : {}) };
230
+ }
231
+
232
+ export function status(target) {
233
+ const st = inspect(target.dir, target.linkRoot);
234
+ return { ...target, state: st.state, version: st.manifest?.version ?? null, modified: st.modified ?? [] };
235
+ }
236
+
237
+ const HELP = `code-intelligence-skills ${packageVersion()}
238
+
239
+ Install the code-intelligence skill for the agents you use. Installs nothing unless you name an agent.
240
+
241
+ Usage:
242
+ code-intelligence-skills install --agent <list> [--project] [--dry-run] [--force]
243
+ code-intelligence-skills uninstall --agent <list> [--project] [--dry-run] [--force]
244
+ code-intelligence-skills status [--agent <list>] [--project]
245
+ code-intelligence-skills list
246
+
247
+ Agents: ${Object.keys(AGENTS).join(", ")}, all (comma separated)
248
+ claude -> ~/.claude/skills/${SKILL_NAME}
249
+ others -> ~/.agents/skills/${SKILL_NAME} (Codex, OpenCode, Pi and Gentle Shell read this directory)
250
+ With --project the same paths are used relative to the current directory instead of your home.
251
+
252
+ Options:
253
+ --dry-run Show what would change, change nothing
254
+ --force Replace/remove files even if they were modified after installation
255
+ --home <p> Use <p> instead of your home directory
256
+ -h, --help / -v, --version
257
+
258
+ The skill needs the code-intel CLI: https://github.com/micio86dev/code-intelligence
259
+ Exit codes: 0 ok, 1 something was refused, 2 usage error.
260
+ `;
261
+
262
+ export function run(argv, { cwd = process.cwd(), out = (s) => process.stdout.write(s), err = (s) => process.stderr.write(s) } = {}) {
263
+ let parsed;
264
+ try {
265
+ parsed = parseArgs({
266
+ args: argv,
267
+ allowPositionals: true,
268
+ options: {
269
+ agent: { type: "string", short: "a" },
270
+ project: { type: "boolean" },
271
+ "dry-run": { type: "boolean" },
272
+ force: { type: "boolean" },
273
+ home: { type: "string" },
274
+ help: { type: "boolean", short: "h" },
275
+ version: { type: "boolean", short: "v" },
276
+ },
277
+ });
278
+ } catch (e) {
279
+ err(`error: ${e.message}\n`);
280
+ return 2;
281
+ }
282
+ const { values: v, positionals } = parsed;
283
+ if (v.version) {
284
+ out(`${packageVersion()}\n`);
285
+ return 0;
286
+ }
287
+ const cmd = positionals[0];
288
+ if (v.help || !cmd) {
289
+ out(HELP);
290
+ return cmd || v.help ? 0 : 2;
291
+ }
292
+ try {
293
+ if (cmd === "list") {
294
+ for (const [a, s] of Object.entries(AGENTS)) out(`${a.padEnd(13)} ${s.label.padEnd(14)} ~/${s.dir}/${SKILL_NAME}\n`);
295
+ return 0;
296
+ }
297
+ if (!["install", "uninstall", "status"].includes(cmd)) throw new UsageError(`Unknown command '${cmd}'`);
298
+ if (positionals.length > 1) throw new UsageError(`Unexpected argument '${positionals[1]}'`);
299
+
300
+ let agents = (v.agent ?? "").split(",").map((s) => s.trim()).filter(Boolean);
301
+ if (agents.includes("all")) agents = Object.keys(AGENTS);
302
+ if (agents.length === 0) {
303
+ if (cmd !== "status") throw new UsageError("Name the agent(s) to use: --agent claude,codex,opencode,pi,gentle-shell (or all)");
304
+ agents = Object.keys(AGENTS);
305
+ }
306
+ const home = v.home ? resolve(cwd, v.home) : homedir();
307
+ const targets = resolveTargets(agents, { project: Boolean(v.project), home, cwd });
308
+ const opts = { dryRun: Boolean(v["dry-run"]), force: Boolean(v.force) };
309
+ let refused = false;
310
+ for (const t of targets) {
311
+ const who = t.agents.map((a) => AGENTS[a].label).join(", ");
312
+ if (cmd === "status") {
313
+ const s = status(t);
314
+ out(`${who}: ${s.state}${s.version ? ` (v${s.version})` : ""}${s.modified.length ? ` modified: ${s.modified.join(", ")}` : ""}\n ${t.dir}\n`);
315
+ continue;
316
+ }
317
+ const r = cmd === "install" ? install(t, opts) : uninstall(t, opts);
318
+ if (r.action === "refused") refused = true;
319
+ out(`${who}: ${r.action}${r.reason ? `: ${r.reason}` : ""}${r.note ? ` (${r.note})` : ""}\n ${t.dir}\n`);
320
+ }
321
+ return refused ? 1 : 0;
322
+ } catch (e) {
323
+ if (e instanceof UsageError) {
324
+ err(`error: ${e.message}\n`);
325
+ return 2;
326
+ }
327
+ err(`internal error: ${e.message}\n`);
328
+ return 70;
329
+ }
330
+ }
331
+
332
+ // Run only when executed directly. npm's bin shim is a symlink, so compare real paths (a plain
333
+ // path comparison silently does nothing when installed through npm).
334
+ function isMain() {
335
+ if (!process.argv[1]) return false;
336
+ try {
337
+ return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
338
+ } catch {
339
+ return false;
340
+ }
341
+ }
342
+ if (isMain()) {
343
+ process.exitCode = run(process.argv.slice(2));
344
+ }
package/package.json CHANGED
@@ -1,6 +1,51 @@
1
1
  {
2
2
  "name": "code-intelligence-skills",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Agent skill and installer that teach Claude Code, Codex, OpenCode, Pi and Gentle Shell when and how to use the code-intel CLI.",
5
+ "license": "MIT",
6
+ "author": "micio86dev",
7
+ "type": "module",
8
+ "keywords": [
9
+ "pi-package",
10
+ "agent-skills",
11
+ "claude-code",
12
+ "codex",
13
+ "opencode",
14
+ "gentle-shell",
15
+ "security",
16
+ "code-intelligence"
17
+ ],
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/micio86dev/code-intelligence-skills.git"
21
+ },
22
+ "homepage": "https://github.com/micio86dev/code-intelligence-skills#readme",
23
+ "bugs": {
24
+ "url": "https://github.com/micio86dev/code-intelligence-skills/issues"
25
+ },
26
+ "bin": {
27
+ "code-intelligence-skills": "installer/install.mjs"
28
+ },
29
+ "files": [
30
+ "installer",
31
+ "skills",
32
+ "snippets",
33
+ ".claude-plugin",
34
+ "docs",
35
+ "README.md",
36
+ "LICENSE",
37
+ "CHANGELOG.md"
38
+ ],
39
+ "engines": {
40
+ "node": ">=22"
41
+ },
42
+ "pi": {
43
+ "skills": [
44
+ "./skills"
45
+ ]
46
+ },
47
+ "scripts": {
48
+ "test": "node --test --test-concurrency=1 \"test/**/*.test.mjs\"",
49
+ "validate": "node scripts/validate.mjs"
50
+ }
51
+ }
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: code-intelligence
3
+ description: "Trigger: security check, is this change safe, scan for secrets or vulnerabilities, vulnerable dependencies, which tests are affected by my change, are my tests good enough, mutation testing, before commit or PR. Runs the `code-intel` CLI to get deterministic evidence (gitleaks, semgrep, osv-scanner, ast-grep architecture rules, codegraph, StrykerJS) about the files that changed. Not for general code review, style or refactoring."
4
+ compatibility: "Needs the code-intel CLI (https://github.com/micio86dev/code-intelligence) on PATH and a git repository. Engines (gitleaks, semgrep, osv-scanner, ...) are installed separately by the user."
5
+ metadata:
6
+ repository: https://github.com/micio86dev/code-intelligence-skills
7
+ ---
8
+
9
+ # code-intelligence
10
+
11
+ `code-intel` runs real scanners on **what changed** and prints normalized findings. It gives you evidence; interpreting it and acting on it is your job. It has no LLM and no background process.
12
+
13
+ ## First use in a repository
14
+
15
+ 1. `command -v code-intel`. If it is missing, **tell the user** how to install it (README of the code-intelligence repository). Do not install tools silently.
16
+ 2. `code-intel doctor`. A missing engine is reported, not fatal. Mention what is missing; do not install engines without asking.
17
+
18
+ ## Pick the smallest check that answers the question
19
+
20
+ | Situation | Command | Cost |
21
+ |---|---|---|
22
+ | You changed code that touches input handling, auth, SQL, shell, crypto, file paths, dependencies, config or secrets, and are about to call the work done | `code-intel scan --format json` | seconds |
23
+ | Before a commit | `code-intel scan --staged --format json` | seconds |
24
+ | Before a PR, whole branch | `code-intel scan --since <base-branch> --format json` | seconds |
25
+ | "Which tests should I run for this change?" | `code-intel impact --json` | seconds |
26
+ | "Are my tests good enough?" or risky logic is about to merge (JS/TS) | `code-intel mutate --json` | minutes |
27
+ | The user asks for a full audit | `code-intel scan --all -p deep --format json` | slow: ask first |
28
+
29
+ **Do not** scan after every edit, on documentation-only changes, or run `deep` / `mutate` unprompted. They cost time the user is waiting for.
30
+
31
+ ## Reading the result
32
+
33
+ - **Exit code** `0` ok · `1` findings at or above the threshold · `2` usage/config error · **`3` incomplete: not a pass.**
34
+ - `complete: false` means some engine did not run (`engines[].status` is `unavailable`, `timeout` or `error`, with a `reason`). Say which checks did not run. Never report "clean" or "secure" for an incomplete scan.
35
+ - Each finding has `severity`, `file`, `line`, `ruleId`, `message`, `remediation`, a stable `fingerprint`, and `alsoReportedBy`.
36
+ - `summary.suppressed.outsideChangedLines > 0` means SAST findings on lines the change did not touch were hidden on purpose. Mention it when the change is security-sensitive; `--all` shows them.
37
+ - `config.inEffect` lists settings the **repository itself** supplied (`.code-intel.json`, `.gitleaks.toml`, a baseline...). A repository can configure a scan to find less. If it is non-empty and you are reviewing code you did not write, say so, and re-run with `--ignore-repo-config`.
38
+ - No findings means "these checks found nothing". It is not proof of safety. Say it that way.
39
+
40
+ Field details: `references/findings.md`. Which command for which situation: `references/profiles.md`.
41
+
42
+ ## Acting on findings
43
+
44
+ - Fix real problems in the code you changed, then **re-run the same command** to confirm.
45
+ - **Secrets:** never print, copy or commit the value. Tell the user to rotate the credential; removing it from the file is not enough once it was committed.
46
+ - **Dependencies:** upgrade as `remediation` says, then run the project's tests.
47
+ - **False positive:** explain why in one or two sentences. Suppress only with the user's agreement, narrowly and with a reason (`# nosemgrep: <rule-id>` on the line, or a `.gitleaksignore` entry).
48
+ - **Do not** edit `.code-intel.json`, the baseline, `.gitleaks.toml` or exclude globs to make findings disappear. `code-intel baseline` is for when the user decides to accept the current state.
49
+ - **mutate:** a surviving mutant is a behavior change your tests did not notice. Add or strengthen a test for that line, then re-run on that file.
50
+
51
+ ## Privacy
52
+
53
+ `osv-scanner` sends package names and versions from lockfiles to the OSV API, and semgrep registry rulesets download rules (no source code leaves the machine). If the user forbids that, run `code-intel scan -e secrets,sast` with local semgrep rules.
54
+
55
+ ## Feeding a review
56
+
57
+ When a reviewer or review tool asks for scanner evidence, give it the findings (rule, file:line, severity, remediation) from the JSON, never a secret value. See `references/gentle-review-evidence.md`.
58
+
59
+ ## References (load only when needed)
60
+
61
+ - `references/findings.md`: JSON fields, severities, fingerprints, baseline
62
+ - `references/profiles.md`: scopes, profiles, engines, what each costs
63
+ - `references/gentle-review-evidence.md`: passing evidence to Gentle AI review lenses
64
+ - `references/property-testing.md`: when and how to add property-based tests (technique, no engine)
@@ -0,0 +1,33 @@
1
+ # Reading `code-intel scan --format json`
2
+
3
+ Top level: `schemaVersion` (1), `profile`, `target.mode` (`changed|staged|since|all`), `complete`, `durationMs`, `engines[]`, `summary`, `findings[]`, `exitCode`.
4
+
5
+ ## engines[]
6
+
7
+ `status` is one of `ok`, `findings`, `skipped` (with a `reason`, e.g. "no lockfile or manifest in scope"), `unavailable` (engine not installed; `reason` has the install hint), `timeout`, `error`. Only `unavailable`, `timeout` and `error` make `complete` false. `warnings[]` are non-fatal notes, e.g. a changed source file semgrep skipped because of its default ignores.
8
+
9
+ ## findings[]
10
+
11
+ | Field | Meaning |
12
+ |---|---|
13
+ | `severity` | `info < low < medium < high < critical`. The default failing threshold is `high` |
14
+ | `category` | `secrets`, `sast`, `deps`, `architecture` |
15
+ | `file`, `line`, `endLine` | Repo-relative POSIX path; `line` is `null` for dependency findings (the lockfile is the location) |
16
+ | `ruleId` | The engine's rule or advisory id (`GHSA-...`, `aws-access-token`, `semgrep....`) |
17
+ | `message`, `remediation` | What is wrong and, where known, how to fix it (`Upgrade lodash to 4.17.21 or later.`) |
18
+ | `fingerprint` | Stable across line shifts; use it to say "same finding as before" |
19
+ | `alsoReportedBy` | Other engines that found the same secret; already merged, not duplicated |
20
+
21
+ A finding never contains the matched secret or the source line.
22
+
23
+ ## config
24
+
25
+ `config.file` (the repository's `.code-intel.json` if present), `config.ignored` (`--ignore-repo-config` was used) and `config.inEffect`: the non-default settings and files the repository supplied (failOn, extra excludes, `.gitleaks.toml`, `.gitleaksignore`, `.semgrepignore`, a baseline). These can make a scan find less; for code you did not write, re-run with `--ignore-repo-config`.
26
+
27
+ ## summary
28
+
29
+ `bySeverity`, `failOn`, `newOnly`, and `suppressed.{outsideChangedLines, baseline}`: counts of findings hidden on purpose (unchanged lines; already in the baseline). Tell the user when these are non-zero and relevant.
30
+
31
+ ## Baseline
32
+
33
+ `code-intel baseline` records today's findings; `code-intel scan --new-only` then fails only on new ones. Use only when the user chooses to accept the current state.
@@ -0,0 +1,19 @@
1
+ # Passing scanner evidence to Gentle AI review lenses
2
+
3
+ Gentle AI's `gentle-ai review` runs LLM reviewer subagents (risk, resilience, readability, reliability) over a frozen diff. Those reviewers have no tools: they cannot run commands. The `risk` lens asks for "concrete exploit or scanner evidence". The parent agent (you) can supply it.
4
+
5
+ What this integration does and does not do:
6
+
7
+ - **Does:** you run `code-intel scan --format json` (and `--since <base>` for a branch) *before* delegating or starting a review, and include a short evidence block in the context you hand over.
8
+ - **Does not:** modify or hook into `gentle-ai review`, its receipts, or its frozen context. That pipeline is owned by Gentle AI. This path has not been validated end to end through `gentle-ai review` itself.
9
+
10
+ ## Evidence block (paste into the review context)
11
+
12
+ ```
13
+ Scanner evidence (code-intel 0.1.0, profile quick, scope: changed, complete: true)
14
+ - HIGH semgrep src/auth.ts:42 <ruleId>: <message> fix: <remediation>
15
+ - MEDIUM osv-scanner package-lock.json GHSA-xxxx: lodash@4.17.15 ... fix: Upgrade lodash to 4.17.21
16
+ Not run: osv-scanner (unavailable: not installed)
17
+ ```
18
+
19
+ Rules: include `complete` and every engine that did not run; list findings by rule id, location, severity and remediation; never include secret values; do not claim "no vulnerabilities", say "these checks found nothing".
@@ -0,0 +1,24 @@
1
+ # Scopes, profiles and cost
2
+
3
+ | Flag | Scope |
4
+ |---|---|
5
+ | (none) / `--changed` | Uncommitted changes vs `HEAD`, plus untracked files |
6
+ | `--staged` | Only what is staged |
7
+ | `--since <ref>` | Working tree vs a ref, e.g. `main` |
8
+ | `--all` | Whole repository |
9
+
10
+ | Profile | Categories | Per-engine time limit |
11
+ |---|---|---|
12
+ | `quick` (default) | secrets (gitleaks), sast (semgrep), deps (osv-scanner, trivy fallback) | 60 s |
13
+ | `deep` | + architecture (ast-grep rules from the project's `sgconfig.yml`) | 10 min |
14
+
15
+ Typical quick scan of a few changed files: a few seconds (semgrep start-up dominates). Select engines with `-e secrets,sast,deps,architecture` or by engine name.
16
+
17
+ ## Other commands
18
+
19
+ - `code-intel impact [--staged | --since <ref>] --json`: tests affected by the change. `method: "codegraph"` is transitive (needs `codegraph init` once); `method: "heuristic"` lists only direct importers and name matches and says so in `notes`.
20
+ - `code-intel mutate [files] [--min-score N] --json`: JavaScript/TypeScript only, needs `@stryker-mutator/core` in the project. Mutates only the changed lines. Minutes, not seconds. Keep the project's `npm test` to tests only (a linter in it makes every mutant look killed). A score of 0% usually means the test command ran no tests.
21
+
22
+ ## When something is missing
23
+
24
+ `unavailable` engines print an install hint. Offer it to the user; do not run installers yourself. `--allow-missing` downgrades a missing engine to a warning: only use it if the user accepts that check not running.
@@ -0,0 +1,14 @@
1
+ # Property-based testing (technique, not an engine)
2
+
3
+ `code-intel` does not run property-based tests: they are a test-library technique, so there is nothing to wrap. Suggest them when `code-intel mutate` shows survivors in pure logic (parsers, validators, serializers, arithmetic, sorting/merging, state machines), because properties cover input ranges that hand-picked examples miss.
4
+
5
+ | Language | Library |
6
+ |---|---|
7
+ | JavaScript/TypeScript | `fast-check` |
8
+ | Python | `hypothesis` |
9
+ | Rust | `proptest` |
10
+ | Go | `testing/quick`, `gopter` |
11
+
12
+ Useful properties: round-trip (`decode(encode(x)) == x`), idempotence (`f(f(x)) == f(x)`), invariants (sorted output is a permutation of the input), "never throws" for arbitrary input, and agreement with a slow, obviously-correct reference implementation.
13
+
14
+ Workflow: take a surviving mutant, state the property it violates, write it as a property test, re-run `code-intel mutate <file>` and confirm the mutant is now killed. Keep generators small and seeds reproducible. Do not add the dependency without asking the user.
@@ -0,0 +1,3 @@
1
+ ## Code intelligence (optional always-on hint)
2
+
3
+ When a change touches input handling, authentication, SQL, shell commands, file paths, cryptography, dependencies or secrets, run `code-intel scan --format json` before reporting the work done, and treat exit code 3 as "checks did not complete", never as a pass. Do not scan after every edit and do not run `deep` or `mutate` unprompted. Details: the `code-intelligence` skill.