From 7c1dd40b9ce7fcc0f79690c40222d76d3026b9fc Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sun, 26 Jul 2026 12:06:10 +0100 Subject: [PATCH] docs: a contributing page for working on the system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Everything in docs/ describes the product; nothing described the repository that produces it. This covers clone-to-green setup, the four local gates (and that there is no CI), rebuilding the knowledge bundle, and the conventions that are mandatory before editing skills. The prose-test section carries the prerequisite that cost most of a session to find: frontmatter hooks in a project subagent only run once the workspace trust dialog is accepted for the folder, and until then they fail silently — no warning, and /hooks shows nothing for an inactive agent. hasCompletedProjectOnboarding can read true while trust is still false, so an old checkout looks set up and quietly isn't. Deliberately thin elsewhere; it grows as we hit things. Co-Authored-By: Claude Opus 5 --- README.md | 4 +- docs/README.md | 4 ++ docs/contributing.md | 107 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 docs/contributing.md diff --git a/README.md b/README.md index 99e120a6c..85a90eeaa 100644 --- a/README.md +++ b/README.md @@ -134,7 +134,9 @@ The [full documentation](docs/README.md) covers every phase in detail, the engin ## Contributing -Contributions are welcome! Whether it's bug fixes, workflow improvements, or new ideas — please open an issue first to discuss significant changes. +Contributions are welcome — bug fixes, workflow improvements, or new ideas. Please open an issue first to discuss anything significant. + +See [docs/contributing.md](docs/contributing.md) for getting set up, the test gates, and the setup gotchas worth knowing before they cost you an afternoon. ## Related Packages diff --git a/docs/README.md b/docs/README.md index a3ae116ee..dc585d5b2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -39,3 +39,7 @@ How the system works beneath the conversation — described, not as anything you - [Capture and the inbox](capture-and-inbox.md) — logging ideas, bugs, and quick-fixes without stopping, then triaging them into real work. - [Lifecycle operations](lifecycle-operations.md) — pivot, absorb, cancel, reactivate, and promote: reshaping work as your understanding of it changes. - [Configuration](configuration.md) — installing and updating, the settings that fill themselves in, and where each one lives. + +## Working on the system + +- [Contributing](contributing.md) — for changing this repository rather than using it: the gates, the prose tests, and the setup hiccups worth knowing before they cost you an afternoon. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 000000000..bdd43578d --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,107 @@ +# Contributing + +This page is for working **on** the system rather than with it. Most of +the documentation describes the product; this describes the repository +that produces it. + +Start by reading `CLAUDE.md` at the repository root — it is the working +brief for anyone, human or agent, changing this codebase, and it covers +architecture, conventions, and the standing rules that are easy to +violate by accident. + +## Getting set up + +```bash +git clone git@github.com:leeovery/agentic-workflows.git +cd agentic-workflows +npm install +npm test +``` + +Node 18+. `npm install` pulls dev dependencies only — the product itself +has no runtime dependencies, which is why the knowledge-base CLI ships +as a committed bundle. + +## The gates + +There is **no automated CI**. The gates run locally, and the convention +is to run them before every commit rather than at the end of a branch. + +| Command | What it covers | +| --- | --- | +| `npm test` | Node suites: engine, gateways, knowledge, migrations, pipeline simulation, prose-test perimeter | +| `npm run test:cli` | Shell contract suites: manifest field surface, inbox promotion, knowledge CLI and build | +| `npm run test:migrations` | Every `tests/scripts/test-migration-*.sh` | +| `npm run typecheck` | JSDoc type contracts (`tsc --noEmit`) | + +**Never pipe a gate's output.** A pipe swallows the exit code, and a +suite that aborts halfway then reads as green. Redirect to a file and +check `$?` instead. This has produced a falsely-green report before. + +## After changing the knowledge base + +`src/knowledge/` is bundled into +`skills/workflow-knowledge/scripts/knowledge.cjs` by esbuild. Installs +come from git tags with no build step, so the bundle must be present and +current whenever a tag is cut: + +```bash +npm run build # then commit the bundle alongside the source change +``` + +## Prose tests + +`tests/prose/` walks the skill prose with real agents against real +project states. Walks cost tokens, so they run on command via the +`/prose-test` skill rather than as part of a gate. `npm test` covers only +the token-free perimeter: corpus validation and snapshot rebuilds. + +**Prerequisite that will otherwise waste your afternoon:** the walker +records what it did through a `PostToolUse` hook declared in its own +agent frontmatter, and **frontmatter hooks in a project subagent only +run once the workspace trust dialog has been accepted for the folder** +(Claude Code 2.1.218+). Until then they fail *silently* — no warning, no +error, and `/hooks` shows nothing for an agent that isn't currently +active. The symptom is every prose-test run reporting `HARNESS ERROR` +with no action log. + +Check it directly: + +```bash +node -e 'const o=require(process.env.HOME+"/.claude.json"); + console.log(o.projects[process.cwd()]?.hasTrustDialogAccepted)' +``` + +If that prints `false`, accept the trust dialog for the folder. Note that +`hasCompletedProjectOnboarding` can be `true` while trust is still +`false` — onboarding predates the change that started gating hooks on +it, so an old checkout will look set up and quietly not be. + +## Known hiccups + +- **Agent and skill definitions are cached per session.** Editing + `.claude/agents/*.md` and immediately testing will exercise the old + definition. Reload plugins, or restart, before trusting a result. +- **Snapshot drift is expected after an engine change.** A red + `prose-test snapshots` suite means a world moved. Regenerate with + `node tests/prose/run.cjs snap ` and land the snapshot diff in + the same PR as the change that moved it. Never hand-edit a snapshot. +- **`CHANGELOG.md` is generated.** Never edit it by hand. +- **Shipped `.sh` migrations are frozen.** Fix forward with a new + numbered `.cjs` migration rather than editing one that has run on real + installs. + +## Conventions + +Skill authoring — prose economy, display conventions, file structure, +navigation patterns — lives in `CONVENTIONS.md`, and it is mandatory +reading before editing anything under `skills/`. It is dense and changes +often; skipping it has produced silently non-compliant skills more than +once. + +## Raising changes + +Open an issue before anything substantial, so the shape can be agreed +before the work. Each idea ships as its own pull request rather than +bundled with others, and any change to engine scripts, adapters, +migrations or `src/knowledge/` lands with its test alongside it.