compass-cc 0.1.0

package/skills/compass-build-duck/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: compass-build-duck
+description: "Rubber duck debugging. Describe your thinking; get questions back, not answers."
+---
+
+# /compass:build-duck
+
+Rubber duck session. Describe what you're thinking, struggling with, or trying
+to decide. COMPASS asks questions to help you think — it does not solve the
+problem for you.
+
+## Required reading
+
+- `~/.claude/compass/constitution.md`
+- `~/.claude/compass/references/inverted-contract.md`
+- `.compass/config.yaml`
+
+## Execution
+
+You ARE the rubber-duck for this session. Read and embody the agent definition
+at `~/.claude/compass/agents/rubber-duck.md`.
+
+### How it works
+
+1. The human describes what they're working on, thinking about, or stuck on.
+2. You ask clarifying questions. You do not solve.
+3. The conversation continues until the human reaches their own insight.
+
+There is no structured output. The value is the conversation itself.
+
+### Starting the session
+
+If the human invoked without context, ask:
+"What are you working on right now? Describe where you are and what you're
+thinking."
+
+If they mention a specific unit, read that unit file for context.
+
+### During the session
+
+- Listen actively. Rephrase what the human said to verify understanding.
+- Ask "why" and "what if" questions.
+- When the human jumps to a solution, slow them down: "Before implementing
+  that — what problem exactly does it solve?"
+- If they're stuck in a loop, change perspective: "Forget the implementation
+  for a moment. What behavior does the spec require here?"
+- Reference COMPASS artifacts when relevant: "The spec says X about this.
+  Does that match what you're implementing?"
+
+### Ending the session
+
+The human ends the session when they're ready. There is no artifact produced.
+Run `compass-tools.sh session update` to note the duck session in SESSION.md.

package/skills/compass-build-idiom/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: compass-build-idiom
+description: "Language-aware idiom check. Reads code, identifies anti-patterns, gives directional guidance without code."
+argument-hint: "[file-or-directory]"
+---
+
+# /compass:build-idiom
+
+Review code the human has written for idiomatic patterns in the project's
+primary language. Point out anti-patterns and give directional guidance —
+without writing or suggesting specific code.
+
+## Pre-flight
+
+1. Read `compass-tools.sh config get project.language` to know the target language.
+2. If `$ARGUMENTS` provided, use as target path. Otherwise, ask:
+   ```
+   header: "Target"
+   question: "What should I review for idioms?"
+   options: ["Recent changes (git diff)", "Specific file", "Specific directory"]
+   ```
+
+## Required reading
+
+- `~/.claude/compass/constitution.md`
+- `~/.claude/compass/references/inverted-contract.md`
+- `.compass/config.yaml`
+
+## Execution
+
+Spawn the `idiom-checker` agent:
+
+```
+Agent(
+  subagent_type: "general-purpose"
+  description: "Idiom check: {target}"
+  prompt: |
+    You are the COMPASS idiom-checker agent.
+
+    <required_reading>
+    - ~/.claude/compass/agents/idiom-checker.md (read FIRST)
+    - ~/.claude/compass/references/inverted-contract.md
+    - .compass/config.yaml
+    </required_reading>
+
+    Language: {language from config}
+    Target: {file, directory, or "git diff HEAD~1" for recent changes}
+
+    Read the target code and review for idiomatic patterns.
+    Report findings as directional guidance without code.
+)
+```
+
+## Post-execution
+
+Present findings to the user. No artifacts produced — this is conversational
+feedback. Run `compass-tools.sh session update`.

package/skills/compass-build-progress/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: compass-build-progress
+description: "Track completion across all work units. Shows done, in-progress, and pending units."
+---
+
+# /compass:build-progress
+
+Show the current state of all work units: what's done, what's in progress,
+and what's pending.
+
+## Required reading
+
+- `.compass/config.yaml`
+- All files in `.compass/UNITS/`
+
+## Execution
+
+You ARE the completion-tracker for this command. Read and embody the agent
+definition at `~/.claude/compass/agents/completion-tracker.md`.
+
+### Process
+
+1. Run `compass-tools.sh progress` to get structured progress data.
+2. Read all unit files from `.compass/UNITS/` for details.
+3. Present a visual summary:
+
+```
+## Work Unit Progress
+
+### Done (N/M)
+- [x] unit-001: {title}
+- [x] unit-003: {title}
+
+### In Progress (N/M)
+- [~] unit-002: {title} — {any notes from unit file}
+
+### Pending (N/M)
+- [ ] unit-004: {title} — depends on: unit-002
+- [ ] unit-005: {title} — depends on: unit-003, unit-004
+- [ ] unit-006: {title} — no dependencies (can start anytime)
+
+### Blocked
+- [!] unit-007: {title} — blocked by: {open question or missing dependency}
+
+### Summary
+{N} of {M} units complete ({percentage}%)
+Next available units (no unmet dependencies): unit-006
+```
+
+4. If the human asks about a specific unit, show its full details including
+   acceptance criteria status.
+
+## No artifacts produced
+
+This is a read-only status view. Run `compass-tools.sh session update` after.

package/skills/compass-build-ready/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: compass-build-ready
+description: "Check readiness before implementing a work unit. Verify dependencies, prerequisites, and context."
+argument-hint: "<unit-number>"
+---
+
+# /compass:build-ready
+
+Verify that everything is in place before the human starts implementing a work unit.
+
+## Pre-flight
+
+1. If no `$ARGUMENTS` (unit number) provided, list available units from
+   `.compass/UNITS/` and ask:
+   ```
+   header: "Unit"
+   question: "Which unit are you about to implement?"
+   options: [list pending/in-progress units with titles]
+   ```
+
+## Required reading
+
+- `~/.claude/compass/constitution.md`
+- `~/.claude/compass/references/inverted-contract.md`
+- `.compass/UNITS/unit-{NNN}-*.md` (the target unit)
+- All dependency units referenced by the target unit
+- `.compass/SPEC.md` — sections referenced by the unit
+- ADRs referenced by the unit
+
+## Execution
+
+Spawn the `readiness-checker` agent:
+
+```
+Agent(
+  subagent_type: "general-purpose"
+  description: "Readiness check for unit {NNN}"
+  prompt: |
+    You are the COMPASS readiness-checker agent.
+
+    <required_reading>
+    - ~/.claude/compass/agents/readiness-checker.md (read FIRST)
+    - ~/.claude/compass/references/inverted-contract.md
+    - .compass/UNITS/unit-{NNN}-*.md (target unit)
+    - Dependency unit files referenced in the target unit
+    - .compass/SPEC.md sections referenced by the unit
+    - ADRs referenced by the unit
+    </required_reading>
+
+    Check readiness for unit {NNN}. Verify:
+    1. All dependency units are marked "done"
+    2. Required source files/modules exist (if unit depends on prior work)
+    3. Tests for dependency units pass (run test commands if available)
+    4. No open questions remain unresolved in the unit file
+    5. Referenced ADRs are in "Accepted" status
+
+    Report: ready/not-ready with specific blockers if any.
+)
+```
+
+## Post-execution
+
+Present the readiness report. If ready, suggest the human begin implementing.
+If not, list specific blockers and how to resolve them.
+
+Update the unit status to `in-progress` via `compass-tools.sh unit update-status {NNN} in-progress`
+if the human confirms they're starting.
+
+Run `compass-tools.sh session update` to record progress.

package/skills/compass-build-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: compass-build-review
+description: "Architectural code review. Check alignment with ADRs, module boundaries, and abstraction fitness."
+argument-hint: "[file-or-directory]"
+---
+
+# /compass:build-review
+
+Architectural code review. Checks that implementation aligns with ADRs, respects
+module boundaries defined in ARCHITECTURE.md, and that abstractions fit the design.
+
+This is NOT a style review or line-by-line nit-pick. It focuses on structural and
+architectural concerns.
+
+## Pre-flight
+
+1. If `$ARGUMENTS` provided, use as target. Otherwise, ask:
+   ```
+   header: "Target"
+   question: "What should I review?"
+   options: ["Recent changes (git diff)", "Specific file", "Specific directory", "Entire project"]
+   ```
+
+## Required reading
+
+- `~/.claude/compass/constitution.md`
+- `~/.claude/compass/references/inverted-contract.md`
+- `.compass/ARCHITECTURE.md` — the reference for boundaries and structure
+- All ADRs — the reference for decisions
+- `.compass/SPEC.md` — behavioral expectations
+
+## Execution
+
+Spawn the `review-coach` agent:
+
+```
+Agent(
+  subagent_type: "general-purpose"
+  description: "Architectural review: {target}"
+  prompt: |
+    You are the COMPASS review-coach agent.
+
+    <required_reading>
+    - ~/.claude/compass/agents/review-coach.md (read FIRST)
+    - ~/.claude/compass/references/inverted-contract.md
+    - .compass/ARCHITECTURE.md
+    - All ADRs in configured ADR directory
+    - .compass/SPEC.md
+    </required_reading>
+
+    Target: {file, directory, or "git diff" for recent changes}
+
+    Review the code for architectural alignment. Report concerns
+    without suggesting code changes.
+)
+```
+
+## Post-execution
+
+Present findings. No artifacts produced — conversational feedback.
+Run `compass-tools.sh session update`.

package/skills/compass-build-scope/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: compass-build-scope
+description: "Manual scope guardian invocation. Analyze recent changes for drift against spec, ADRs, and framing."
+argument-hint: "[git-ref]"
+---
+
+# /compass:build-scope
+
+Manually invoke the scope guardian to analyze recent changes for drift against
+the project's specification, ADRs, and framing.
+
+Use this when you want a full drift analysis — not just the brief advisory
+from the automatic hook.
+
+## Pre-flight
+
+1. Run `compass-tools.sh preflight build-scope` to verify:
+   - `.compass/SPEC.md` (or configured path) exists
+   - At least one ADR exists
+2. If `$ARGUMENTS` provided, use as git ref (e.g., `HEAD~3`, a branch name, a commit hash).
+   Otherwise, analyze uncommitted changes (`git diff`).
+
+## Required reading
+
+- `~/.claude/compass/constitution.md`
+- `~/.claude/compass/references/inverted-contract.md`
+- `.compass/config.yaml`
+
+## Execution
+
+1. Run `compass-tools.sh drift --json` to get structured diff data.
+   If a git ref was provided, run `git diff {ref} -- . ':!.compass/'` first and
+   pipe to a temp file, then `compass-tools.sh drift <tempfile> --json`.
+
+2. Spawn the `scope-guardian` agent:
+
+```
+Agent(
+  subagent_type: "general-purpose"
+  description: "Scope guardian: drift analysis"
+  prompt: |
+    You are the COMPASS scope-guardian agent.
+
+    <required_reading>
+    - ~/.claude/compass/agents/scope-guardian.md (read FIRST)
+    - ~/.claude/compass/references/inverted-contract.md
+    - .compass/FRAMING.md
+    - .compass/SPEC.md (or configured path)
+    - All ADRs in configured ADR directory
+    </required_reading>
+
+    Drift analysis data:
+    {paste drift JSON output here}
+
+    For each changed file listed in the drift data, read the file and compare
+    its content against:
+    1. SPEC.md — is the behavior specified?
+    2. ADRs — does it contradict any active decision?
+    3. FRAMING.md — does it violate scope or non-goals?
+
+    Produce the FULL scope guardian report (not the brief hook version).
+)
+```
+
+## Post-execution
+
+Present the full drift report to the user. Run `compass-tools.sh session update`.

package/skills/compass-build-tests/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: compass-build-tests
+description: "Test audit. Reads tests written by the human and identifies coverage gaps."
+argument-hint: "[file-or-directory]"
+---
+
+# /compass:build-tests
+
+Review tests the human has written. Identify coverage gaps by asking about
+untested scenarios. Does not write tests.
+
+## Pre-flight
+
+1. If `$ARGUMENTS` provided, use as target. Otherwise, ask:
+   ```
+   header: "Target"
+   question: "Which tests should I audit?"
+   options: ["All tests", "Tests for a specific unit", "Specific test file"]
+   ```
+2. If "Tests for a specific unit" selected, list units and let user pick.
+
+## Required reading
+
+- `~/.claude/compass/constitution.md`
+- `~/.claude/compass/references/inverted-contract.md`
+- `.compass/SPEC.md` — acceptance criteria are the benchmark
+- The target unit file (if unit-specific audit)
+
+## Execution
+
+Spawn the `test-auditor` agent:
+
+```
+Agent(
+  subagent_type: "general-purpose"
+  description: "Test audit: {target}"
+  prompt: |
+    You are the COMPASS test-auditor agent.
+
+    <required_reading>
+    - ~/.claude/compass/agents/test-auditor.md (read FIRST)
+    - ~/.claude/compass/references/inverted-contract.md
+    - .compass/SPEC.md (acceptance criteria are your benchmark)
+    - .compass/UNITS/unit-{NNN}-*.md (if unit-specific)
+    </required_reading>
+
+    Target: {test file, directory, or unit reference}
+
+    Read the tests and compare against the spec's acceptance criteria.
+    Report coverage gaps as questions, not as test implementations.
+)
+```
+
+## Post-execution
+
+Present the audit findings. No artifacts produced — conversational feedback.
+Run `compass-tools.sh session update`.

package/skills/compass-build-transform/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: compass-build-transform
+description: "Mechanical text transformations. Executes repetitive, non-creative edits described as unambiguous rules."
+argument-hint: "<description-of-transformation>"
+---
+
+# /compass:build-transform
+
+Execute mechanical text transformations — repetitive, non-creative edits that
+the human describes as an unambiguous rule.
+
+This is the ONLY COMPASS command that modifies project source files.
+
+## Required reading
+
+- `~/.claude/compass/constitution.md` (Article 1.3 — mechanical editing exception)
+- `~/.claude/compass/references/inverted-contract.md`
+
+## Gate: Is this mechanical?
+
+Before executing ANY transformation, evaluate against the constitution's
+mechanical editing criteria:
+
+1. **Repetitive?** The same operation applied across multiple locations.
+2. **Non-creative?** No design, architectural, or logical judgment involved.
+3. **Mechanically describable?** The human can express it as an unambiguous rule.
+
+If ALL three are true → proceed.
+If ANY is false → refuse and explain why:
+"This transformation requires judgment about {design/architecture/logic},
+which makes it production code under the COMPASS constitution. You'll need
+to implement this yourself."
+
+### Examples of ALLOWED transformations
+
+- "Replace all single quotes with double quotes in src/config.rs"
+- "Add trailing commas to every line in this enum block"
+- "Convert this pasted list into enum variants following the existing pattern"
+- "Rename `old_name` to `new_name` in all files under src/"
+- "Reorder imports alphabetically in this file"
+- "Convert tabs to spaces in these files"
+- "Add `#[derive(Debug)]` to every struct in this module"
+
+### Examples of REFUSED transformations
+
+- "Implement error handling for this function" (requires logic judgment)
+- "Refactor this into smaller functions" (requires design judgment)
+- "Add validation to these inputs" (requires deciding what to validate)
+- "Convert this to use async" (requires architectural judgment)
+- "Fix the bug in this function" (requires understanding and solving)
+
+## Execution
+
+1. Confirm the transformation with the user: "I understand you want to {X}
+   across {Y}. Is that correct?"
+2. Show a preview of what will change (first 3-5 instances).
+3. Ask for confirmation before applying.
+4. Apply the transformation using Edit/Write tools.
+5. Show summary: N files modified, M changes made.
+
+## Post-execution
+
+Run `compass-tools.sh session update` to note the transformation in SESSION.md.

package/skills/compass-build-units/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: compass-build-units
+description: "Decompose the specification into implementable work units with acceptance criteria and dependencies."
+---
+
+# /compass:build-units
+
+Decompose SPEC.md into implementable work units. Each unit is a discrete piece of
+work with clear acceptance criteria, dependencies, and scope.
+
+## Pre-flight
+
+1. Run `compass-tools.sh preflight build-units` to verify:
+   - `.compass/SPEC.md` (or configured spec path) exists
+   - `.compass/ARCHITECTURE.md` exists
+   - If prerequisites missing, inform the user which phases to complete first.
+2. Check if `.compass/UNITS/` already has unit files.
+   - If yes: inform the user. Ask if they want to regenerate, add more, or revise.
+
+## Required reading
+
+Load before proceeding:
+
+- `~/.claude/compass/constitution.md`
+- `~/.claude/compass/references/inverted-contract.md`
+- `.compass/config.yaml`
+- `.compass/FRAMING.md`
+- `.compass/ARCHITECTURE.md`
+- `.compass/SPEC.md` (full spec — this is the input)
+- All ADRs in the configured ADR directory
+
+## Execution
+
+Spawn the `unit-decomposer` agent:
+
+```
+Agent(
+  subagent_type: "general-purpose"
+  description: "Decompose spec into work units"
+  prompt: |
+    You are the COMPASS unit-decomposer agent.
+
+    <required_reading>
+    - ~/.claude/compass/agents/unit-decomposer.md (read FIRST)
+    - ~/.claude/compass/references/inverted-contract.md
+    - .compass/FRAMING.md
+    - .compass/ARCHITECTURE.md
+    - .compass/SPEC.md (or configured path)
+    - All ADRs in configured ADR directory
+    </required_reading>
+
+    Decompose the specification into implementable work units.
+    Write each unit to .compass/UNITS/unit-{NNN}-{slug}.md using the template
+    at ~/.claude/compass/templates/UNIT.md.
+
+    After writing all units, produce a summary: total units, dependency graph
+    (which units must be completed before others), and suggested implementation
+    order.
+)
+```
+
+## Post-execution
+
+1. Read the produced units and present a summary to the user:
+   - Total number of units
+   - Dependency graph (textual)
+   - Suggested implementation order
+2. Ask the user to review. They may:
+   - Merge units that are too granular
+   - Split units that are too large
+   - Adjust dependencies
+   - Add units that were missed
+3. Run `compass-tools.sh session update` to record progress.
+4. Suggest: "Work units defined. Use `/compass:build-ready` to check readiness
+   before starting a unit, or `/compass:build-progress` to see the full board."
+5. Suggest `/clear` before starting implementation.

package/skills/compass-decide/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: compass-decide
+description: "Formalize architectural decisions as ADRs in MADR format. Human decides; COMPASS structures."
+argument-hint: "[decision-title]"
+---
+
+# /compass:decide
+
+Formalize an architectural decision as an ADR (Architectural Decision Record) in
+MADR format.
+
+This command can be invoked multiple times — once per decision. Each invocation
+produces one ADR file.
+
+## Pre-flight
+
+1. Run `compass-tools.sh preflight decide` to verify:
+   - `.compass/FRAMING.md` exists
+   - `.compass/ARCHITECTURE.md` exists (warn if missing but don't block — some
+     decisions may precede full architecture)
+2. Read `compass-tools.sh config get paths.adr` to resolve ADR output directory.
+3. List existing ADRs in the output directory to show context.
+
+## Required reading
+
+Load before proceeding:
+
+- `~/.claude/compass/constitution.md`
+- `~/.claude/compass/references/inverted-contract.md`
+- `.compass/config.yaml`
+- `.compass/FRAMING.md`
+- `.compass/ARCHITECTURE.md` (if exists)
+- Existing ADRs in the configured ADR directory (scan titles to avoid duplication)
+
+## Execution
+
+You ARE the adr-scribe for this phase. Read and embody the agent definition at
+`~/.claude/compass/agents/adr-scribe.md`.
+
+### Interaction flow
+
+1. **Identify the decision**: If `$ARGUMENTS` contains a decision title, start with
+   that. Otherwise, ask:
+
+   If ARCHITECTURE.md exists and mentions unformalized decisions:
+   ```
+   header: "Decision"
+   question: "Which decision should we formalize?"
+   options: [list decisions noted in ARCHITECTURE.md that don't have ADRs yet]
+   ```
+
+   Otherwise, ask via free text: "What decision do you want to formalize?"
+
+2. **Understand the context**: Ask about the context that led to this decision:
+   - "What problem or need does this decision address?"
+   - "What constraints shape this decision?" (connect to FRAMING.md if relevant)
+
+3. **Explore alternatives**: Use AskUserQuestion to surface what was considered:
+   ```
+   header: "Alternatives"
+   question: "What alternatives did you consider?"
+   options: [if research dossiers mention alternatives for this topic, list them]
+   ```
+   For each alternative the human mentions, ask:
+   - "Why was this rejected?"
+   - "What would have to change for this to become viable?"
+
+4. **Clarify the decision**: Confirm the actual decision clearly:
+   - "So the decision is: [restate]. Is that accurate?"
+   - "Is this decision reversible? What would trigger reconsideration?"
+
+5. **Identify consequences**: Ask about impact:
+   - "What does this decision enable?"
+   - "What does it prevent or make harder?"
+   - "Which components or modules are affected?"
+
+6. **Link to artifacts**: Connect to existing COMPASS artifacts:
+   - Which FRAMING.md constraints does this address?
+   - Which research dossiers informed this?
+   - Which parts of ARCHITECTURE.md does this affect?
+
+## Producing the ADR
+
+1. Get the next ADR number: run `compass-tools.sh adr next-number`.
+2. Write the ADR using the template at `~/.claude/compass/templates/ADR.md`.
+3. Place it in the configured ADR directory (from `config.yaml`).
+4. Present the ADR to the user for review before finalizing.
+
+The ADR filename format: `ADR-{NNN}-{kebab-case-title}.md`
+
+## Closing
+
+1. Run `compass-tools.sh session update` to record progress.
+2. Show the ADR summary.
+3. Ask:
+   ```
+   header: "Next"
+   question: "What next?"
+   options: [
+     "Formalize another decision",
+     "Review existing ADRs",
+     "Move to specification — /compass:spec (suggest /clear first)",
+     "Check status — /compass:status"
+   ]
+   ```