AGENTS.md

Guidance for coding agents working in this repository.

ADHD Progress Hub

• Prefer MCP tools from adhd-hub (resolve_project, session_digest, check_overlap, upsert_progress, mark_done, set_reminder) when starting, pausing, or finishing work that could be abandoned. On routine upsert_progress checkpoints, update Goal/Focus/Next/Blocked/Resume only — omit ritual content (never “Thread upserted from …”).
• Install skills globally when possible: npx skills add ./skills -g (or uniskela/adhd-hub once public). Skills include adhd-hub-session, adhd-hub-projects, and env-check.
• Use env-check (resolve scripts/check_runtime.sh from the installed skill — project-scoped .agents/skills/env-check/… or Hub source skills/env-check/…) for CLOUD_AGENT vs LOCAL_WORKSPACE; MCP unavailable triggers forge [ADHD] fallback — never invent Hub state. Recommended Made-with footer on those issues: Made with [ADHD Progress Hub](https://github.com/uniskela/adhd-hub) under ## Attribution.
• Do not invent hub state — only report what the tools return.
• Prefer summaries; never dump full chat transcripts into the hub.

Graphify

This project keeps a knowledge graph under graphify-out/.

CLOUD_AGENT: do not assume the graphify CLI (or other machine-installed local skill binaries) exists. If missing: one-line notice, continue via repo tools and committed graphify-out/ when present; never fabricate graph output. LOCAL_WORKSPACE may have those tools. Hub MCP down still uses the [ADHD] forge mailbox when allowed (see continuity block / env-check).

Before exploring code

When the graphify CLI is available, orient with it before broad Read/Grep/Glob exploration:

graphify query "<question>"
graphify path "<A>" "<B>"
graphify explain "<concept>"

Use Read/Grep/Glob after orientation when you need exact lines to edit or debug. If the CLI is missing, say so in one line and continue with repo tools / committed graphify-out/ — do not invent graph state. If graphify-out/graph.json is missing and the CLI is available, build/update the graph first.

After modifying code

When the CLI is available, always refresh the graph after code edits (AST-only, no LLM / API cost):

graphify update .

Run this after meaningful code edits in the same session (not optional). Prefer the project root as ..

Useful extras

graphify god-nodes
graphify affected "<symbol>"
graphify check-update .

If graphify-out/wiki/index.md exists, prefer it for navigation. Use graphify-out/GRAPH_REPORT.md for broad architecture review when query/path/explain are not enough.

See the Cursor skill .cursor/skills/graphify/SKILL.md and rule .cursor/rules/graphify.mdc.

Releases / PR titles

Release Please reads the squash-merge subject on main, not PR body bullets. With GitHub COMMIT_OR_PR_TITLE, that subject is the PR title (for multi-commit squashes unless the merger edits it).

• Release-surface diffs (src/, pyproject.toml, uv.lock, Dockerfile, docker-compose.yml): PR title must be feat: / fix: / perf: / revert: (optional scope) or type!: for breaking changes.
• Docs / chore / CI / test-only PRs may use docs:, chore:, ci:, test:, etc.
• CI enforces the release-surface rule via .github/workflows/pr-title.yml (scripts/pr_title_gate.py, same surfaces as scripts/release_gate.py). Release Please release PRs (release-please--branches--* / release-please bot author) are exempt — their chore(…): release … titles are intentional.
• Soft-skip of release_gate on main for non-releasable subjects (docs/chore) is intentional — it skips Release Please rather than failing the push.

See CONTRIBUTING.md and the PR template.

Docs / Wiki

• On each new PR, audit and update wiki docs (graphify-out/wiki/ when present) so they stay aligned with the change and do not drift.

ADHD Hub continuity

For substantial work in this project:

• If ADHD Hub MCP tools are missing, errored, unauthorized, or otherwise unavailable: on the first substantial Hub-worthy turn after detecting the outage, the first line MUST state that Hub MCP is not available, plus a short fix hint (MCP URL → this Hub's /mcp, ADHD_HUB_AUTH_TOKEN, restart the agent; skip/cancel Auth if it hangs until Hub OAuth is enabled). Repeat only if Hub status changes, a persistence attempt fails again, or the reply could otherwise imply continuity was saved. Then continue the authorized work. Never invent Hub state or claim a Hub write succeeded.
• MCP unavailable is the Hub continuity trigger (not runtime alone). Use the env-check skill — resolve scripts/check_runtime.sh from the installed skill (project-scoped: .agents/skills/env-check/…; Hub source: skills/env-check/…) — for CLOUD_AGENT vs LOCAL_WORKSPACE as supporting context (CURSOR_AGENT, container cues — never $USER=root alone). When Hub MCP is unreachable, use the forge issue mailbox only when issue-write access is available and the authenticated identity is accepted by Hub Inbox authors. Open/update a GitHub/Gitea issue titled [ADHD] … with a short Goal/Focus/Next/Resume cue. Optional labels: adhd-hub, project:<slug>, source:cursor; skip labels if the token cannot set them. Recommended: append Made with [ADHD Progress Hub](https://github.com/uniskela/adhd-hub) under a non-imported heading (e.g. ## Attribution) so it does not land in Resume. Prefer short repository-relative summaries; never invent Hub continuity, progress, or thread state after a forge-only write. Never put credentials, tokens, personal/customer data, private hostnames/IPs, absolute local paths, transcripts, or secrets/env contents in forge issues.
• CLOUD_AGENT: do not assume machine-installed local skill CLIs (e.g. graphify) exist. If missing: one-line notice, continue via repo tools / committed graphify-out/ when present; never fabricate graph or Hub state. Prefer headless tests and injected env/OIDC over .env.local; no native browser/macOS-Windows binaries. Hub MCP down still uses the [ADHD] forge mailbox when allowed. LOCAL_WORKSPACE: those local CLIs may be available; local docker / localhost OK; prefer Hub MCP when up.
• Skip Hub for trivial/read-only/tiny work.
• Once per meaningful session: resolve_project with create_if_missing=false, then session_digest with the task query. Reuse resolved context where possible. Create/register only after the workspace is authorized as a Hub project.
• One thread = one independently finishable outcome (not the whole repo). Size the Goal to what the agent can finish (e.g. open a review-ready PR). A Goal that includes merge/deploy stays open/paused until that is done — do not auto-split every PR into a second thread. Before updating a thread, compare new work to that thread's Goal; if it does not advance the same outcome, use another thread or create one.
• Known thread → upsert_progress(thread_id=...) with compact structured state (goal / focus / ≤3 next / blocked if any / resume); omit ritual content. Do not silently attach to an unrelated open thread.
• check_overlap only before potentially new work; reuse only when the Goal matches. Different goal → separate thread (force_new_thread if needed).
• End-of-task (checkpoint first if Hub state is stale): completion.ready reflects stored state only (not PR/CI/merge), so it can block mark_done but never approve it alone. mark_done on that thread only when ready is true or absent and the Goal is done with nothing remaining (optional final checkpoint first). ready == false (even if the Goal looks done) or any remaining work (review, draft PR, CI, merge, deploy, verify, or a next action — even if ready == true) → upsert_progress (record it in next_steps) then pause_thread(thread_id, next_step=...) — do not mark_done. If mark_done is denied/rejected for unfinished work: do not retry; checkpoint + pause_thread and continue the normal response.
• If Hub guidance looks stale (session_digest guidance status, or doctor), mention it once, keep using the current MCP contract, and recommend adhd-hub setup . --refresh and adhd-hub sync-project . (or setup . --project-skills) — do not nag repeatedly or hand-edit AGENTS.md.
• Summaries only; never secrets, credentials, env files, transcripts, private Hub URLs, internal hosts/IPs, or absolute machine paths in public artifacts.