adhd-hub / rules

---
description: ADHD Progress Hub — check overlap and save progress on unfinished work
alwaysApply: true
hub_guidance_version: 8
---

# ADHD Progress Hub

Use Hub for substantial continuity-worthy work, not trivial/read-only questions, quick explanations, or tiny edits.

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 the warning 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 — one-line notice if missing, then repo tools / committed `graphify-out/`; prefer headless tests and injected env/OIDC over `.env.local`; no native browser/macOS-Windows binaries. LOCAL_WORKSPACE: local docker / localhost OK; local CLIs may exist; prefer Hub MCP when up.

When this workspace involves substantial starting, resuming, or pausing work:

1. Call MCP `adhd-hub` → `resolve_project` with `create_if_missing=false`, then `session_digest` with the task query once per meaningful session. Reuse resolved context where possible. Create/register only after the workspace is authorized as a Hub project.
2. One thread = one independently finishable outcome. 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. If resuming a known thread, reuse its `thread_id`. Otherwise call `check_overlap` before potentially new work and reuse a candidate only when its Goal matches; different goal → separate thread (`force_new_thread=true` when needed).
3. At meaningful checkpoints use `upsert_progress(thread_id=...)` with compact goal/focus/next/blocked/resume state. When leaving mid-task, checkpoint then call `pause_thread(thread_id, next_step=...)` with one concrete resume action.
4. End-of-task (checkpoint first if Hub state is stale): `completion.ready` reflects stored state only (not PR/CI/merge), so it can block but never approve alone. `mark_done` on that thread only when `ready` is `true` or absent **and** the Goal is done with nothing remaining. `ready == false` (even if the Goal looks done) or any remaining work (even if `ready == true`) → `upsert_progress` (record it in `next_steps`) then `pause_thread` — do not `mark_done`. If `mark_done` is denied/rejected for unfinished work: do not retry; checkpoint + `pause_thread` and continue normally.

If Hub guidance looks stale, mention it once and recommend `adhd-hub setup . --refresh` and `adhd-hub sync-project .` (or `setup . --project-skills`) — do not nag or hand-edit AGENTS.md.

Never put credentials, customer/personal data, private Hub URLs, internal hostnames/IPs, absolute local workspace paths, or full transcripts in public issues or progress notes. Prefer short repository-relative summaries.