bearings 0.2.0 → 0.3.0

package/templates/agents/skills/repo-navigation/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: repo-navigation
 description: Use when exploring the repo, locating code, or deciding which docs and paths to read before making changes.
 ---
 
@@ -6,7 +7,9 @@ description: Use when exploring the repo, locating code, or deciding which docs
 
 ## Purpose
 
-Explore efficiently without crawling irrelevant, archived, generated, or project-specific material.
+Route straight to owning source using the codebase map, and load domain,
+architecture, decision, or deferred-work context only when the task actually
+needs it.
 
 ## Triggers
 
@@ -15,14 +18,27 @@ Explore efficiently without crawling irrelevant, archived, generated, or project
 
 ## Required Workflow
 
-1. Read `docs/CURRENT_STATE.md` -> use it as the first source map.
-2. Read only the paths relevant to the task -> keep exploration proportional.
-3. If the source map is stale -> report the mismatch and continue from direct evidence.
+1. Read the entire `docs/CODEBASE_MAP.md` before any source work -> use its
+   `path#symbol` anchors as the routing model.
+2. Load `docs/DOMAIN.md` only when the task turns on behavior, requirements,
+   workflows, terminology, scope, or domain rules.
+3. Load `docs/ARCHITECTURE.md` only when the task turns on components,
+   dependency direction, integrations, state ownership, significant
+   dependencies, or environment/build shape.
+4. Load `docs/adr/INDEX.md` and only matching ADRs when a consequential
+   decision constrains the task.
+5. Load `docs/deferred/INDEX.md` and only matching details when planning a
+   new capability.
+6. If any loaded map is stale -> report the mismatch and continue from direct
+   evidence.
 
 ## Rules
 
-- Do: prefer durable docs, manifests, and entry points before deep file walks.
-- Do not: crawl archived, generated, vendored, or build-output folders unless the task explicitly needs them.
+- Do: prefer the codebase map, other durable docs, manifests, and entry
+  points before deep file walks.
+- Do not: crawl archived, generated, vendored, or build-output folders unless
+  the task explicitly needs them.
+- Do not: load a map whose trigger does not match the current task.
 
 ## Verification
 
@@ -30,5 +46,8 @@ Explore efficiently without crawling irrelevant, archived, generated, or project
 
 ## References
 
-- `docs/CURRENT_STATE.md` - source map and current shipped shape.
-- `docs/conventions/current-state.md` - update policy and staleness rules.
+- `docs/CODEBASE_MAP.md` - current capability/concern-to-source map.
+- `docs/DOMAIN.md` - business language and workflows.
+- `docs/ARCHITECTURE.md` - stable technical shape and environment.
+- `docs/adr/INDEX.md` - consequential decision registry.
+- `docs/deferred/INDEX.md` - approved postponed-work registry.

package/templates/agents/skills/resurface-deferred-work/SKILL.md

@@ -1,5 +1,6 @@
 ---
-description: Use before building, planning, or designing work that matches an entry in docs/deferred/INDEX.md.
+name: resurface-deferred-work
+description: Use when building, planning, or designing work that matches an entry in docs/deferred/INDEX.md.
 ---
 
 # Resurface Deferred Work
@@ -33,4 +34,3 @@ Prevent agents from silently building over parked decisions without confirming t
 ## References
 
 - `docs/deferred/INDEX.md` - parked-work registry.
-- `docs/conventions/doc-lifecycle.md` - lifecycle for deferred plans.

package/templates/agents/skills/secrets-handling/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: secrets-handling
 description: Use when touching credentials, tokens, keys, secret references, config containing secrets, or secret redaction paths.
 ---
 

package/templates/docs/ARCHITECTURE.md

@@ -0,0 +1,37 @@
+# ARCHITECTURE
+
+Answers: how is the system technically shaped? Populated and kept current by `/refresh-repo-map`. Do not hand-edit outside that workflow.
+
+## System Boundary
+
+<agent: fill via /refresh-repo-map - the system and runtime boundary: what is inside versus outside this codebase.>
+
+## Primary Stack
+
+<agent: fill via /refresh-repo-map - primary language, runtime, framework, platform, and package manager.>
+
+## Significant Dependencies
+
+<agent: fill via /refresh-repo-map - architecture-significant dependencies and the role each plays.>
+
+## Components and Dependency Direction
+
+<agent: fill via /refresh-repo-map - major components and the direction dependencies flow between them.>
+
+## Integrations and State Ownership
+
+<agent: fill via /refresh-repo-map - external integrations and which component owns which state.>
+
+## Runtime and Deployment
+
+<agent: fill via /refresh-repo-map - runtime topology and how the system is deployed.>
+
+## Development Environment
+
+<agent: fill via /refresh-repo-map - local prerequisites and canonical install, run, build, test, and lint commands.>
+
+## Architectural Constraints
+
+<agent: fill via /refresh-repo-map - durable technical constraints and links to governing ADRs.>
+
+<!-- repo-map-synced: <agent: fill via /refresh-repo-map> -->

package/templates/docs/CODEBASE_MAP.md

@@ -0,0 +1,33 @@
+# CODEBASE_MAP
+
+Answers: where is today's shipped implementation? Organized by capability and concern, not directory order. Populated and kept current by `/refresh-repo-map`. Do not hand-edit outside that workflow.
+
+## Executable Entry Points
+
+<agent: fill via /refresh-repo-map - the executable entry points into this codebase.>
+
+## Capabilities and Concerns
+
+<agent: fill via /refresh-repo-map - each shipped capability or technical concern and its owning `path#symbol` anchors.>
+
+## Critical Flows
+
+<agent: fill via /refresh-repo-map - critical flow chains where one owner table cannot show the route clearly.>
+
+## Shared Utilities and Infrastructure
+
+<agent: fill via /refresh-repo-map - shared utilities and infrastructure used across capabilities.>
+
+## Interfaces and State
+
+<agent: fill via /refresh-repo-map - interfaces, state, side effects, and external boundaries.>
+
+## Change Hazards
+
+<agent: fill via /refresh-repo-map - change hazards that affect safe routing or proof.>
+
+## Verification Map
+
+<agent: fill via /refresh-repo-map - relevant tests and verification commands per capability.>
+
+<!-- repo-map-synced: <agent: fill via /refresh-repo-map> -->

package/templates/docs/DOMAIN.md

@@ -0,0 +1,33 @@
+# DOMAIN
+
+Answers: why does this system exist? Populated and kept current by `/refresh-repo-map`. Do not hand-edit outside that workflow.
+
+## Problem and Outcomes
+
+<agent: fill via /refresh-repo-map - the problem this system solves and the outcomes it produces for its users.>
+
+## Actors
+
+<agent: fill via /refresh-repo-map - users, operators, and other systems that act on or through this system.>
+
+## Use Cases
+
+<agent: fill via /refresh-repo-map - the business use cases this system supports.>
+
+## Workflows
+
+<agent: fill via /refresh-repo-map - the end-to-end workflows actors follow to reach an outcome.>
+
+## Ubiquitous Language
+
+<agent: fill via /refresh-repo-map - canonical domain terms and their precise meaning in this system.>
+
+## Domain Rules
+
+<agent: fill via /refresh-repo-map - domain rules and invariants that constrain behavior regardless of implementation.>
+
+## Boundaries and Non-Goals
+
+<agent: fill via /refresh-repo-map - what this system is explicitly not responsible for.>
+
+<!-- repo-map-synced: <agent: fill via /refresh-repo-map> -->

package/templates/docs/adr/0000-template.md

@@ -8,10 +8,22 @@ State whether this decision is proposed, accepted, superseded, or rejected.
 
 Describe the forces, constraints, and facts that make a decision necessary.
 
+## Scope
+
+State exactly which domain or technical concerns this decision applies to.
+
 ## Decision
 
 Record the chosen approach and the scope where it applies.
 
+## Alternatives
+
+List the alternatives considered and why each was rejected.
+
 ## Consequences
 
 List the tradeoffs, follow-up work, and verification impact.
+
+## Supersession
+
+State whether this ADR supersedes or is superseded by another ADR, and cross-link both records.

package/templates/docs/adr/INDEX.md

@@ -0,0 +1,6 @@
+# Architecture Decision Records
+
+An ADR is warranted when a decision constrains future work, has meaningful alternatives or tradeoffs, or is costly to reverse. Recording a decision here requires an approved consequential decision — never invent or record an unapproved entry. Read this index first, then only matching accepted or superseding ADRs; do not scan every ADR.
+
+| ID | Decision | Status | Affected concerns | Supersedes | Detail |
+|---|---|---|---|---|---|

package/templates/docs/deferred/INDEX.md

@@ -1,6 +1,8 @@
 # Deferred Work
 
-| ID | Parked item | Revisit trigger | Detail |
-|---|---|---|---|
+This folder is not a general backlog and does not hold permanently rejected work or ordinary code TODOs. Recording an entry here requires explicit developer approval — an agent may suggest deferral but never records it unapproved.
 
-Add a `DEF-NNN-topic.md` detail doc per entry. Scan this file before planning new features.
+| ID | Postponed item | Reason | Revisit trigger | Detail |
+|---|---|---|---|---|
+
+Add a `DEF-NNN-topic.md` detail doc per entry. Read this index before planning a new capability, then open only matching detail files. Remove a row once its work is shipped or rejected.

package/templates/agents/commands/current-state.md

@@ -1,163 +0,0 @@
----
-description: Generate or refresh docs/CURRENT_STATE.md and, if `docs/diagrams/` exists in this repo, docs/diagrams/c4-component.puml — the source-of-truth source map
----
-
-# /current-state
-
-Refresh `docs/CURRENT_STATE.md` and, if `docs/diagrams/` exists in this repo, `docs/diagrams/c4-component.puml` when component topology changes. Runs after each committed task, or standalone when the source map has drifted.
-
-This command is the **only** writer for `CURRENT_STATE.md` and, if `docs/diagrams/` exists in this repo, `c4-component.puml`. Do not touch either during implementation.
-
-## When to run
-
-- After a task is implemented and committed — typical use, run in the same thread.
-- Standalone, when the source map has drifted and needs catching up without a task in progress.
-- First time, to seed `CURRENT_STATE.md` for an existing codebase or a freshly-skeletoned project.
-
-## Required sections — CURRENT_STATE.md
-
-Exactly these headings, in this order. Empty section: keep the heading with `(none)`. Do not remove.
-
-```markdown
-# CURRENT_STATE
-
-## Purpose
-
-<1–2 sentences, caveman: what codebase does, for whom>
-
-## Stack
-
-<lang ⊕ framework ⊕ key libs; versions only when material>
-
-## Shipped capabilities
-
-<flat list, 1 line each — only end-user functionality working today>
-
-## Source map
-
-<folder/file tree, 1-line purpose per node — tech-lead pointer granularity>
-
-## Design patterns in use
-
-<pattern name → file/dir>
-
-## Public interfaces
-
-<HTTP routes / UI routes / CLI cmds / events / queues>
-
-## Data model digest
-
-<link to docs/diagrams/erd.puml ⊕ 1-line table list>
-
-## Component diagram
-
-<embed of rendered docs/diagrams/rendered/c4-component.svg, if `docs/diagrams/` exists in this repo>
-
-## Known debt / TODOs
-
-<short, current; deleted once addressed>
-```
-
-## Caveman style — whole file
-
-- Bullet fragments. Drop articles (`the`, `a`).
-- Symbols: `→` leads-to · `⊕` and-also · `~` approximately · `Δ` change · `&` and-also.
-- `file:line` over prose: `auth/login.ts:42` ✓ · "line 42 of auth/login.ts" ✗.
-- No hedging (`might`, `could`, `perhaps`) — state or omit.
-- No preamble, no meta, no restating the question.
-- 1 line per entry where possible.
-
-Example:
-
-```
-## Shipped capabilities
-- email/pw signup ⊕ verify
-- JWT auth → 7d refresh
-- profile edit (name, avatar)
-
-## Source map
-- src/auth/ — signup, login, JWT issuance
-  - login.ts:42 → token mint
-  - guards/ — route protection
-- src/users/ — CRUD ⊕ profile
-- src/db/ — Prisma client ⊕ migrations
-```
-
-## Inputs
-
-Gather these in order — the diff is the truth source; task or issue context describes intent:
-
-1. **`docs/CURRENT_STATE.md`** — baseline to preserve.
-2. **If `docs/diagrams/` exists in this repo, `docs/diagrams/c4-component.puml`** — component baseline.
-3. **Task or issue context** — identify from conversation context, linked issue/spec, or `git log -1 --format=%B`. Read named context docs for intended Δ when present.
-4. **Adjacent planning docs** — read only if linked by the task, issue, spec, or commit message.
-5. **`git diff HEAD~1`** — what actually shipped; trust this over intent docs if they diverge.
-
-## Procedure A — generate from scratch (no file exists)
-
-Covers (a) existing codebase adopting the methodology, (b) new project past design/skeleton phase.
-
-1. **Stack** — read manifests: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `tsconfig.json`, `vite.config.*`, `next.config.*`, `prisma/schema.prisma`, etc.
-2. **Source map** — walk top-down. Per top-level folder: read `index.*` / `mod.rs` / `__init__.py`, the largest file, any `README.md`. Stop at tech-lead-pointer granularity (deep enough to route a dev to the right file, no deeper). Symbol-level entries only when the symbol _is_ the landmark.
-3. **Public interfaces** — find route registrations (Express/NestJS/FastAPI/Django/etc.), CLI entry points (`bin/`, `cmd/`, `cli.*`), event/queue handlers.
-4. **Data model digest** — read schema + migrations → 1-line table list. Link `docs/diagrams/erd.puml` if it exists; if not, link `prisma/schema.prisma` or equivalent. Do not inline schema.
-5. **Design patterns in use** — recurring shapes by directory naming + import graph (Repository, Service, UseCase, Controller, ...). Pattern → file/dir.
-6. **Shipped capabilities** — user-facing features actually working today. Skip in-flight or planned. If unsure what works, **ask the user**. Do not infer from task files or phase docs.
-7. **Component diagram** — if `docs/diagrams/` exists in this repo and `docs/diagrams/c4-component.puml` does not exist, create a minimal skeleton from the source map's top-level boundaries. Render to SVG via `docker run --rm -v "$PWD:/data" plantuml/plantuml -tsvg docs/diagrams/c4-component.puml`. Embed the rendered SVG path in the section. If `docs/diagrams/` does not exist in this repo, write `(none)` in the section.
-8. **Known debt / TODOs** — grep `TODO|FIXME|HACK|XXX`. Add obvious gaps spotted during the walk.
-9. **Purpose** — 1–2 caveman sentences. If unclear, **ask the user**. Do not guess.
-10. Apply caveman style end-to-end. Re-read once. Cut every word with no signal.
-
-After drafting: surface to user, ask for corrections. The first version is a draft, not the answer.
-
-## Procedure B — update an existing file
-
-Trigger: a task was just committed and `/current-state` is called in the same thread, or standalone drift correction.
-
-1. Read `docs/CURRENT_STATE.md` fully — establish the baseline.
-2. If `docs/diagrams/` exists in this repo, read `docs/diagrams/c4-component.puml` — establish the component baseline.
-3. Identify the completed task or issue from conversation context or `git log -1 --format=%B`. Read named context docs for intended Δ when present.
-4. Run `git diff HEAD~1` — confirm what actually shipped. This is the truth source.
-5. Map change to affected sections — most tasks touch 1–3:
-   - new dep → **Stack**
-   - new user-facing feature working today → **Shipped capabilities**
-   - new/renamed/removed file or folder, or purpose shift → **Source map**
-   - new endpoint/CLI/event → **Public interfaces**
-   - new migration → **Data model digest**
-   - new component or container relation → **Component diagram** if `docs/diagrams/` exists in this repo (edit `c4-component.puml`, re-render)
-   - new pattern adopted ⊕ old pattern retired → **Design patterns in use**
-   - debt resolved → **prune** from Known debt; new debt → add
-   - **Purpose** — touch only if scope actually shifted
-6. **Weigh new entries against the existing baseline.** A freshly-shipped task does not automatically replace older, more important entries. If the file is growing past one screen, prune low-signal entries first.
-7. Apply changes with the **Edit tool only** — surgical replacements. Never regenerate the file. Untouched sections stay byte-identical.
-8. **Prune obsolete entries.** File removed → delete source-map line. Pattern retired → delete entry. Debt resolved → delete item. Stale entries are worse than missing ones.
-9. New entries match surrounding density. Caveman throughout.
-10. If `docs/diagrams/` exists in this repo and `c4-component.puml` changed, re-render: `docker run --rm -v "$PWD:/data" plantuml/plantuml -tsvg docs/diagrams/c4-component.puml`. Update the embed path in the Component diagram section if the rendered filename changed.
-11. Re-read after editing. Cut redundancy the diff introduced.
-
-After updating: surface the diff of `CURRENT_STATE.md` to the user, flag any conflicts, ask for corrections. Once the user approves (or no corrections are needed), commit with a concise docs message such as:
-
-```
-docs: update CURRENT_STATE
-```
-
-Include only project-required trailers. Stage only `docs/CURRENT_STATE.md` and, if `docs/diagrams/` exists in this repo and changed, `docs/diagrams/c4-component.puml` plus its rendered SVG.
-
-## Conflict handling
-
-- **Task file says X, diff shows Y** → trust the diff. Note the divergence to the user.
-- **Manual human edit in `CURRENT_STATE.md` conflicts with new change** → trust the new change but **flag the conflict before overwriting**. The human edit may encode context the agent lacks.
-
-## Anti-bloat rules
-
-- No narrative. No restating code comments.
-- No planned, in-flight, or "next release" features. Only what works today.
-- No duplication of content that lives elsewhere — link instead (`→ prisma/schema.prisma`, `→ docs/diagrams/erd.puml`).
-- File grows with **source-tree structure**, not task count. Growing per-task → wrong content going in; rework the entry until it describes structure, not the task.
-- No business detail — that lives in `docs/features/`. `CURRENT_STATE.md` is a source map, not a feature catalog.
-- No history — `CURRENT_STATE.md` answers "what is"; `CHANGELOG.md` answers "how we got here". They never overlap.
-
-## Out of scope
-
-- Appending to `CHANGELOG.md`.
-- Editing unrelated requirements, prototypes, class diagrams, ERDs, context diagrams, or container diagrams.

package/templates/docs/CURRENT_STATE.md

@@ -1,38 +0,0 @@
-# CURRENT_STATE
-
-## Purpose
-
-<agent: fill via /current-state>
-
-## Stack
-
-- <agent: fill via /current-state>
-- <agent: fill via /current-state>
-
-## Shipped capabilities
-
-- <agent: fill via /current-state>
-
-## Source map
-
-- `<agent: fill via /current-state>` - <agent: fill via /current-state>
-
-## Design patterns in use
-
-- <agent: fill via /current-state> -> <agent: fill via /current-state>
-
-## Public interfaces
-
-- <agent: fill via /current-state> -> <agent: fill via /current-state>
-
-## Data model digest
-
-- <agent: fill via /current-state> - <agent: fill via /current-state>
-
-## Component diagram
-
-- <agent: fill via /current-state>
-
-## Known debt / TODOs
-
-- <agent: fill via /current-state>

package/templates/docs/conventions/current-state.md

@@ -1,9 +0,0 @@
-# Current State Policy
-
-## Policy
-
-- Agents read it before broad exploration.
-- If it answers the question, agents should not re-crawl the repo.
-- It should be updated only by an explicit command or maintenance workflow.
-- If stale, agents should report staleness instead of silently rewriting it during unrelated work.
-- Only `/current-state` writes `docs/CURRENT_STATE.md`.

package/templates/docs/conventions/doc-lifecycle.md

@@ -1,16 +0,0 @@
-# Documentation Lifecycle
-
-## Common categories
-
-| Category | Examples | Lifecycle |
-|---|---|---|
-| Durable | architecture, ADRs, glossary, operations, current-state conventions | Long-lived |
-| Planning | roadmap, phases, feature plans, task docs | Archived or removed after shipped |
-| Runbooks | deployment, rollback, manual checks, provider setup | Updated when operations change |
-| Deferred work | parked plans and revisit triggers | Removed when built or rejected |
-
-## Why this matters
-
-- Prevents agents from treating stale plans as shipped behavior.
-- Prevents durable docs from depending on soon-archived docs.
-- Gives agents a clear source of truth for scope disputes.