Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
c8dfa8b
Add design spec: Load a private repository's agent instructions witho…
danielhanold Oct 6, 2026
c306d18
Update design spec: Load a private repository's agent instructions wi…
danielhanold Oct 6, 2026
6b3e64f
feat(document): neutral dckt: marker namespace for managed blocks
danielhanold Oct 6, 2026
4e80ab8
feat(install): retire one managed block and write another in the same…
danielhanold Oct 6, 2026
26160ad
feat(install): hook-entries target kind for Claude Code and Cursor ho…
danielhanold Oct 6, 2026
9e062f7
feat(harness): plan the private-instructions triggers for all four ha…
danielhanold Oct 6, 2026
5ba7a56
feat(reposeed): plan a private repository's instructions file
danielhanold Oct 6, 2026
5fa0748
feat(app): write a private repository's instructions to .git/dckt, ne…
danielhanold Oct 6, 2026
e6ecc29
feat(cli): docket instructions prints a private repository's agent in…
danielhanold Oct 6, 2026
3b0dcb2
docs(skills): private-repository instructions file and its user-level…
danielhanold Oct 6, 2026
2f31778
test: fresh-session acceptance of private-instructions delivery
danielhanold Oct 6, 2026
64cb9c7
test(process): kill the supervisor before its command in the unprovab…
danielhanold Oct 6, 2026
e38c134
fix(reposeed): keep the Codex clause in the private file on a scoped …
danielhanold Oct 6, 2026
4593b6d
fix(install): skip a hooks file that is not a regular file instead of…
danielhanold Oct 6, 2026
0839691
docs(install): name the session triggers an install writes and uninst…
danielhanold Oct 6, 2026
219c898
fix(install): skip a hooks file docket cannot parse instead of failin…
danielhanold Oct 6, 2026
6d50d0a
fix(install): retire changed trigger commands and linked-worktree sur…
danielhanold Oct 6, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/install/claude-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,13 @@ calling out, after a word on what the install writes.
17 agent wrappers are written to `~/.claude/agents/docket-*.md`, each carrying the model and
effort resolved from your global config over the built-in table. Nothing is written per
repository for these.
- **Two `SessionStart` hooks in `~/.claude/settings.json`.** These content-free hooks run
`dckt instructions --hook claude --section dispatch` and
`dckt instructions --hook claude --section lessons`, which print nothing outside a private
repository, so they are inert everywhere else. A `settings.json` docket cannot edit in place (a
symlink, or a file docket cannot parse, such as one with comments) is left untouched, and the
run warns about it. Uninstall removes the hooks
only while they are unchanged.
- **The dispatch block in `CLAUDE.md`, on opt-in only.** When a repository's `.docket.yml` or
`.docket.local.yml` lists `claude` in `agent_harnesses`, the install reconciles a
marker-bounded `docket` dispatch block in that repository's `CLAUDE.md`. When Codex or opencode is
Expand Down
7 changes: 6 additions & 1 deletion docs/install/codex.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Codex: running docket under Codex

Codex is a first-class docket harness. An install writes two kinds of Codex artifact:
Codex is a first-class docket harness. An install writes three kinds of Codex artifact:

- **User-level skills and agent wrappers.** docket's skills are linked under the harness-neutral
`~/.agents/skills/` root, which Codex reads, and its 17 agent wrappers are written to
Expand All @@ -13,6 +13,11 @@ Codex is a first-class docket harness. An install writes two kinds of Codex arti
`.toml` agent (Codex reads `AGENTS.md`; it has no analog of Cursor's `.mdc` rule). The block is
**committed and machine-neutral**: it carries only agent names and routing instructions, never a
model ID or effort value, so it is identical in every clone (ADR-0036).
- **A `dckt:private-instructions` pointer block in `~/.codex/AGENTS.md`.** This user-level,
content-free block asks Codex to run `dckt instructions` once at the start of a session and to
follow whatever it prints as the repository's own `AGENTS.md`. Outside a private repository the
command prints nothing, so the block is inert. It needs no opt-in, and uninstall removes it only
while it is unchanged.

### The opt-in you need

Expand Down
5 changes: 5 additions & 0 deletions docs/install/cursor.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,11 @@ small, stable permission configuration, because docket must run **outside** Curs
`description`, and a `model:` line wherever a model resolves, with any reasoning effort encoded
inside the model value. Agent overrides come from your global config only. Nothing is written
per repository for these.
- **A `sessionStart` hook in `~/.cursor/hooks.json`.** This content-free hook runs
`dckt instructions --hook cursor`, which prints nothing outside a private repository, so it is
inert everywhere else. A `hooks.json` docket cannot edit in place (a symlink, or a file docket
cannot parse, such as one with comments) is left untouched, and the run warns about it. Uninstall removes the hook only while it is
unchanged.
- **The dispatch rule, on opt-in only.** When a repository's `.docket.yml` or `.docket.local.yml`
lists `cursor` in `agent_harnesses`, the install writes `.cursor/rules/docket-dispatch.mdc` in that
repository. It tells Cursor to dispatch a docket workflow to its matching agent instead of running
Expand Down
14 changes: 13 additions & 1 deletion docs/install/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,16 @@ harness, after editing a config file, and after every version update). A single
global agent wrappers** — the model/effort-pinned subagent copies, resolved from your global
config over docket's built-in defaults. Wrappers are user-level only; no repository carries its
own copies.
- **Installs one content-free session trigger per harness**, so a private repository's agent
instructions load without any file in that repository: two Claude Code `SessionStart` hooks in
`~/.claude/settings.json` (`dckt instructions --hook claude --section dispatch` and
`dckt instructions --hook claude --section lessons`), a Cursor `sessionStart` hook in
`~/.cursor/hooks.json` (`dckt instructions --hook cursor`), the OpenCode plugin
`~/.config/opencode/plugins/dckt-instructions.js`, and a `dckt:private-instructions` pointer
block in `~/.codex/AGENTS.md`. Each one only runs `dckt instructions`, which prints nothing
outside a private repository, so a trigger is inert everywhere else. A hooks file docket cannot
edit in place (a symlink, or a file docket cannot parse, such as one with comments) is left
untouched, and the run warns about it.
- **Retires the old global parent-facing dispatch blocks** that earlier docket versions wrote into
your personal `~/.claude/CLAUDE.md` and the other harnesses' global instruction files, while
keeping the global skills and agent wrappers. Removal is **proof-gated** — the engine deletes a
Expand Down Expand Up @@ -75,7 +85,9 @@ Claude-Code-only user can stop here. To pin a model or change a default on this
## Uninstalling docket

`docket uninstall` removes the harness integrations docket recorded for you — the
global `skills/` symlinks and `agents/` wrappers it wrote — and nothing else. With
global `skills/` symlinks, the `agents/` wrappers, and the session triggers it wrote
(the hook entries, the OpenCode plugin, and the Codex pointer block, each removed only
while it is unchanged) — and nothing else. With
no flag it removes **every recorded harness**; a repeatable **`--harness <name>`**
limits the run to the harness(es) you name, and duplicate `--harness` values are
de-duplicated before anything is touched. **`--dry-run`** reports exactly what a
Expand Down
6 changes: 5 additions & 1 deletion docs/install/opencode.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# opencode: running docket under opencode

opencode is a first-class docket harness. An install writes two kinds of opencode artifact:
opencode is a first-class docket harness. An install writes three kinds of opencode artifact:

- **User-level skills and agent definitions**, under
`${XDG_CONFIG_HOME:-~/.config}/opencode/`: docket's skills are linked under `skills/`, and its 17
Expand All @@ -13,6 +13,10 @@ opencode is a first-class docket harness. An install writes two kinds of opencod
block, **shared with Codex**: opencode reads the same committed project-root `AGENTS.md`, so one
managed block serves both. A repo targeting either harness gets it; a repo targeting both gets it
exactly once. It is **committed and machine-neutral** (ADR-0036).
- **The `plugins/dckt-instructions.js` plugin**, under the same user-level opencode directory. This
content-free plugin runs `dckt instructions` and adds whatever it prints to the system prompt.
Outside a private repository the command prints nothing, so the plugin is inert. It needs no
opt-in, and uninstall removes it only while it is unchanged.

### The opt-in you need

Expand Down
Loading
Loading