From c629959f37d8fc04c0a20f5dba0a2628284bf77e Mon Sep 17 00:00:00 2001 From: jared Date: Fri, 10 Jul 2026 09:45:55 -0400 Subject: [PATCH] ADR-023 os-backlog plugin + ADR-024 Apprise transport; state cc-os operating-layer role MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-023: backlog process management ships as a new os-backlog plugin (not an os-vault extension) and cc-os's ecosystem role is made explicit — the always-on personal operating layer of mutually aware os-* plugins, vs cc-plugins' optional shelf. CLAUDE.md opening updated to match. ADR-024: Apprise supersedes Pushover as the notification transport (server on OVH + minimal client this iteration; expansion seeded as P2/P3 board cards). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_018Mb3V8NNzAuns7vgX9A2jU --- CLAUDE.md | 11 ++++++--- .../03-architecture-decisions.md | 24 ++++++++++++++++++- 2 files changed, 31 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c4a4cf3..d4f5ad5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,9 +7,14 @@ operational procedures live in [docs/implementation-status.md](docs/implementati ## What this repository is -`cc-os` is a **design + implementation repository** for a **personal, cross-project memory -system for Claude Code** (for a multi-client freelancer), plus a family of global Claude Code -plugins and the research/evals that inform them. Everything is markdown-as-truth: specs, +`cc-os` is the user's **personal operating layer for Claude Code**: the family of always-on, +globally installed `os-*` plugins that run on every machine the user works from, plus the +research/evals that inform them. The founding piece is a **cross-project memory system** (for +a multi-client freelancer), but the scope is the whole operating layer — memory, decisions, +process/backlog management, status, notifications — and the long-term intent is that the +`os-*` plugins are **aware of each other and cooperate** (ADR-023). By contrast, +`~/dev/cc-plugins` holds optional, as-needed plugins; anything that should be ambient on +every machine belongs here. Everything is markdown-as-truth: specs, ADRs, and the build plan in `docs/` are the source of truth for what is being built. When asked to "build," work from the staged tasks in `docs/memory-system/04-build-plan.md`, not ad hoc. diff --git a/docs/memory-system/03-architecture-decisions.md b/docs/memory-system/03-architecture-decisions.md index a4e27d0..9ded933 100644 --- a/docs/memory-system/03-architecture-decisions.md +++ b/docs/memory-system/03-architecture-decisions.md @@ -1,6 +1,6 @@ # Architecture Decision Records -_Last updated: 2026-07-03_ +_Last updated: 2026-07-10_ A running log of decisions and *why*. Format per entry: Context · Decision · Rationale · Alternatives rejected · Status. Newest decisions extend the log; supersede rather than delete. @@ -631,6 +631,28 @@ _Date: 2026-07-06_ - **Cross-references**: OpenSpec change `add-os-status-plugin` (proposal/design/specs/tasks), `plugins/os-status/invariants.md`, WS1 findings (`docs/orchestration-audit/2026-07-06-findings.md`), ADR-018 (marketplace-manifest procedure followed for install). - **Status**: Accepted 2026-07-06. Built, tested (36 model-free tests), installed, smoke-tested (including the regression canary: exported `CLAUDE_CODE_SUBAGENT_MODEL=haiku` produces the override warn). +## ADR-023 — Backlog process management ships as a new `os-backlog` plugin (not an os-vault extension) + +_Date: 2026-07-10_ + +- **Context**: The Planka backlog pilot (vault note `vault-backlog-pilot-plan`) reached its plugin phase with one gated decision open: build the AI's process-management surface (skills for capture/list/tick/board ops, deterministic scripts over the `planka-api` gem, card-triage/board-audit named agents, hooks) as a new plugin or as an extension of os-vault. The decision also surfaced a broader framing question: what cc-os *is* relative to `~/dev/cc-plugins`. +- **Decision**: (1) New global plugin **`os-backlog`** (`plugins/os-backlog/`). os-vault is not extended. Naming per `cc-os-plugin-skill-naming-convention.md`: verb-first skills invoked as `/os-backlog:`; no `name:` frontmatter; no `commands/` dispatchers. (2) **Ecosystem role made explicit**: cc-os is the user's *personal operating layer* for Claude Code — the family of always-on, globally installed, mutually aware `os-*` plugins running on every machine; `~/dev/cc-plugins` is the shelf of optional, as-needed plugins. Cross-plugin awareness and cooperation (including notifications, ADR-024) is an explicit long-term goal of the cc-os family, not an accident. +- **Rationale**: Separation of concerns — os-vault is the memory/knowledge domain (what do I know), os-backlog is the workflow/process domain (what state is work in): different backing stores (SecondBrain vault vs. Planka Postgres via REST), different failure modes (local files vs. network service), different maturity (os-vault is eval-hardened and stable; backlog skills will churn while the process settles). Every comparably sized domain in the family already got its own plugin (os-adr, os-status, os-doc-hygiene). Hook hygiene: a broken/unreachable Planka must not degrade vault sync hooks. +- **Alternatives rejected**: **Extending os-vault** — the only benefit is one fewer plugin to maintain, a cost already amortized by `bin/refresh-plugins` and the marketplace procedure (ADR-018); it would couple a churning surface to a frozen, eval-tuned one and blur the domain boundary the tag taxonomy itself encodes. Future skills needing both domains compose by invoking each other's skills, not by merging plugins. +- **Cross-references**: vault notes `vault-backlog-pilot-plan` (pilot plan + execution status), `cc-os-plugin-skill-naming-convention`; ADR-018 (install procedure); ADR-024 (notification direction the plugin will consume). +- **Status**: Accepted 2026-07-10. Design pass (skill/agent/hook inventory) next; build delegated to sonnet after design. + +## ADR-024 — Apprise replaces Pushover as the notification transport (supersedes the Pushover-direct plan) + +_Date: 2026-07-10_ + +- **Context**: The `planka-api` gem's tick/digest delivery was specified as Pushover-direct (`PUSHOVER_API_TOKEN`/`PUSHOVER_USER_KEY`, falls back to stdout when unset — see the gem's `docs/issues/README.md` and the P0 board card "Provision Pushover digest credentials"). Separately, Planka itself ships Apprise as a notification integration, and the user's real need is multi-service: Discord, Telegram, Bark, Home Assistant, Gnome desktop, Zoom, and Pushover are all in active use, and any AI agent (Claude Code, Hermes) on any machine should be able to notify on whichever service fits the moment. +- **Decision**: (1) **Apprise becomes the single notification transport**: an Apprise API server deployed as a docker-compose service on the OVH production server, following the established service pattern. (2) **This iteration's scope is deliberately minimal**: stand up the server and swap the gem's Pushover P0 for a minimal Apprise client (one `notify` call against the API) — the pilot's critical path does not grow. (3) The **expansion is captured as P2/P3 backlog cards, to be built soon**: an Apprise client gem + CLI wrapper, an `os-notify` cc-os plugin so any session can route notifications by service/need (per ADR-023's ecosystem framing, notifications are cross-plugin infrastructure and belong in cc-os), multi-service routing config, and wiring Planka's native Apprise integration to the same server. +- **Rationale**: One integration covers N services — adding a service becomes an Apprise URL/tag config change, not new code; service selection becomes a runtime parameter, which is exactly the "tell the AI where to notify" requirement. Planka speaking Apprise natively means board events and agent-initiated notifications converge on one server. The minimal client is *less* work than the Pushover gem would have been (Apprise absorbs per-service quirks). Notification-blindness policy (pull beats push, silent days stay silent) is unchanged — this ADR changes the transport, not the policy. +- **Alternatives rejected**: **Pushover gem as planned** — single-service dead end; every future service would be a new integration. **Deferring Apprise entirely** — the server + minimal client is comparable effort to the Pushover path, so there is no cheaper interim. +- **Cross-references**: ADR-023 (os-backlog / ecosystem role); vault note `vault-backlog-pilot-plan` (notification policy v2); gem repo `~/dev/ruby-gems/planka` (tick delivery); Apprise docs https://appriseit.com/. +- **Status**: Accepted 2026-07-10. Server deploy + P0 swap queued on the boards; expansion cards seeded at P2/P3. + ## Rejected tools (summary) | Tool | Why rejected for our use |