compass-cc 0.1.3 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/agents/adr-scribe.md +6 -0
- package/agents/architect-coach.md +6 -0
- package/agents/baseline-analyzer.md +6 -0
- package/agents/domain-researcher.md +6 -0
- package/agents/spec-writer.md +6 -0
- package/agents/unit-decomposer.md +6 -0
- package/constitution.md +20 -5
- package/package.json +1 -1
- package/references/inverted-contract.md +1 -1
- package/skills/compass-architect/SKILL.md +2 -2
- package/skills/compass-build-duck/SKILL.md +1 -1
- package/skills/compass-build-idiom/SKILL.md +2 -2
- package/skills/compass-build-progress/SKILL.md +2 -2
- package/skills/compass-build-ready/SKILL.md +2 -2
- package/skills/compass-build-review/SKILL.md +1 -1
- package/skills/compass-build-scope/SKILL.md +4 -4
- package/skills/compass-build-tests/SKILL.md +1 -1
- package/skills/compass-build-transform/SKILL.md +1 -1
- package/skills/compass-build-units/SKILL.md +2 -2
- package/skills/compass-decide/SKILL.md +4 -4
- package/skills/compass-frame/SKILL.md +6 -2
- package/skills/compass-init/SKILL.md +20 -8
- package/skills/compass-next/SKILL.md +3 -3
- package/skills/compass-research/SKILL.md +22 -20
- package/skills/compass-spec/SKILL.md +3 -3
- package/skills/compass-status/SKILL.md +2 -2
- package/templates/config.yaml +3 -0
package/README.md
CHANGED
|
@@ -96,7 +96,7 @@ COMPASS externalizes all state to `.compass/` in the target project:
|
|
|
96
96
|
```
|
|
97
97
|
|
|
98
98
|
State files are the source of truth — not conversation history. All state mutations
|
|
99
|
-
go through
|
|
99
|
+
go through `~/.claude/compass/scripts/compass-tools.sh` (deterministic, no LLM involved).
|
|
100
100
|
|
|
101
101
|
---
|
|
102
102
|
|
package/agents/adr-scribe.md
CHANGED
|
@@ -23,6 +23,12 @@ You are a scribe — a skilled documenter who takes a decision the human articul
|
|
|
23
23
|
and gives it structure, context, and traceability. You ask clarifying questions to
|
|
24
24
|
ensure the ADR is complete. You do not influence the decision itself.
|
|
25
25
|
|
|
26
|
+
## Artifact language
|
|
27
|
+
|
|
28
|
+
Read `language.docs` from `.compass/config.yaml`. Write the ADR in that language.
|
|
29
|
+
If not set, default to English. File names and section headings from templates remain
|
|
30
|
+
in English.
|
|
31
|
+
|
|
26
32
|
## Structural blocks
|
|
27
33
|
|
|
28
34
|
- You MUST NOT make or recommend decisions.
|
|
@@ -26,6 +26,12 @@ You are the senior engineer in the room who has read all the research and asks
|
|
|
26
26
|
the hard questions. You connect proposals to evidence. You surface what was
|
|
27
27
|
overlooked. You test assumptions against reality.
|
|
28
28
|
|
|
29
|
+
## Artifact language
|
|
30
|
+
|
|
31
|
+
Read `language.docs` from `.compass/config.yaml`. Write ARCHITECTURE.md in that language.
|
|
32
|
+
If not set, default to English. File names and section headings from templates remain
|
|
33
|
+
in English.
|
|
34
|
+
|
|
29
35
|
## Structural blocks
|
|
30
36
|
|
|
31
37
|
- You MUST NOT propose architecture. The human proposes; you react.
|
|
@@ -26,6 +26,12 @@ more. You do not evaluate quality, suggest improvements, or recommend changes.
|
|
|
26
26
|
- You MUST NOT write production code.
|
|
27
27
|
- You describe what exists. Factual inventory, not code review.
|
|
28
28
|
|
|
29
|
+
## Artifact language
|
|
30
|
+
|
|
31
|
+
Read `language.docs` from `.compass/config.yaml`. Write the baseline in that language.
|
|
32
|
+
If not set, default to English. File names and section headings from templates remain
|
|
33
|
+
in English.
|
|
34
|
+
|
|
29
35
|
## Process
|
|
30
36
|
|
|
31
37
|
1. **Project structure**: Run `find . -type f | head -200` and `ls -R` (limited depth)
|
|
@@ -21,6 +21,12 @@ You are a research instrument. You find, organize, and present information about
|
|
|
21
21
|
a topic. You do not recommend, advocate, or decide. You present findings with
|
|
22
22
|
trade-offs and let the human draw conclusions.
|
|
23
23
|
|
|
24
|
+
## Artifact language
|
|
25
|
+
|
|
26
|
+
Read `language.docs` from `.compass/config.yaml`. Write the dossier in that language.
|
|
27
|
+
If not set, default to English. File names and section headings from templates remain
|
|
28
|
+
in English.
|
|
29
|
+
|
|
24
30
|
## Structural blocks
|
|
25
31
|
|
|
26
32
|
- You MUST NOT recommend a specific approach, technology, or solution.
|
package/agents/spec-writer.md
CHANGED
|
@@ -28,6 +28,12 @@ scenarios, the failure recovery.
|
|
|
28
28
|
You write the spec document, but the behavioral decisions come from the human.
|
|
29
29
|
You never invent requirements.
|
|
30
30
|
|
|
31
|
+
## Artifact language
|
|
32
|
+
|
|
33
|
+
Read `language.docs` from `.compass/config.yaml`. Write the spec in that language.
|
|
34
|
+
If not set, default to English. File names and section headings from templates remain
|
|
35
|
+
in English.
|
|
36
|
+
|
|
31
37
|
## Structural blocks
|
|
32
38
|
|
|
33
39
|
- You MUST NOT invent requirements or behavior.
|
|
@@ -24,6 +24,12 @@ You are a work breakdown specialist. You take a specification and decompose it
|
|
|
24
24
|
into units small enough to implement in a focused session, with clear boundaries
|
|
25
25
|
and acceptance criteria derived from the spec.
|
|
26
26
|
|
|
27
|
+
## Artifact language
|
|
28
|
+
|
|
29
|
+
Read `language.docs` from `.compass/config.yaml`. Write unit files in that language.
|
|
30
|
+
If not set, default to English. File names and section headings from templates remain
|
|
31
|
+
in English.
|
|
32
|
+
|
|
27
33
|
## Structural blocks
|
|
28
34
|
|
|
29
35
|
- You MUST NOT suggest how to implement any unit.
|
package/constitution.md
CHANGED
|
@@ -93,7 +93,7 @@ All project state lives in files under `.compass/` in the target project.
|
|
|
93
93
|
- Every decision, artifact, and progress marker must be persisted to a file.
|
|
94
94
|
- State files are the authoritative record. If conversation context and files
|
|
95
95
|
disagree, the files are correct.
|
|
96
|
-
- State mutations go through
|
|
96
|
+
- State mutations go through `~/.claude/compass/scripts/compass-tools.sh` — sub-agents must not directly
|
|
97
97
|
edit `SESSION.md`, `config.yaml`, or progress markers.
|
|
98
98
|
|
|
99
99
|
---
|
|
@@ -106,7 +106,7 @@ Each sub-agent invocation is stateless. It loads only the files it needs via exp
|
|
|
106
106
|
- Sub-agents must not assume prior conversation context.
|
|
107
107
|
- Sub-agents must not assume other sub-agents have run unless their artifacts exist
|
|
108
108
|
in `.compass/`.
|
|
109
|
-
- The pre-flight check (
|
|
109
|
+
- The pre-flight check (`~/.claude/compass/scripts/compass-tools.sh preflight`) is the authoritative source
|
|
110
110
|
for whether prerequisites are met.
|
|
111
111
|
|
|
112
112
|
---
|
|
@@ -130,7 +130,7 @@ Nothing advances without the human saying so.
|
|
|
130
130
|
ADRs are mandatory for non-trivial architectural decisions.
|
|
131
131
|
|
|
132
132
|
- Format: MADR (Markdown Any Decision Records).
|
|
133
|
-
- Each ADR lives in its own file, numbered sequentially by
|
|
133
|
+
- Each ADR lives in its own file, numbered sequentially by `~/.claude/compass/scripts/compass-tools.sh adr next-number`.
|
|
134
134
|
- ADRs are linked to requirements in FRAMING.md and, later, to code locations.
|
|
135
135
|
- The scope-guardian checks diffs against active ADRs for contradictions.
|
|
136
136
|
- ADR location is configurable via `config.yaml` (default: `.compass/ADR/`).
|
|
@@ -159,13 +159,28 @@ File existence checks, phase numbering, progress tracking, drift detection setup
|
|
|
159
159
|
ADR numbering, and session state updates are handled by deterministic scripts —
|
|
160
160
|
not by LLM reasoning.
|
|
161
161
|
|
|
162
|
-
-
|
|
162
|
+
- `~/.claude/compass/scripts/compass-tools.sh` is the canonical tool for all bookkeeping operations.
|
|
163
163
|
- Sub-agents call the script for state queries and mutations.
|
|
164
164
|
- The script's output is authoritative over any LLM inference about state.
|
|
165
165
|
|
|
166
166
|
---
|
|
167
167
|
|
|
168
|
-
## Article 10 —
|
|
168
|
+
## Article 10 — Document Language
|
|
169
|
+
|
|
170
|
+
All COMPASS artifacts (FRAMING.md, dossiers, ARCHITECTURE.md, ADRs, SPEC.md, unit
|
|
171
|
+
files, SESSION.md) must be written in the language configured in `language.docs`
|
|
172
|
+
from `config.yaml`.
|
|
173
|
+
|
|
174
|
+
- If `language.docs` is not set, default to English (`en`).
|
|
175
|
+
- File names, phase names, commands, and code identifiers remain in English regardless
|
|
176
|
+
of the configured language.
|
|
177
|
+
- Conversation language is independent — it follows the user's CLAUDE.md or session
|
|
178
|
+
context, not this setting.
|
|
179
|
+
- Sub-agents must read `language.docs` from config before producing any artifact.
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## Article 11 — Six Phases
|
|
169
184
|
|
|
170
185
|
The COMPASS workflow has six phases, executed in order:
|
|
171
186
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "compass-cc",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"description": "COMPASS — Collaborative Orientation, Mapping, Planning, Architecture, Spec & Supervision. An inverted AI coding skill: the human implements, the LLM orients.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "hvpaiva",
|
|
@@ -18,7 +18,7 @@ This reference is loaded by every COMPASS sub-agent. It is non-negotiable.
|
|
|
18
18
|
- Report problems without prescribing code solutions.
|
|
19
19
|
- Respect phase gates — never advance without human approval.
|
|
20
20
|
- Read state from `.compass/` files, not from conversation memory.
|
|
21
|
-
- Call
|
|
21
|
+
- Call `~/.claude/compass/scripts/compass-tools.sh` for state mutations, never edit state files directly.
|
|
22
22
|
|
|
23
23
|
## Mechanical editing exception
|
|
24
24
|
|
|
@@ -11,7 +11,7 @@ document the result.
|
|
|
11
11
|
|
|
12
12
|
## Pre-flight
|
|
13
13
|
|
|
14
|
-
1. Run
|
|
14
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh preflight architect` to verify:
|
|
15
15
|
- `.compass/FRAMING.md` exists
|
|
16
16
|
- `.compass/RESEARCH/` has at least one dossier
|
|
17
17
|
- 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.
|
|
|
82
82
|
|
|
83
83
|
## Closing
|
|
84
84
|
|
|
85
|
-
1. Run
|
|
85
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
|
|
86
86
|
2. Show summary of what was documented.
|
|
87
87
|
3. Note any decisions that surfaced during the architecture session that should
|
|
88
88
|
become formal ADRs.
|
|
@@ -50,4 +50,4 @@ If they mention a specific unit, read that unit file for context.
|
|
|
50
50
|
### Ending the session
|
|
51
51
|
|
|
52
52
|
The human ends the session when they're ready. There is no artifact produced.
|
|
53
|
-
Run
|
|
53
|
+
Run `~/.claude/compass/scripts/compass-tools.sh session update` to note the duck session in SESSION.md.
|
|
@@ -12,7 +12,7 @@ without writing or suggesting specific code.
|
|
|
12
12
|
|
|
13
13
|
## Pre-flight
|
|
14
14
|
|
|
15
|
-
1. Read
|
|
15
|
+
1. Read `~/.claude/compass/scripts/compass-tools.sh config get project.language` to know the target language.
|
|
16
16
|
2. If `$ARGUMENTS` provided, use as target path. Otherwise, ask:
|
|
17
17
|
```
|
|
18
18
|
header: "Target"
|
|
@@ -54,4 +54,4 @@ Agent(
|
|
|
54
54
|
## Post-execution
|
|
55
55
|
|
|
56
56
|
Present findings to the user. No artifacts produced — this is conversational
|
|
57
|
-
feedback. Run
|
|
57
|
+
feedback. Run `~/.claude/compass/scripts/compass-tools.sh session update`.
|
|
@@ -20,7 +20,7 @@ definition at `~/.claude/compass/agents/completion-tracker.md`.
|
|
|
20
20
|
|
|
21
21
|
### Process
|
|
22
22
|
|
|
23
|
-
1. Run
|
|
23
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh progress` to get structured progress data.
|
|
24
24
|
2. Read all unit files from `.compass/UNITS/` for details.
|
|
25
25
|
3. Present a visual summary:
|
|
26
26
|
|
|
@@ -52,4 +52,4 @@ Next available units (no unmet dependencies): unit-006
|
|
|
52
52
|
|
|
53
53
|
## No artifacts produced
|
|
54
54
|
|
|
55
|
-
This is a read-only status view. Run
|
|
55
|
+
This is a read-only status view. Run `~/.claude/compass/scripts/compass-tools.sh session update` after.
|
|
@@ -63,7 +63,7 @@ Agent(
|
|
|
63
63
|
Present the readiness report. If ready, suggest the human begin implementing.
|
|
64
64
|
If not, list specific blockers and how to resolve them.
|
|
65
65
|
|
|
66
|
-
Update the unit status to `in-progress` via
|
|
66
|
+
Update the unit status to `in-progress` via `~/.claude/compass/scripts/compass-tools.sh unit update-status {NNN} in-progress`
|
|
67
67
|
if the human confirms they're starting.
|
|
68
68
|
|
|
69
|
-
Run
|
|
69
|
+
Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
|
|
@@ -14,7 +14,7 @@ from the automatic hook.
|
|
|
14
14
|
|
|
15
15
|
## Pre-flight
|
|
16
16
|
|
|
17
|
-
1. Run
|
|
17
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh preflight build-scope` to verify:
|
|
18
18
|
- `.compass/SPEC.md` (or configured path) exists
|
|
19
19
|
- At least one ADR exists
|
|
20
20
|
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.
|
|
|
28
28
|
|
|
29
29
|
## Execution
|
|
30
30
|
|
|
31
|
-
1. Run
|
|
31
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh drift --json` to get structured diff data.
|
|
32
32
|
If a git ref was provided, run `git diff {ref} -- . ':!.compass/'` first and
|
|
33
|
-
pipe to a temp file, then
|
|
33
|
+
pipe to a temp file, then `~/.claude/compass/scripts/compass-tools.sh drift <tempfile> --json`.
|
|
34
34
|
|
|
35
35
|
2. Spawn the `scope-guardian` agent:
|
|
36
36
|
|
|
@@ -64,4 +64,4 @@ Agent(
|
|
|
64
64
|
|
|
65
65
|
## Post-execution
|
|
66
66
|
|
|
67
|
-
Present the full drift report to the user. Run
|
|
67
|
+
Present the full drift report to the user. Run `~/.claude/compass/scripts/compass-tools.sh session update`.
|
|
@@ -10,7 +10,7 @@ work with clear acceptance criteria, dependencies, and scope.
|
|
|
10
10
|
|
|
11
11
|
## Pre-flight
|
|
12
12
|
|
|
13
|
-
1. Run
|
|
13
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh preflight build-units` to verify:
|
|
14
14
|
- `.compass/SPEC.md` (or configured spec path) exists
|
|
15
15
|
- `.compass/ARCHITECTURE.md` exists
|
|
16
16
|
- If prerequisites missing, inform the user which phases to complete first.
|
|
@@ -70,7 +70,7 @@ Agent(
|
|
|
70
70
|
- Split units that are too large
|
|
71
71
|
- Adjust dependencies
|
|
72
72
|
- Add units that were missed
|
|
73
|
-
3. Run
|
|
73
|
+
3. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
|
|
74
74
|
4. Suggest: "Work units defined. Use `/compass:build-ready` to check readiness
|
|
75
75
|
before starting a unit, or `/compass:build-progress` to see the full board."
|
|
76
76
|
5. Suggest `/clear` before starting implementation.
|
|
@@ -14,11 +14,11 @@ produces one ADR file.
|
|
|
14
14
|
|
|
15
15
|
## Pre-flight
|
|
16
16
|
|
|
17
|
-
1. Run
|
|
17
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh preflight decide` to verify:
|
|
18
18
|
- `.compass/FRAMING.md` exists
|
|
19
19
|
- `.compass/ARCHITECTURE.md` exists (warn if missing but don't block — some
|
|
20
20
|
decisions may precede full architecture)
|
|
21
|
-
2. Read
|
|
21
|
+
2. Read `~/.claude/compass/scripts/compass-tools.sh config get paths.adr` to resolve ADR output directory.
|
|
22
22
|
3. List existing ADRs in the output directory to show context.
|
|
23
23
|
|
|
24
24
|
## Required reading
|
|
@@ -81,7 +81,7 @@ You ARE the adr-scribe for this phase. Read and embody the agent definition at
|
|
|
81
81
|
|
|
82
82
|
## Producing the ADR
|
|
83
83
|
|
|
84
|
-
1. Get the next ADR number: run
|
|
84
|
+
1. Get the next ADR number: run `~/.claude/compass/scripts/compass-tools.sh adr next-number`.
|
|
85
85
|
2. Write the ADR using the template at `~/.claude/compass/templates/ADR.md`.
|
|
86
86
|
3. Place it in the configured ADR directory (from `config.yaml`).
|
|
87
87
|
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`
|
|
|
90
90
|
|
|
91
91
|
## Closing
|
|
92
92
|
|
|
93
|
-
1. Run
|
|
93
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
|
|
94
94
|
2. Show the ADR summary.
|
|
95
95
|
3. Ask:
|
|
96
96
|
```
|
|
@@ -10,7 +10,7 @@ exists, and what constraints shape it.
|
|
|
10
10
|
|
|
11
11
|
## Pre-flight
|
|
12
12
|
|
|
13
|
-
1. Run
|
|
13
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh preflight frame` to verify:
|
|
14
14
|
- `.compass/config.yaml` exists (if not, suggest `/compass:init` first)
|
|
15
15
|
2. Check if `.compass/FRAMING.md` already exists.
|
|
16
16
|
- If yes: inform the user. Ask if they want to revise or start fresh.
|
|
@@ -73,6 +73,10 @@ Read that file now and follow its instructions completely.
|
|
|
73
73
|
|
|
74
74
|
## Producing FRAMING.md
|
|
75
75
|
|
|
76
|
+
Read `language.docs` from `.compass/config.yaml`. Write FRAMING.md in that language.
|
|
77
|
+
If not set, default to English. File names and section headings from templates remain
|
|
78
|
+
in English.
|
|
79
|
+
|
|
76
80
|
Once the user approves the framing, write `.compass/FRAMING.md` using the template
|
|
77
81
|
at `~/.claude/compass/templates/FRAMING.md`.
|
|
78
82
|
|
|
@@ -99,7 +103,7 @@ If yes, collect the principles through conversation. Then append them to
|
|
|
99
103
|
|
|
100
104
|
After FRAMING.md and constitution are written:
|
|
101
105
|
|
|
102
|
-
1. Run
|
|
106
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
|
|
103
107
|
2. Show summary of what was produced.
|
|
104
108
|
3. Suggest: "Framing complete. Next step: `/compass:research` to investigate domain topics."
|
|
105
109
|
4. Suggest `/clear` before the next phase.
|
|
@@ -63,7 +63,19 @@ question: "Primary project language?"
|
|
|
63
63
|
options: [detected language first, then: "Rust", "Go", "Python", "TypeScript", "Shell"]
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
### Question 2 —
|
|
66
|
+
### Question 2 — Document language
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
header: "Docs lang"
|
|
70
|
+
question: "What language should COMPASS artifacts be written in?"
|
|
71
|
+
options: [
|
|
72
|
+
"English (Recommended)",
|
|
73
|
+
"Português brasileiro",
|
|
74
|
+
"Español"
|
|
75
|
+
]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Question 3 — ADR location
|
|
67
79
|
|
|
68
80
|
```
|
|
69
81
|
header: "ADRs"
|
|
@@ -71,7 +83,7 @@ question: "Where should Architectural Decision Records be stored?"
|
|
|
71
83
|
options: [".compass/ADR/", "docs/adrs/", "docs/decisions/"]
|
|
72
84
|
```
|
|
73
85
|
|
|
74
|
-
### Question
|
|
86
|
+
### Question 4 — Spec location
|
|
75
87
|
|
|
76
88
|
```
|
|
77
89
|
header: "Spec"
|
|
@@ -79,7 +91,7 @@ question: "Where should the specification document live?"
|
|
|
79
91
|
options: [".compass/SPEC.md", "docs/spec.md"]
|
|
80
92
|
```
|
|
81
93
|
|
|
82
|
-
### Question
|
|
94
|
+
### Question 5 — Socratic intensity
|
|
83
95
|
|
|
84
96
|
```
|
|
85
97
|
header: "Style"
|
|
@@ -91,7 +103,7 @@ options: [
|
|
|
91
103
|
]
|
|
92
104
|
```
|
|
93
105
|
|
|
94
|
-
### Question
|
|
106
|
+
### Question 6 — Scope guardian
|
|
95
107
|
|
|
96
108
|
```
|
|
97
109
|
header: "Guardian"
|
|
@@ -99,7 +111,7 @@ question: "Enable automatic scope guardian during build phase?"
|
|
|
99
111
|
options: ["Yes — detect drift automatically on every file edit", "No — I will invoke it manually"]
|
|
100
112
|
```
|
|
101
113
|
|
|
102
|
-
### Question
|
|
114
|
+
### Question 7 — Conventional commits
|
|
103
115
|
|
|
104
116
|
```
|
|
105
117
|
header: "Commits"
|
|
@@ -107,7 +119,7 @@ question: "Validate conventional commit format?"
|
|
|
107
119
|
options: ["Yes — block non-conventional commits", "No — do not enforce"]
|
|
108
120
|
```
|
|
109
121
|
|
|
110
|
-
### Question
|
|
122
|
+
### Question 8 — Git tracking
|
|
111
123
|
|
|
112
124
|
```
|
|
113
125
|
header: "Git"
|
|
@@ -117,7 +129,7 @@ options: ["Yes — version all COMPASS artifacts", "No — add .compass/ to .git
|
|
|
117
129
|
|
|
118
130
|
## Step 4 — Scaffold .compass/ directory
|
|
119
131
|
|
|
120
|
-
Run
|
|
132
|
+
Run `~/.claude/compass/scripts/compass-tools.sh init <project-root>` with the resolved config values.
|
|
121
133
|
|
|
122
134
|
This creates:
|
|
123
135
|
```
|
|
@@ -133,7 +145,7 @@ This creates:
|
|
|
133
145
|
|
|
134
146
|
## Step 5 — Confirm and suggest next step
|
|
135
147
|
|
|
136
|
-
1. Run
|
|
148
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
|
|
137
149
|
2. Show the user:
|
|
138
150
|
- Summary of configuration choices
|
|
139
151
|
- Directory structure created
|
|
@@ -10,7 +10,7 @@ where they are and what the logical next step is.
|
|
|
10
10
|
|
|
11
11
|
## Execution
|
|
12
12
|
|
|
13
|
-
1. Run
|
|
13
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh status --json` to get full project state.
|
|
14
14
|
2. If the command fails (no `.compass/` found), suggest: "No COMPASS project
|
|
15
15
|
found. Run `/compass:init` to get started."
|
|
16
16
|
|
|
@@ -55,6 +55,6 @@ where they are and what the logical next step is.
|
|
|
55
55
|
## Design notes
|
|
56
56
|
|
|
57
57
|
- This command must be FAST. Minimal reading, no spawning, no heavy analysis.
|
|
58
|
-
- It reads state from files and
|
|
58
|
+
- It reads state from files and `~/.claude/compass/scripts/compass-tools.sh` — never from conversation memory.
|
|
59
59
|
- It works perfectly after a `/clear` because it depends only on `.compass/` files.
|
|
60
|
-
- Run
|
|
60
|
+
- Run `~/.claude/compass/scripts/compass-tools.sh session update` is NOT called — this is read-only.
|
|
@@ -13,14 +13,18 @@ one dossier in `.compass/RESEARCH/`.
|
|
|
13
13
|
|
|
14
14
|
## Pre-flight
|
|
15
15
|
|
|
16
|
-
1. Run
|
|
16
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh preflight research` to verify:
|
|
17
17
|
- `.compass/FRAMING.md` exists (if not, suggest `/compass:frame` first)
|
|
18
|
-
2. If no `$ARGUMENTS` (topic) provided,
|
|
18
|
+
2. If no `$ARGUMENTS` (topic) provided, use AskUserQuestion with **multiSelect: true**
|
|
19
|
+
to let the user pick one or more topics at once:
|
|
19
20
|
```
|
|
20
|
-
header: "
|
|
21
|
-
question: "
|
|
22
|
-
|
|
21
|
+
header: "Topics"
|
|
22
|
+
question: "Which topics do you want to research?"
|
|
23
|
+
multiSelect: true
|
|
24
|
+
options: [derive 2-4 topics from FRAMING.md gaps, risks, and unknowns]
|
|
23
25
|
```
|
|
26
|
+
The user can also type a custom topic via the "Other" option.
|
|
27
|
+
Run one research agent per selected topic (in parallel when possible).
|
|
24
28
|
|
|
25
29
|
## Required reading
|
|
26
30
|
|
|
@@ -34,7 +38,11 @@ Load before proceeding:
|
|
|
34
38
|
|
|
35
39
|
## Execution
|
|
36
40
|
|
|
37
|
-
|
|
41
|
+
For **each** selected topic, spawn a `domain-researcher` agent. When there are multiple
|
|
42
|
+
topics, launch all agents **in parallel** (one Agent tool call per topic in the same message).
|
|
43
|
+
|
|
44
|
+
Pre-assign dossier numbers sequentially before spawning (e.g., if the next number is 003
|
|
45
|
+
and the user picked 3 topics, assign 003, 004, 005) to avoid race conditions.
|
|
38
46
|
|
|
39
47
|
```
|
|
40
48
|
Agent(
|
|
@@ -55,7 +63,7 @@ Agent(
|
|
|
55
63
|
Project context: [summarize FRAMING.md key points — mission, scope, constraints]
|
|
56
64
|
|
|
57
65
|
Produce a research dossier at: .compass/RESEARCH/dossier-{NNN}-{slug}.md
|
|
58
|
-
|
|
66
|
+
(your assigned number is {NNN} — do not change it).
|
|
59
67
|
|
|
60
68
|
Use the template at ~/.claude/compass/templates/RESEARCH-DOSSIER.md for structure.
|
|
61
69
|
|
|
@@ -65,17 +73,11 @@ Agent(
|
|
|
65
73
|
|
|
66
74
|
## Post-execution
|
|
67
75
|
|
|
68
|
-
1. Read
|
|
69
|
-
2. Run
|
|
70
|
-
3. Ask the user:
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
"Research another topic",
|
|
76
|
-
"Review/revise this dossier",
|
|
77
|
-
"Move to architecture — /compass:architect",
|
|
78
|
-
"Check status — /compass:status"
|
|
79
|
-
]
|
|
80
|
-
```
|
|
76
|
+
1. Read all produced dossiers and present a summary of each to the user.
|
|
77
|
+
2. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
|
|
78
|
+
3. Ask the user what to do next (as a regular text message, not AskUserQuestion):
|
|
79
|
+
- Research another topic
|
|
80
|
+
- Review/revise a dossier
|
|
81
|
+
- Move to architecture — `/compass:architect`
|
|
82
|
+
- Check status — `/compass:status`
|
|
81
83
|
4. Suggest `/clear` before starting a new phase.
|
|
@@ -11,12 +11,12 @@ invariants, boundary conditions.
|
|
|
11
11
|
|
|
12
12
|
## Pre-flight
|
|
13
13
|
|
|
14
|
-
1. Run
|
|
14
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh preflight spec` to verify:
|
|
15
15
|
- `.compass/FRAMING.md` exists
|
|
16
16
|
- `.compass/ARCHITECTURE.md` exists
|
|
17
17
|
- At least one ADR exists in the configured ADR directory
|
|
18
18
|
- If prerequisites missing, inform the user which phases to complete first.
|
|
19
|
-
2. Read
|
|
19
|
+
2. Read `~/.claude/compass/scripts/compass-tools.sh config get paths.spec` to resolve spec output path.
|
|
20
20
|
3. Check if spec file already exists.
|
|
21
21
|
- If yes: inform the user. Ask if they want to revise, extend, or start fresh.
|
|
22
22
|
|
|
@@ -107,7 +107,7 @@ spec is reviewed at the end before finalizing.
|
|
|
107
107
|
|
|
108
108
|
## Closing
|
|
109
109
|
|
|
110
|
-
1. Run
|
|
110
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh session update` to record progress.
|
|
111
111
|
2. Show summary: number of modules specified, total behaviors, total acceptance
|
|
112
112
|
criteria.
|
|
113
113
|
3. Suggest: "Specification complete. Next step: `/compass:build-units` to
|
|
@@ -10,7 +10,7 @@ every artifact, and (in build phase) every work unit.
|
|
|
10
10
|
|
|
11
11
|
## Execution
|
|
12
12
|
|
|
13
|
-
1. Run
|
|
13
|
+
1. Run `~/.claude/compass/scripts/compass-tools.sh status --json` for structured state data.
|
|
14
14
|
2. Read `.compass/config.yaml` for configuration context.
|
|
15
15
|
3. Scan all `.compass/` artifacts.
|
|
16
16
|
|
|
@@ -76,4 +76,4 @@ Stopped at: {from SESSION.md}
|
|
|
76
76
|
- This is a read-only panorama. No artifacts produced, no state modified.
|
|
77
77
|
- Heavier than `/compass:next` — reads more files for the complete picture.
|
|
78
78
|
- Useful for orientation after a long break or context clear.
|
|
79
|
-
- Run
|
|
79
|
+
- Run `~/.claude/compass/scripts/compass-tools.sh session update` is NOT called — this is read-only.
|