compass

Sidecar annotation system for Compass vault files. Agents attach persistent notes that auto-surface when files are read. Lightweight alternative to full lessons.

Run the full Compass pipeline (research → plan → build → test → validate) for S/M tasks. Orchestrates the actual agents with human checkpoints.

Execute tasks from active.md by spawning builder agents. Handles parallel execution for non-overlapping tasks, the fix loop, and optional validation.

Scan a Compass project for problems - missing agents, stale handoffs, unclosed tasks, vault inconsistencies, broken hooks, missing config. Reports what's wrong and how to fix it.

Long-horizon merge, prune, and demote pass over the lessons set. Runs only when a hard-cap warning is present (proves bloat triggered). Merges near-duplicates the per-phase dedup missed, rewrites verbose bodies preserving the displaced text in-file, archives stale baseline-score lessons, rebuilds the catalog and the index Lessons section. Never archives escalated lessons; flags them for human review.

Condense this project's file-based memory (the ~/.claude/projects/<project>/memory/ store) - merge duplicates, prune one-session and stale facts, condense verbose bodies, and rebuild MEMORY.md to one line per memory. Cuts the per-session context the memory loads.

Investigate errors, test failures, or unexpected behavior in your project by spawning the debug agent in an isolated context. (Named diagnose to avoid colliding with Claude Code's built-in /debug skill.)

Retrospectively extract lessons from a capture opportunity. Reads opportunity.json from .compass/tmp/capture-opportunities/OPP-<UTC>/, checks the binary triggers against the opportunity's kind and evidence, applies the anti-list, hands survivors to lesson-write, and may revise or archive a lesson through lesson-write when opportunity evidence contradicts it. Writes an audit log of every candidate considered (aged into archive/logs/ after 30 days) and closes the opportunity via `compass capture-close`. Never invoked directly by humans.

Interactive guide for working with Compass. Detects where you are in the workflow, explains what to do next, and can spawn the right agents for you. Also helps port existing projects into Compass.

Create a handoff at end of session, or resume from one at start. Create compresses context into a portable document. Resume verifies state and presents a situational report.

Refresh .compass derived state (root index, tag index, catalog rows, cap warnings, log cleanup) by running `compass sync`. The mechanical work lives in the CLI; this skill invokes it and surfaces findings.

Capture an in-the-moment lesson the human just noticed. One-line argument; the skill infers category (process or domain via Reinertsen) plus area and tags, then hands off to lesson-write. Use when the human types /compass:learned to record a discovery before they forget.

Write or update a lesson in the .compass/ vault. Loads the catalog as a dedup manifest, applies the anti-list filter, enforces the 5-line body cap, and atomically updates the lesson file plus catalog plus index. Handles recurrence escalation. Called by extract-lessons and /compass:learned. Never call directly from prose.

How to search and apply lessons from the .compass/ vault. Catalog structure and search algorithm. Creation is handled by the lesson-write skill, called by extract-lessons or /compass:learned - never created in agent prose.

The Compass development workflow pipeline - Spec, Research, Plan, Tasks, Build, Validate - with human involvement gradient, status transitions, testing mandate, and required artifacts enforcement

Obsidian-compatible formatting conventions - YAML frontmatter schema, wikilinks, file naming, vault search patterns, and document templates for the .compass/ vault

Look up and read academic papers from Hugging Face paper pages or arXiv. Fetches paper markdown, structured metadata, linked models/datasets, citing papers, and the citation graph. Use for deep research on techniques, algorithms, and implementations.

Create a new implementation plan or iterate on an existing one. For new plans, spawns the planner agent. For iterations, handles the surgical editing flow inline with confirmation gates.

Promote a flat spec into a folder spec. The CLI does the move (`compass promote`); this skill decides when to promote and guides authoring the children.

Report a Compass bug. Captures it locally (deduped by fingerprint) via the compass CLI and files it as a GitHub issue against the Compass repo, skipping any duplicate that is already open.

Router for research. Dispatches to /compass:research-codebase or /compass:research-papers depending on whether the question is about code or about an academic paper / algorithm.

Document the codebase as it exists today by spawning parallel sub-agents (codebase-locator, codebase-analyzer, pattern-finder). Output is a research document saved to .compass/research/. You are a documentarian, not a critic - describe what IS, not what SHOULD BE.

Investigate an academic paper, algorithm, or technique using the citation graph - Current (the paper itself), Backward (ancestors / why it works), Forward (descendants / how it evolved). Output is a research document saved to .compass/research/.

Create vault artifacts (specs, tasks, ADRs, lessons) for work that already happened without Compass. Interviews the human one question at a time to document the intent behind existing commits.

Set up Compass in a project for the first time - creates the .compass/ vault, installs agents, rules, skills, the compass CLI, and hooks into .claude/, and proposes CLAUDE.md additions. To refresh an existing install, use /compass:update.

Interactive specification creation. Interviews the human one question at a time to capture the PROBLEM and the NEED, never the solution. Creates a draft spec in .compass/specs/ and gets human approval before marking it approved.

Capture a braindump of ideas, break them into separate specs, and write them all in batch with minimal repeated questioning. Use when you have multiple specs in your head at once.

Bulk-migrate a flat vault to the hierarchical+faceted scheme. Analyzes existing specs, proposes a faceted tag vocabulary and a folder hierarchy, presents the proposal as a diff, executes after human approval. Non-destructive - existing tags and references survive.

The operational admission bar for tests - what a single test must demonstrate to exist, the classes that never qualify, and per-type design guidance. Loaded by the tester agent in both its pre-build and post-build stations; the validator audits against the same names.

Update an existing Compass install in this project from GitHub - refreshes agents, rules, skills, the compass CLI, and hooks. Pulls from the canonical git repository, never from a local copy. Does not touch the .compass vault.

Run the validator agent as the final quality gate. Compares plan against actual implementation, runs adversarial probes, issues VERDICT.

Validate Compass vault integrity - frontmatter and wikilinks via `compass validate`, plus orphan and bare-reference detection. Reports vault health with actionable fixes.

Capture the project's overall goal, scope, and the full set of needs that will become specs. Run BEFORE creating individual specs to avoid bundling unrelated needs into one giant spec. Output is a vision document and a proposed spec list.