Skip to content

Commit 3d854f1

Browse files
jothimani-rajendranjothimani-rajendran
authored
Merge pull request #6 from open-coder-ai/docs/readme-landing
docs: rewrite README as a landing page
2 parents d32ebd0 + 87e7068 commit 3d854f1

1 file changed

Lines changed: 52 additions & 98 deletions

File tree

‎README.md‎

Lines changed: 52 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,29 @@
1-
# chock-copilot-plugins
1+
<p align="center">
2+
<img src="https://raw.githubusercontent.com/open-coder-ai/chock/main/docs/assets/logo.svg" alt="chock logo" width="110">
3+
</p>
4+
5+
<h1 align="center">chock-copilot-plugins</h1>
6+
7+
<p align="center"><strong>Chock policies for Copilot CLI and VS Code agent mode — a real <code>PreToolUse</code> deny hook where the client supports it.</strong></p>
8+
9+
<p align="center">
210

311
[![Generated-only](https://github.com/open-coder-ai/chock-copilot-plugins/actions/workflows/generated-only.yml/badge.svg)](https://github.com/open-coder-ai/chock-copilot-plugins/actions/workflows/generated-only.yml)
412
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
513
[![Contribute upstream](https://img.shields.io/badge/contribute-chock--catalog-8957e5)](https://github.com/open-coder-ai/chock-catalog)
614

7-
Chock policies packaged as installable plugins for **GitHub Copilot** — Copilot CLI and
8-
VS Code agent mode. Guard policies ship a real `PreToolUse` hook, so a matched destructive
9-
command is **denied in the session**, not just discouraged.
15+
</p>
1016

11-
<img src="docs/assets/hero.svg" alt="Animated replay: an agent runs rm -rf and the chock guard denies it before it runs (Copilot CLI / VS Code, exit 2)" width="720">
17+
<p align="center">
18+
<img src="https://raw.githubusercontent.com/open-coder-ai/chock/main/docs/assets/demo.gif" alt="Chock's demo: an agent runs a destructive command and a guard plugin denies it before it executes" width="760">
19+
</p>
1220

13-
**This repository is generated.** Every file is compiled from policy sources in
14-
[chock-catalog](https://github.com/open-coder-ai/chock-catalog) by
15-
[chock](https://github.com/open-coder-ai/chock). Pull requests here are closed with a
16-
pointer to the catalog — review belongs where the source is.
17-
18-
## Which clients this works with
19-
20-
These packages use the **Claude plugin format**, which VS Code and GitHub Copilot CLI read
21-
natively (VS Code auto-detects the format and sets `CLAUDE_PLUGIN_ROOT` for the hook). The
22-
same packages also work in Claude Code. This repository is the
23-
**Copilot-branded** distribution of that content; the format-named distribution lives at
24-
[chock-claude-plugins](https://github.com/open-coder-ai/chock-claude-plugins) and the two
25-
are byte-identical where they overlap, because both are generated from the same catalog.
26-
Cursor and Codex users are served by
27-
[chock-cursor-plugins](https://github.com/open-coder-ai/chock-cursor-plugins) and
28-
[chock-codex-plugins](https://github.com/open-coder-ai/chock-codex-plugins), which carry
29-
those vendors' own formats and deny dialects.
21+
An agent you're running can already touch your shell, your git history, and your CI config.
22+
You want it to move fast without being the reason a stray `rm -rf` actually happens. Telling
23+
it to be careful in a prompt is not a guarantee; a plugin that can refuse the command is
24+
closer to one — and it should be honest about which of those two it is.
25+
26+
## Install
3027

3128
```
3229
# VS Code / GitHub Copilot: add this repository as a plugin marketplace, then install a
@@ -35,71 +32,37 @@ those vendors' own formats and deny dialects.
3532
# https://code.visualstudio.com/docs/agent-customization/agent-plugins
3633
```
3734

38-
Clients that read the Agent Plugins 1.0 standard instead can use the `agent-plugins/` tree
39-
(advisory: the standard carries skills, not hooks).
40-
41-
## What a plugin actually does — read this before installing
42-
43-
Chock's rule is that a claim must match a mechanism, and that rule applies to these
44-
packages: they are not equally strong and they say so in each description.
45-
46-
- **Guard policies** (e.g. `block-destructive-commands`) ship a `PreToolUse` hook and are
47-
**session-enforced** where the host honours it — the hook exits non-zero and the client
48-
refuses the call. This needs `python3` and a usable shell on PATH. Without them,
49-
fail-open clients allow silently and fail-closed clients refuse matched commands; on
50-
Windows, disable the `python3` Microsoft Store alias or install Python. Every guard's
51-
description states this posture verbatim.
52-
- **Advisory policies** are a skill the client reads. They shape behaviour; they cannot
53-
block anything on their own.
54-
55-
See **[PLUGINS.md](PLUGINS.md)** for the full list: every policy, its version, whether it
56-
enforces or advises in this client, and a link to its page in the catalog. That file is
57-
generated from the packages themselves, so it cannot drift from what is published.
58-
59-
**A plugin is not the same as adopting Chock.** A plugin governs one person's session on
60-
one client. It cannot enforce anything at commit time, it does not travel with a clone, and
61-
it does not run in CI. Repository-wide enforcement — git hooks and a CI gate that a
62-
`--no-verify` cannot skip — comes from installing Chock in the repo:
35+
These packages use the Claude plugin format, which VS Code and GitHub Copilot CLI read
36+
natively (VS Code auto-detects the format and sets `CLAUDE_PLUGIN_ROOT` for the hook).
6337

64-
```bash
65-
pip install chock
66-
chock init && chock sync --ci
67-
```
38+
## What you get
6839

69-
## Layout
40+
Guard policies ship a `PreToolUse` hook and are session-enforced where the host honours it —
41+
the hook exits non-zero and the client refuses the call. This needs `python3` and a usable
42+
shell on PATH: fail-open clients allow silently without them, fail-closed clients refuse
43+
matched commands. Advisory policies are a skill the client reads; they shape behaviour but
44+
cannot block anything on their own. See **[PLUGINS.md](PLUGINS.md)** for the full list: each
45+
policy, its version, whether it enforces or advises in this client, and a catalog link.
7046

71-
```
72-
claude/<policy-id>/ Claude-layout packages (hooks where the policy has a guard) — Copilot reads these natively
73-
copilot/<policy-id>/ Agent Plugins 1.0 layout with the same hook under com.github.copilot/ — for spec-validating marketplaces
74-
agent-plugins/<policy-id>/ plain Agent Plugins 1.0 packages (advisory: the standard itself has no hooks)
75-
.claude-plugin/marketplace.json the index VS Code and Claude Code read
76-
.github/plugin/marketplace.json byte-identical copy, the path Copilot CLI reads
77-
```
47+
## Generated from chock-catalog
7848

79-
The trees are deliberately separate. The same policy is enforced in a package that ships a
80-
hook and advisory in a package that cannot carry one — so a shared skill file would have to
81-
make a claim that is false for one of them. `claude/` and `copilot/` run byte-identical
82-
hooks; they differ only in where the manifest and hook file live, because marketplace
83-
validators disagree about that.
84-
85-
## Trust
86-
87-
- **Generated only:** CI regenerates from the pinned catalog and fails on any difference,
88-
so content here cannot be hand-edited into something the catalog never published.
89-
- **Byte-identical guards:** guard scripts and the hook adapter are verbatim copies of
90-
their sources in the framework — a plugin cannot quietly behave differently from a
91-
repository install.
92-
- **Best-effort, not a boundary:** guards are pattern-based filters. Aliases, quoting, and
93-
unusual paths can evade them. See
94-
[SECURITY.md](https://github.com/open-coder-ai/chock/blob/main/SECURITY.md) and the
95-
[assurance case](https://github.com/open-coder-ai/chock/blob/main/docs/assurance-case.md).
49+
Every file here is compiled from policy sources in
50+
[chock-catalog](https://github.com/open-coder-ai/chock-catalog) by
51+
[chock](https://github.com/open-coder-ai/chock). Pull requests against this repository are
52+
closed automatically — open them against the catalog instead.
53+
54+
- **Generated only:** CI regenerates from the pinned catalog and fails on any difference.
55+
- **Byte-identical guards:** guard scripts and the hook adapter are verbatim copies of their
56+
framework sources.
57+
- **Best-effort, not a boundary:** guards are pattern-based filters; see
58+
[SECURITY.md](https://github.com/open-coder-ai/chock/blob/main/SECURITY.md).
9659
- **Tested upstream, and gated:** every policy ships an eval suite
9760
(`base/<policy>/evals/suite.yaml`) in the catalog, and the publish workflow runs
9861
`chock check` and `chock check --only evals` before packaging anything — a policy whose
9962
evals fail cannot reach this repository. The tests live in the catalog because the policy
10063
source does; this repository is compiled output.
101-
- **This README is the exception:** it is the one file the publisher never writes, so it
102-
alone sits outside the generated-only guarantee. Everything else here regenerates.
64+
- This README is the exception: the one hand-written file in this repository, so it alone
65+
sits outside the generated-only guarantee.
10366

10467
### Verify it yourself
10568

@@ -126,35 +89,26 @@ checked without rebuilding the rest.
12689
**If you are listing these plugins in a marketplace,** pin both a tag and the full commit
12790
SHA. The tag names the release; the SHA is what holds the reviewed bytes still.
12891

129-
13092
## Contributing
13193

132-
Pull requests that change packages here are closed automatically, and not because the
133-
change is unwelcome: every package is compiled from the catalog, so an edit here would be
134-
overwritten at the next publish and would carry none of a policy's checks. What is welcome,
135-
and where it goes:
136-
13794
| You want to | Go to |
13895
| :--- | :--- |
13996
| Fix or add a policy | [chock-catalog](https://github.com/open-coder-ai/chock-catalog/blob/main/CONTRIBUTING.md) — it reaches every client from there, including this one |
14097
| Report that a guard did or did not block on your Copilot CLI or VS Code version | an issue on [chock](https://github.com/open-coder-ai/chock/issues/new/choose), which records the witnessed-blocking claims these packages carry; "it fails open where you say it fails closed" is the most useful result you can send |
14198
| Report a bug in how packages are generated | [chock](https://github.com/open-coder-ai/chock/issues/new/choose), where the emitter lives |
14299
| Fix this README | here — it is the one hand-written file in the repository |
143100

144-
## Part of the open-coder-ai family
145-
146-
Everything under [open-coder-ai](https://github.com/open-coder-ai) is built on one rule: a claim must match a
147-
mechanism. Where this repository sits among the others:
148-
149-
| Repository | What it is |
150-
| :--- | :--- |
151-
| [chock](https://github.com/open-coder-ai/chock) | The framework: write a policy once, enforce it on git hooks, CI, and every agent |
152-
| [chock-catalog](https://github.com/open-coder-ai/chock-catalog) | The policies, each graded by what it actually enforces |
153-
| [agentseam](https://github.com/open-coder-ai/agentseam) | The primitives layer under chock: one handler API over every agent's hooks, with a capability matrix that carries its provenance |
154-
| [context-report](https://github.com/open-coder-ai/context-report) | A signed report format for whether a plugin, hook, skill or `AGENTS.md` actually works |
155-
| [chock-threat-intel](https://github.com/open-coder-ai/chock-threat-intel) | A weekly, human-reviewed threat digest scored against the catalog |
156-
| [chock-claude-plugins](https://github.com/open-coder-ai/chock-claude-plugins) · [cursor](https://github.com/open-coder-ai/chock-cursor-plugins) · [codex](https://github.com/open-coder-ai/chock-codex-plugins) | The same catalog compiled for the other clients; generated only, like this one |
157-
| [chock-quickstart](https://github.com/open-coder-ai/chock-quickstart) · [chock-example](https://github.com/open-coder-ai/chock-example) | Template repositories: exactly what `chock init` leaves behind, and a working adoption with one policy per layer |
101+
## Part of open-coder-ai
102+
103+
| | |
104+
|---|---|
105+
| [agentseam](https://github.com/open-coder-ai/agentseam) | the primitives — one handler API and a verified capability matrix across 16 agents |
106+
| [chock](https://github.com/open-coder-ai/chock) | the compiler — one policy into git hooks, CI gates and native pre-tool hooks |
107+
| [chock-catalog](https://github.com/open-coder-ai/chock-catalog) | the policies — 39, each labelled enforced or advisory, with replayed evals |
108+
| [context-report](https://github.com/open-coder-ai/context-report) | the evidence — a signed report of whether an agent artifact actually works |
109+
| [chock-threat-intel](https://github.com/open-coder-ai/chock-threat-intel) | the threat ledger the catalog's policies answer to |
110+
| chock-{claude,cursor,copilot,codex}-plugins | the catalog, packaged for each agent's plugin format (generated) |
111+
| chock-quickstart · chock-example | template repos: what `chock init` leaves behind, and a full adoption |
158112

159113
## License
160114

0 commit comments

Comments
 (0)