docs(openspec): set up OpenSpec baseline (config + principles + glossary)

[drakulavich]

Summary

Sets up OpenSpec for oura-cli, mirroring the layout used by kesha-voice-kit, ottoman, bowser, and iago: a config.yaml carrying project context + spec-writing rules, plus a specs/ README and glossary. Future work can then be proposed as OpenSpec change deltas against a consistent baseline.

The spec-writing rules are the Pareto core of Joel Spolsky's painless-functional-spec structure (Non-Goals first-class, outcomes not implementation, Open Issues first-class) crossed with Nikita Sobolev's user-story lenses (named personas, glossary terms verbatim, every requirement verifiable with a happy and an error scenario), plus file:line traceability.

What's added

File	Purpose
openspec/config.yaml	schema + context (oura-cli's conventions — Bun-native, Oura Cloud API → SQLite Local cache, login/sync/report/db + agent surface, JSON-off-TTY output, CliError/ErrorCode, tsgo strict, named exports, co-located tests, OpenClaw manifest) + rules (1 proposal rule, 6 spec rules).
openspec/specs/README.md	Disclaimer, spec shape, three personas (Quinn the quantified-self user / Marcus the data scripter / Aria the agent author), planned capability table.
openspec/specs/GLOSSARY.md	Canonical terms (Local cache, PAT, Data type, CliError, manifest, …), each traced to src/.

The seven rules (config.yaml rules)

• Non-goals section in every proposal
• Glossary terms verbatim
• Every requirement: happy-path and error/edge scenario
• Outcomes, not implementation, in requirement text
• Named personas (Quinn/Marcus/Aria), never a generic "user"
• Uncertainty / spec-vs-code drift under "Open Issues" — never invent a resolution
• Trace each requirement to code with file:line refs in a Technical Note

Notes

• No spec.md files yet — specs/ fills in as capabilities are extracted (the README table links them in then).
• Docs/tooling only, no user-visible behavior change — so no CHANGELOG.md [Unreleased] entry (per CONTRIBUTING, that's for user-visible changes).
• config.yaml mirrors the schema validated under openspec validate --specs --strict elsewhere; the OpenSpec CLI can be added separately for the in-editor workflow.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR establishes an OpenSpec baseline for oura-cli: a config.yaml encoding project conventions and seven spec-writing rules, plus a specs/ README with three named personas and a capabilities table, and a canonical GLOSSARY.md tracing every term of art to its source file.

• openspec/config.yaml accurately captures the project's tech conventions (Bun, tsgo, named exports, CliError/ErrorCode, co-located tests) and defines the proposal/spec rule set.
• openspec/specs/README.md correctly describes the spec shape and the three personas (Quinn / Marcus / Aria); the --format json flag fix from the follow-up commit is reflected.
• openspec/specs/GLOSSARY.md contains two factual errors: the healthcheck entry claims the command checks "token present" and "API status" but the implementation is a local-DB probe only; the db entry asserts "without hitting the network" but db import is a sync alias that calls the Oura Cloud API.

Confidence Score: 4/5

Safe to merge once two GLOSSARY inaccuracies are corrected — no production code is touched.

The entire value of this PR rests on the GLOSSARY being trustworthy: future agent-surface and query specs will be written against these definitions. Two entries misrepresent the actual implementation — healthcheck does not check token presence or API reachability, and db import does hit the network despite the entry saying the command is network-free. These are direct contradictions between the glossary text and the source files.

openspec/specs/GLOSSARY.md — the healthcheck and db entries need correction before this becomes a reliable reference for future spec authors.

Important Files Changed

Filename	Overview
openspec/config.yaml	Project context and seven spec-writing rules are accurate against the codebase — conventions, paths, tooling, and command surface all check out.
openspec/specs/GLOSSARY.md	Two factual errors: healthcheck definition lists "token present" and "API status" checks that don't exist in the implementation; db definition claims "without hitting the network" but db import is a sync alias that calls the Oura Cloud API.
openspec/specs/README.md	Persona definitions and capabilities table are accurate; the previous --json flag issue was addressed in the follow-up commit.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[openspec/config.yaml\nProject context + 7 rules] --> B[openspec/specs/README.md\nPersonas + capabilities table]
    A --> C[openspec/specs/GLOSSARY.md\nCanonical term definitions]
    B --> D[Future spec files\nspecs/auth/spec.md\nspecs/sync/spec.md\n...]
    C --> D
    D --> E[OpenSpec validate\n--specs --strict]

    subgraph Terms verified against src/
        C1[PAT ok - src/commands/login.ts]
        C2[Local cache ok - src/db/database.ts]
        C3[Output mode ok - src/lib/format-resolve.ts]
        C4[healthcheck - claims token+API check but impl is local-DB probe only]
        C5[db - claims network-free but db import calls Oura Cloud API]
    end

    C --> C1 & C2 & C3 & C4 & C5

Loading

_{Reviews (2): Last reviewed commit: "docs(openspec): fix output flag — --form..." | Re-trigger Greptile}

[drakulavich]

Fixed both glossary inaccuracies: healthcheck is now described as a local SQLite probe (SELECT 1 → {ok, version, latencyMs}) that does not touch the token or API, and the db entry now notes that db import is a sync alias which does hit the Oura Cloud API (so it's not network-free). Thanks for catching both.