compass-cc 0.1.0 → 0.1.4

package/README.md

@@ -96,7 +96,7 @@ COMPASS externalizes all state to `.compass/` in the target project:
 ```
 
 State files are the source of truth — not conversation history. All state mutations
-go through `compass-tools.sh` (deterministic, no LLM involved).
+go through `~/.claude/compass/scripts/compass-tools.sh` (deterministic, no LLM involved).
 
 ---
 

package/constitution.md

@@ -93,7 +93,7 @@ All project state lives in files under `.compass/` in the target project.
 - Every decision, artifact, and progress marker must be persisted to a file.
 - State files are the authoritative record. If conversation context and files
   disagree, the files are correct.
-- State mutations go through `compass-tools.sh` — sub-agents must not directly
+- State mutations go through `~/.claude/compass/scripts/compass-tools.sh` — sub-agents must not directly
   edit `SESSION.md`, `config.yaml`, or progress markers.
 
 ---
@@ -106,7 +106,7 @@ Each sub-agent invocation is stateless. It loads only the files it needs via exp
 - Sub-agents must not assume prior conversation context.
 - Sub-agents must not assume other sub-agents have run unless their artifacts exist
   in `.compass/`.
-- The pre-flight check (`compass-tools.sh preflight`) is the authoritative source
+- The pre-flight check (`~/.claude/compass/scripts/compass-tools.sh preflight`) is the authoritative source
   for whether prerequisites are met.
 
 ---
@@ -130,7 +130,7 @@ Nothing advances without the human saying so.
 ADRs are mandatory for non-trivial architectural decisions.
 
 - Format: MADR (Markdown Any Decision Records).
-- Each ADR lives in its own file, numbered sequentially by `compass-tools.sh adr next-number`.
+- Each ADR lives in its own file, numbered sequentially by `~/.claude/compass/scripts/compass-tools.sh adr next-number`.
 - ADRs are linked to requirements in FRAMING.md and, later, to code locations.
 - The scope-guardian checks diffs against active ADRs for contradictions.
 - ADR location is configurable via `config.yaml` (default: `.compass/ADR/`).
@@ -159,7 +159,7 @@ File existence checks, phase numbering, progress tracking, drift detection setup
 ADR numbering, and session state updates are handled by deterministic scripts —
 not by LLM reasoning.
 
-- `compass-tools.sh` is the canonical tool for all bookkeeping operations.
+- `~/.claude/compass/scripts/compass-tools.sh` is the canonical tool for all bookkeeping operations.
 - Sub-agents call the script for state queries and mutations.
 - The script's output is authoritative over any LLM inference about state.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compass-cc",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "COMPASS — Collaborative Orientation, Mapping, Planning, Architecture, Spec & Supervision. An inverted AI coding skill: the human implements, the LLM orients.",
   "license": "MIT",
   "author": "hvpaiva",

package/references/inverted-contract.md

@@ -18,7 +18,7 @@ This reference is loaded by every COMPASS sub-agent. It is non-negotiable.
 - Report problems without prescribing code solutions.
 - Respect phase gates — never advance without human approval.
 - Read state from `.compass/` files, not from conversation memory.
-- Call `compass-tools.sh` for state mutations, never edit state files directly.
+- Call `~/.claude/compass/scripts/compass-tools.sh` for state mutations, never edit state files directly.
 
 ## Mechanical editing exception
 

package/skills/compass-architect/SKILL.md

@@ -11,7 +11,7 @@ document the result.
 
 ## Pre-flight
 
-1. Run `compass-tools.sh preflight architect` to verify:
+1. Run `~/.claude/compass/scripts/compass-tools.sh preflight architect` to verify:
    - `.compass/FRAMING.md` exists
    - `.compass/RESEARCH/` has at least one dossier
    - If prerequisites missing, inform the user which phases to complete first.
@@ -82,7 +82,7 @@ Present the document to the user for review before finalizing.
 
 ## Closing
 
-1. Run `compass-tools.sh session update` to record progress.
+1. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
 2. Show summary of what was documented.
 3. Note any decisions that surfaced during the architecture session that should
    become formal ADRs.

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

@@ -50,4 +50,4 @@ If they mention a specific unit, read that unit file for context.
 ### 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.
+Run `~/.claude/compass/scripts/compass-tools.sh session update` to note the duck session in SESSION.md.

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

@@ -12,7 +12,7 @@ without writing or suggesting specific code.
 
 ## Pre-flight
 
-1. Read `compass-tools.sh config get project.language` to know the target language.
+1. Read `~/.claude/compass/scripts/compass-tools.sh config get project.language` to know the target language.
 2. If `$ARGUMENTS` provided, use as target path. Otherwise, ask:
    ```
    header: "Target"
@@ -54,4 +54,4 @@ Agent(
 ## Post-execution
 
 Present findings to the user. No artifacts produced — this is conversational
-feedback. Run `compass-tools.sh session update`.
+feedback. Run `~/.claude/compass/scripts/compass-tools.sh session update`.

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

@@ -20,7 +20,7 @@ definition at `~/.claude/compass/agents/completion-tracker.md`.
 
 ### Process
 
-1. Run `compass-tools.sh progress` to get structured progress data.
+1. Run `~/.claude/compass/scripts/compass-tools.sh progress` to get structured progress data.
 2. Read all unit files from `.compass/UNITS/` for details.
 3. Present a visual summary:
 
@@ -52,4 +52,4 @@ Next available units (no unmet dependencies): unit-006
 
 ## No artifacts produced
 
-This is a read-only status view. Run `compass-tools.sh session update` after.
+This is a read-only status view. Run `~/.claude/compass/scripts/compass-tools.sh session update` after.

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

@@ -63,7 +63,7 @@ Agent(
 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`
+Update the unit status to `in-progress` via `~/.claude/compass/scripts/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.
+Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.

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

@@ -58,4 +58,4 @@ Agent(
 ## Post-execution
 
 Present findings. No artifacts produced — conversational feedback.
-Run `compass-tools.sh session update`.
+Run `~/.claude/compass/scripts/compass-tools.sh session update`.

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

@@ -14,7 +14,7 @@ from the automatic hook.
 
 ## Pre-flight
 
-1. Run `compass-tools.sh preflight build-scope` to verify:
+1. Run `~/.claude/compass/scripts/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).
@@ -28,9 +28,9 @@ from the automatic hook.
 
 ## Execution
 
-1. Run `compass-tools.sh drift --json` to get structured diff data.
+1. Run `~/.claude/compass/scripts/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`.
+   pipe to a temp file, then `~/.claude/compass/scripts/compass-tools.sh drift <tempfile> --json`.
 
 2. Spawn the `scope-guardian` agent:
 
@@ -64,4 +64,4 @@ Agent(
 
 ## Post-execution
 
-Present the full drift report to the user. Run `compass-tools.sh session update`.
+Present the full drift report to the user. Run `~/.claude/compass/scripts/compass-tools.sh session update`.

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

@@ -54,4 +54,4 @@ Agent(
 ## Post-execution
 
 Present the audit findings. No artifacts produced — conversational feedback.
-Run `compass-tools.sh session update`.
+Run `~/.claude/compass/scripts/compass-tools.sh session update`.

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

@@ -60,4 +60,4 @@ to implement this yourself."
 
 ## Post-execution
 
-Run `compass-tools.sh session update` to note the transformation in SESSION.md.
+Run `~/.claude/compass/scripts/compass-tools.sh session update` to note the transformation in SESSION.md.

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

@@ -10,7 +10,7 @@ work with clear acceptance criteria, dependencies, and scope.
 
 ## Pre-flight
 
-1. Run `compass-tools.sh preflight build-units` to verify:
+1. Run `~/.claude/compass/scripts/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.
@@ -70,7 +70,7 @@ Agent(
    - Split units that are too large
    - Adjust dependencies
    - Add units that were missed
-3. Run `compass-tools.sh session update` to record progress.
+3. Run `~/.claude/compass/scripts/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

@@ -14,11 +14,11 @@ produces one ADR file.
 
 ## Pre-flight
 
-1. Run `compass-tools.sh preflight decide` to verify:
+1. Run `~/.claude/compass/scripts/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.
+2. Read `~/.claude/compass/scripts/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
@@ -81,7 +81,7 @@ You ARE the adr-scribe for this phase. Read and embody the agent definition at
 
 ## Producing the ADR
 
-1. Get the next ADR number: run `compass-tools.sh adr next-number`.
+1. Get the next ADR number: run `~/.claude/compass/scripts/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.
@@ -90,7 +90,7 @@ The ADR filename format: `ADR-{NNN}-{kebab-case-title}.md`
 
 ## Closing
 
-1. Run `compass-tools.sh session update` to record progress.
+1. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
 2. Show the ADR summary.
 3. Ask:
    ```

package/skills/compass-frame/SKILL.md

@@ -10,7 +10,7 @@ exists, and what constraints shape it.
 
 ## Pre-flight
 
-1. Run `compass-tools.sh preflight frame` to verify:
+1. Run `~/.claude/compass/scripts/compass-tools.sh preflight frame` to verify:
    - `.compass/config.yaml` exists (if not, suggest `/compass:init` first)
 2. Check if `.compass/FRAMING.md` already exists.
    - If yes: inform the user. Ask if they want to revise or start fresh.
@@ -99,7 +99,7 @@ If yes, collect the principles through conversation. Then append them to
 
 After FRAMING.md and constitution are written:
 
-1. Run `compass-tools.sh session update` to record progress.
+1. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
 2. Show summary of what was produced.
 3. Suggest: "Framing complete. Next step: `/compass:research` to investigate domain topics."
 4. Suggest `/clear` before the next phase.

package/skills/compass-init/SKILL.md

@@ -117,7 +117,7 @@ options: ["Yes — version all COMPASS artifacts", "No — add .compass/ to .git
 
 ## Step 4 — Scaffold .compass/ directory
 
-Run `compass-tools.sh init <project-root>` with the resolved config values.
+Run `~/.claude/compass/scripts/compass-tools.sh init <project-root>` with the resolved config values.
 
 This creates:
 ```
@@ -133,7 +133,7 @@ This creates:
 
 ## Step 5 — Confirm and suggest next step
 
-1. Run `compass-tools.sh session update` to record progress.
+1. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
 2. Show the user:
    - Summary of configuration choices
    - Directory structure created

package/skills/compass-next/SKILL.md

@@ -10,7 +10,7 @@ where they are and what the logical next step is.
 
 ## Execution
 
-1. Run `compass-tools.sh status --json` to get full project state.
+1. Run `~/.claude/compass/scripts/compass-tools.sh status --json` to get full project state.
 2. If the command fails (no `.compass/` found), suggest: "No COMPASS project
    found. Run `/compass:init` to get started."
 
@@ -55,6 +55,6 @@ where they are and what the logical next step is.
 ## Design notes
 
 - This command must be FAST. Minimal reading, no spawning, no heavy analysis.
-- It reads state from files and `compass-tools.sh` — never from conversation memory.
+- It reads state from files and `~/.claude/compass/scripts/compass-tools.sh` — never from conversation memory.
 - It works perfectly after a `/clear` because it depends only on `.compass/` files.
-- Run `compass-tools.sh session update` is NOT called — this is read-only.
+- Run `~/.claude/compass/scripts/compass-tools.sh session update` is NOT called — this is read-only.

package/skills/compass-research/SKILL.md

@@ -13,14 +13,18 @@ one dossier in `.compass/RESEARCH/`.
 
 ## Pre-flight
 
-1. Run `compass-tools.sh preflight research` to verify:
+1. Run `~/.claude/compass/scripts/compass-tools.sh preflight research` to verify:
    - `.compass/FRAMING.md` exists (if not, suggest `/compass:frame` first)
-2. If no `$ARGUMENTS` (topic) provided, ask the user:
+2. If no `$ARGUMENTS` (topic) provided, use AskUserQuestion with **multiSelect: true**
+   to let the user pick one or more topics at once:
    ```
-   header: "Topic"
-   question: "What topic should I research?"
-   options: [suggest topics derived from FRAMING.md gaps and risks, if identifiable]
+   header: "Topics"
+   question: "Which topics do you want to research?"
+   multiSelect: true
+   options: [derive 2-4 topics from FRAMING.md gaps, risks, and unknowns]
    ```
+   The user can also type a custom topic via the "Other" option.
+   Run one research agent per selected topic (in parallel when possible).
 
 ## Required reading
 
@@ -34,7 +38,11 @@ Load before proceeding:
 
 ## Execution
 
-Spawn the `domain-researcher` agent for the actual research work:
+For **each** selected topic, spawn a `domain-researcher` agent. When there are multiple
+topics, launch all agents **in parallel** (one Agent tool call per topic in the same message).
+
+Pre-assign dossier numbers sequentially before spawning (e.g., if the next number is 003
+and the user picked 3 topics, assign 003, 004, 005) to avoid race conditions.
 
 ```
 Agent(
@@ -55,7 +63,7 @@ Agent(
     Project context: [summarize FRAMING.md key points — mission, scope, constraints]
 
     Produce a research dossier at: .compass/RESEARCH/dossier-{NNN}-{slug}.md
-    where {NNN} is the next dossier number (check existing files in .compass/RESEARCH/).
+    (your assigned number is {NNN} — do not change it).
 
     Use the template at ~/.claude/compass/templates/RESEARCH-DOSSIER.md for structure.
 
@@ -65,17 +73,11 @@ Agent(
 
 ## Post-execution
 
-1. Read the produced dossier and present a summary to the user.
-2. Run `compass-tools.sh session update` to record progress.
-3. Ask the user:
-   ```
-   header: "Research"
-   question: "What next?"
-   options: [
-     "Research another topic",
-     "Review/revise this dossier",
-     "Move to architecture — /compass:architect",
-     "Check status — /compass:status"
-   ]
-   ```
+1. Read all produced dossiers and present a summary of each to the user.
+2. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
+3. Ask the user what to do next (as a regular text message, not AskUserQuestion):
+   - Research another topic
+   - Review/revise a dossier
+   - Move to architecture — `/compass:architect`
+   - Check status — `/compass:status`
 4. Suggest `/clear` before starting a new phase.

package/skills/compass-spec/SKILL.md

@@ -11,12 +11,12 @@ invariants, boundary conditions.
 
 ## Pre-flight
 
-1. Run `compass-tools.sh preflight spec` to verify:
+1. Run `~/.claude/compass/scripts/compass-tools.sh preflight spec` to verify:
    - `.compass/FRAMING.md` exists
    - `.compass/ARCHITECTURE.md` exists
    - At least one ADR exists in the configured ADR directory
    - If prerequisites missing, inform the user which phases to complete first.
-2. Read `compass-tools.sh config get paths.spec` to resolve spec output path.
+2. Read `~/.claude/compass/scripts/compass-tools.sh config get paths.spec` to resolve spec output path.
 3. Check if spec file already exists.
    - If yes: inform the user. Ask if they want to revise, extend, or start fresh.
 
@@ -107,7 +107,7 @@ spec is reviewed at the end before finalizing.
 
 ## Closing
 
-1. Run `compass-tools.sh session update` to record progress.
+1. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
 2. Show summary: number of modules specified, total behaviors, total acceptance
    criteria.
 3. Suggest: "Specification complete. Next step: `/compass:build-units` to

package/skills/compass-status/SKILL.md

@@ -10,7 +10,7 @@ every artifact, and (in build phase) every work unit.
 
 ## Execution
 
-1. Run `compass-tools.sh status --json` for structured state data.
+1. Run `~/.claude/compass/scripts/compass-tools.sh status --json` for structured state data.
 2. Read `.compass/config.yaml` for configuration context.
 3. Scan all `.compass/` artifacts.
 
@@ -76,4 +76,4 @@ Stopped at: {from SESSION.md}
 - This is a read-only panorama. No artifacts produced, no state modified.
 - Heavier than `/compass:next` — reads more files for the complete picture.
 - Useful for orientation after a long break or context clear.
-- Run `compass-tools.sh session update` is NOT called — this is read-only.
+- Run `~/.claude/compass/scripts/compass-tools.sh session update` is NOT called — this is read-only.