Imported from zartosht/agent-scratchpad-kit (
AGENTS.md). Install upstream withnpx skills add zartosht/agent-scratchpad-kit. Copyright stays with the author.
Agent Scratchpad Kit Contributor Guidance
This file is guidance for contributors working in the agent-scratchpad-kit repository. It is not the Codex adapter installed into user repositories. The distributable Codex adapter template lives at adapters/AGENTS.md.
Source Of Truth
VERSIONis the canonical kit version.skills/agent-scratchpad/SKILL.mdis the canonical skill content.skills/agent-scratchpad/references/contains canonical skill references.adapters/contains canonical adapter templates.installers/contains canonical installer scripts.examples/contains canonical examples.codex-plugin/andclaude-plugin/contain generated package copies and plugin manifests.
Do not hand-edit generated copies under codex-plugin/skills/, codex-plugin/adapters/, codex-plugin/installers/, codex-plugin/examples/, codex-plugin/VERSION, codex-plugin/.codex-plugin/plugin.json, claude-plugin/skills/, claude-plugin/adapters/, claude-plugin/installers/, claude-plugin/examples/, claude-plugin/VERSION, or claude-plugin/.claude-plugin/plugin.json. Edit the canonical source, then run:
npm run sync
Scratchpad Files
This repository dogfoods Agent Scratchpad:
- Track
.agent/README.md. - Track
.agent/SCRATCHPAD.template.md. - Track
.agent/VERSION. - Keep
.agent/SCRATCHPAD.local.mdignored. - Keep
.agent/backups/ignored. - Keep
PLAN.mdignored.
Use .agent/SCRATCHPAD.local.md for live task notes, but never commit it.
Installer Rules
- Direct installer use defaults to all supported adapters.
- Narrow installs use
--agent <name>or--no-adapters. - Managed
BEGIN/END Agent Scratchpad Kitblocks are generated output. Do not edit inside them by hand; put project-specific guidance before or after the block. --repairmust not erase user-edited managed blocks. Replacing those requires--force-managed-block.- Backups belong under
.agent/backups/, never beside the modified file.
Review Discipline
When reviewing installer, sync, packaging, or adapter changes, do not stop at happy paths. Include adversarial checks for valid existing repository states that should keep working:
- Existing instruction files with project-specific prose that merely mentions Agent Scratchpad terms must still allow safe managed-block append unless they are known generated legacy adapter text.
- Tests that inspect Markdown, YAML, or generated metadata must tolerate CRLF line endings when the behavior should be platform-independent.
- Existing config files must be tested in absent, already-correct, simple-merge, and ambiguous/manual-action forms.
- Generated copies must be checked from canonical source, but generated-copy drift passing is not evidence that canonical behavior is correct.
- For every broad substring, regex, or heuristic, add at least one harmless false-positive fixture and one real-positive fixture.
Validation
Before release or handoff, run:
npm run check
This checks installer syntax, package sync drift, installer behavior, version consistency, and packaging safety.
Release Workflow
- Choose the next SemVer version and update
VERSION. - Run
npm run sync. - Update
CHANGELOG.md. - Run
npm run check. - Confirm
.agent/SCRATCHPAD.local.md,.agent/backups/, andPLAN.mdare not tracked. - Confirm stable marketplace refs in the release commit point at the intended release tag, for example
v0.2.0. - Commit the release changes and merge them to
main. - Let the Release Tag workflow validate
mainand create the missingv$VERSIONtag. - Verify the tag exists remotely before relying on marketplace install, for example
git ls-remote --tags origin v0.2.0. - Use release tags for stable marketplace refs. Use
mainonly for a documented latest/dev channel.
