jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/openspec/specs/adr-session-awareness/spec.md

2.5 KiB
Raw Blame History

Spec: ADR Session Awareness

Purpose

Defines the os-adr SessionStart behavior: a deterministic, model-free existence check that injects a near-zero-token usage note when a project's ADR system exists, and a suppressible, once-per-day setup suggestion when it doesn't.

Requirements

Requirement: Deterministic SessionStart existence check

The plugin SHALL register a SessionStart hook (matcher startup|resume) that deterministically checks for docs/adr/ and its index file in the current project. The hook SHALL make no LLM call, SHALL complete within its configured timeout (5s), and SHALL add no perceptible session-start latency.

Scenario: Hook is deterministic

  • WHEN the SessionStart hook runs
  • THEN its output is a pure function of the project's filesystem state (ADR dir, index, suppression state) with no model invocation

Requirement: Minimal context injection when the ADR system exists

WHEN docs/adr/ and the index file both exist, the hook SHALL inject a near-zero-token additionalContext note stating that the ADR system exists and naming both usage surfaces: writing (/os-adr:create) and retrieval (/os-adr:find).

Scenario: Present project gets the usage note

  • WHEN a session starts in a project with docs/adr/ and an index
  • THEN the injected context is a short note (a few lines at most) naming /os-adr:create and /os-adr:find

Requirement: Setup suggestion with suppression when absent

WHEN the ADR system is absent, the hook SHALL notify the user and suggest /os-adr:init or /os-adr:migrate — unless a per-project suppression flag is set, in which case it SHALL stay silent. The suggestion SHALL also be rate-limited to at most once per day per project via a snooze timestamp. Suppression state SHALL live in a gitignored per-project state directory (.os-adr/), following the os-doc-hygiene state-dir shape.

Scenario: Absent and unsuppressed

  • WHEN a session starts in a project with no docs/adr/ and no suppression flag, and no reminder was shown today
  • THEN the hook emits a one-line suggestion to run /os-adr:init or /os-adr:migrate and stamps the snooze timestamp

Scenario: Suppressed project stays silent

  • WHEN a session starts in a project whose .os-adr/suppress flag is set
  • THEN the hook emits nothing

Scenario: Same-day repeat session

  • WHEN a second session starts the same day in an absent, unsuppressed project
  • THEN no repeat suggestion is emitted