Start at docs/README.md — the corpus is the permanent truth about this system (Cliewen conventions since CH-001; see AN-001). Requirements live as Gherkin acceptance criteria under docs/capabilities/*/criteria.md. Before editing, recommend simple when the accepted contract remains unchanged or full when acceptance-criterion, capability, decision, policy, plan-promise, methodology, or uncovered-behavior meaning changes; paths and diff size never decide the route. Simple work uses no Cliewen workspace; chosen full work runs the change loop (clue-delta skill): branch → /changes/CH-xxx-slug/ proposal → implement → digest → PR. Reassess when semantic scope grows, and if the user declines a full recommendation, record the route, recommendation, and risk in the final commit trailers. clue validate judges the corpus; markdown prose is never hard-wrapped (one line per paragraph). A full change never reaches main except through a human-merged PR; simple work may be committed and pushed to main directly only when the maintainer explicitly authorizes that push for that specific change, and such commits carry an Authorized-Push: trailer naming the authorization. Agents never merge their own PRs. See C-002.
Before your first tool call, run clue latest --quiet; if it reports that this repository is behind, ask whether to run the coordinated clue-upgrade workflow. Releases are repository-owned administrative work, not a Cliewen route. A release must provide clear end-user value; corrective releases for defects, security, compatibility, or urgent operational problems may ship without a new user-facing capability. Never release solely to unblock internal or downstream development; use local builds until a value-bearing or corrective release is warranted.
AC IDs are namespaced per capability via ac-prefix frontmatter (registry in docs/README.md); the corpus is the registry, IDs are meaning-immutable. Test purpose tags (every test carries exactly one AC ID or Unit/Sanity/Arch tag) are being introduced capability by capability — see P-001/M-002; extracted criteria sit at status: draft until their tests are wired.
Load the file(s) matching your task type before starting work:
| Task | File(s) |
|---|---|
| Debugging, timing, race conditions | .agents/instructions/debugging.md · docs/DEBUGGING-GUIDE.md |
| Bot API (Java / Python / .NET / TS) | .agents/instructions/cross-platform.md |
| Protocol, WebSocket, server comms | docs/architecture/models/flows/README.md · docs/architecture/models/message-schema/README.md |
| Testing, builds, Gradle | .agents/instructions/testing-and-build.md |
| Documentation, README, Javadoc | .agents/instructions/documentation.md |
| Changelog, release notes | .agents/instructions/changelog.md |
| Code style, naming, conventions | .agents/instructions/coding-conventions.md |
| File encoding, UTF-8 | .agents/instructions/standards.md |
| Product facts, clean-code baseline | .agents/instructions/core-principles.md |
Principles are selected through .principles files; run /dot-scout to refresh mappings and /dot-audit to review a target against the active set.
When creating or updating pull requests through the GitHub API or CLI, send real newline characters in the Markdown body; never send literal \n escape sequences. Prefer a real multiline body or --body-file, and inspect the stored body before considering the PR description complete.
Reusable task instructions live in .agents/skills/. When the user runs a slash command, read the skill file and follow it exactly.
| Skill | Purpose |
|---|---|
clue-delta |
The change loop — use for every full change |
clue-plan |
Create or revise a plan with verifiable milestones |
clue-analysis |
Spikes and findings — every analysis ends in a docs/analysis document |
clue-verify |
Pre-merge checklist, the human-readable twin of clue validate |
clue-extract |
Brownfield adoption (already executed here as CH-001) |
/dot-scout [path] · /dot-audit [target] |
Principles system: discover, review, audit |
/release · /update-deps · /deploy-sample-bots [dir] · /structurizr |
Release, dependency, sample-bot, and diagram workflows |
In repositories indexed by CodeGraph (a .codegraph/ directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:
- MCP tool (when available):
codegraph_exploreanswers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them, including dynamic-dispatch hops grep can't follow. Name a file or symbol in the query to read its current line-numbered source. If it's listed but deferred, load it by name via tool search. - Shell (always works):
codegraph explore "<symbol names or question>"prints the same output.
If there is no .codegraph/ directory, skip CodeGraph entirely — indexing is the user's decision.