compass-st 1.1.2 → 1.1.3
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 +135 -54
- package/VERSION +1 -1
- package/cli/Cargo.lock +1 -1
- package/cli/Cargo.toml +1 -1
- package/cli/src/cmd/version.rs +2 -2
- package/core/colleagues/manifest.json +1 -1
- package/core/manifest.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,26 @@
|
|
|
1
1
|
# Compass
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/compass-st)
|
|
4
|
+
[](https://www.npmjs.com/package/compass-st)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[]()
|
|
7
|
+
[](https://nodejs.org)
|
|
4
8
|
|
|
5
|
-
|
|
9
|
+
> AI command library for Product Owners & Product Managers.
|
|
10
|
+
> Brief what you need — Compass drafts PRDs, epics, and stories with parallel AI Colleagues.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Why Compass
|
|
15
|
+
|
|
16
|
+
Writing product documentation — PRDs, epics, user stories — is mechanical work that blocks the interesting decisions. Compass hands that work to AI Colleagues with opinionated workflows, Silver-Tiger-style folder structure, and a project registry that survives every new session and IDE restart.
|
|
17
|
+
|
|
18
|
+
- **One brief → full deliverables.** `/compass:brief "2FA for login"` → research + PRD + stories, in parallel.
|
|
19
|
+
- **Session-proof.** Switch IDEs, close your laptop, change shells — `compass-cli project resolve` always knows which project you're on.
|
|
20
|
+
- **Validator gate.** `compass-cli validate prd` blocks delivery on bad flows or dangling cross-references.
|
|
21
|
+
- **Silver Tiger domains.** `ard`, `platform`, `communication`, `internal`, `access`, `ai` — built-in; drop config into `CLAUDE.md` and every PO workflow inherits the domain context.
|
|
22
|
+
|
|
23
|
+
---
|
|
6
24
|
|
|
7
25
|
## Install
|
|
8
26
|
|
|
@@ -10,96 +28,159 @@ Tell Compass what you need — it figures out the rest.
|
|
|
10
28
|
npx compass-st
|
|
11
29
|
```
|
|
12
30
|
|
|
13
|
-
Or
|
|
31
|
+
Or, if `npx` is rate-limited:
|
|
14
32
|
|
|
15
33
|
```bash
|
|
16
34
|
curl -fsSL https://raw.githubusercontent.com/mrmandovn/compass/main/bootstrap.sh | bash
|
|
17
35
|
```
|
|
18
36
|
|
|
19
|
-
|
|
37
|
+
**Requires:** macOS or Linux, Node ≥ 16. Rust toolchain is optional — without it the markdown workflows still work; with it you also get the `compass-cli` binary (validators, project registry, memory).
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Quick start
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
/compass:init # first-time: global prefs, then create project
|
|
45
|
+
/compass:brief "add 2FA" # kick off the full PO pipeline
|
|
46
|
+
/compass:plan # review the DAG
|
|
47
|
+
/compass:run # Colleagues execute in parallel
|
|
48
|
+
/compass:check # validate + deliver to Jira / Confluence
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`/compass:project list` shows every registered project; `/compass:project use <path>` switches the active one. Commands run from **any cwd** — the active project is remembered in `~/.compass/projects.json`.
|
|
52
|
+
|
|
53
|
+
---
|
|
20
54
|
|
|
21
|
-
##
|
|
55
|
+
## Pipeline
|
|
22
56
|
|
|
23
57
|
```
|
|
24
|
-
|
|
25
|
-
|
|
58
|
+
┌──────────┐ ┌────────┐ ┌───────┐ ┌────────┐
|
|
59
|
+
│ brief │ → │ plan │ → │ run │ → │ check │
|
|
60
|
+
└──────────┘ └────────┘ └───────┘ └────────┘
|
|
61
|
+
│ │ │ │
|
|
62
|
+
clarify + DAG of wave wave-by-wave validator
|
|
63
|
+
Colleague + budget parallel + deliver
|
|
64
|
+
selection Colleagues
|
|
26
65
|
```
|
|
27
66
|
|
|
28
|
-
|
|
67
|
+
Each Colleague runs in a fresh context with a strict `context_pointers` file list — no context rot, no scope creep.
|
|
29
68
|
|
|
30
|
-
|
|
31
|
-
2. `/compass:plan` — Review the execution plan
|
|
32
|
-
3. `/compass:run` — Colleagues work in parallel
|
|
33
|
-
4. `/compass:check` — Validate and deliver
|
|
69
|
+
---
|
|
34
70
|
|
|
35
71
|
## Commands
|
|
36
72
|
|
|
37
|
-
###
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
|
49
|
-
|
|
50
|
-
| `
|
|
51
|
-
| `
|
|
73
|
+
### Pipeline
|
|
74
|
+
|
|
75
|
+
| Command | Action |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `brief <task>` | Clarify scope, pick Colleagues, write session context |
|
|
78
|
+
| `plan` | Emit `plan.json` DAG with budgets and dependencies |
|
|
79
|
+
| `run` | Execute wave-by-wave with parallel Colleagues |
|
|
80
|
+
| `check` | Validate outputs, deliver to integrations |
|
|
81
|
+
|
|
82
|
+
### Artifacts
|
|
83
|
+
|
|
84
|
+
| Command | Action |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `prd` | Write a PRD following the 11-section template |
|
|
87
|
+
| `story` | User Stories + AC in Given/When/Then |
|
|
88
|
+
| `epic` | Scaffold an epic folder + `user-stories/` + `tasks/` |
|
|
89
|
+
| `research` | Competitive / market / user / tech research |
|
|
90
|
+
| `ideate` | Brainstorm 5–10 feature ideas |
|
|
52
91
|
| `prioritize` | Score backlog (RICE / MoSCoW / Kano) |
|
|
53
|
-
| `prototype` | UI prototype
|
|
54
|
-
| `
|
|
55
|
-
| `feedback` | Quick feedback collection |
|
|
56
|
-
| `roadmap` | Product roadmap with gantt |
|
|
92
|
+
| `prototype` | UI prototype via Figma integration |
|
|
93
|
+
| `roadmap` | Product roadmap with Gantt |
|
|
57
94
|
| `sprint` | Sprint planning by capacity |
|
|
58
95
|
| `release` | Generate release notes |
|
|
59
|
-
| `
|
|
60
|
-
|
|
96
|
+
| `feedback` | Structured user-feedback rollup |
|
|
97
|
+
|
|
98
|
+
### Project + setup
|
|
61
99
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
| `
|
|
66
|
-
| `setup` |
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
100
|
+
| Command | Action |
|
|
101
|
+
|---|---|
|
|
102
|
+
| `init` | First-time global wizard → create project → update config |
|
|
103
|
+
| `project list\|use <path>` | Inspect or switch the active project |
|
|
104
|
+
| `setup` | Configure Jira / Figma / Confluence / Vercel |
|
|
105
|
+
| `status` | Session + project health |
|
|
106
|
+
| `migrate` | Migrate v0.x state to v1.0 (idempotent) |
|
|
107
|
+
| `update` / `help` / `undo` | Self-update, help, restore previous artifact |
|
|
108
|
+
|
|
109
|
+
---
|
|
69
110
|
|
|
70
111
|
## AI Colleagues
|
|
71
112
|
|
|
72
113
|
| Colleague | Role |
|
|
73
|
-
|
|
74
|
-
| Research Aggregator | User feedback, competitive intel |
|
|
75
|
-
| Market Analyst | Market sizing,
|
|
76
|
-
| Product Writer |
|
|
77
|
-
| Story Breaker |
|
|
78
|
-
| Prioritizer | Score backlog |
|
|
79
|
-
| Consistency Reviewer | Cross-doc validation |
|
|
80
|
-
| UX Reviewer | User flows, UX consistency |
|
|
81
|
-
| Stakeholder Communicator | Executive summaries |
|
|
114
|
+
|---|---|
|
|
115
|
+
| Research Aggregator | User feedback, competitive intel, tech eval |
|
|
116
|
+
| Market Analyst | Market sizing, competitor landscape |
|
|
117
|
+
| Product Writer | PRD author — follows the 11-section template exactly |
|
|
118
|
+
| Story Breaker | PRD → user stories with AC |
|
|
119
|
+
| Backlog Prioritizer | Score and rank backlog |
|
|
120
|
+
| Consistency Reviewer | Cross-doc validation, TBD hunt |
|
|
121
|
+
| UX Reviewer | User flows, UX consistency, accessibility |
|
|
122
|
+
| Stakeholder Communicator | Executive summaries, release notes |
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## Architecture highlights (v1.1.x)
|
|
127
|
+
|
|
128
|
+
- **Global project registry** at `~/.compass/projects.json` — every workflow resolves via `compass-cli project resolve`; no more "No compass config found" on fresh sessions.
|
|
129
|
+
- **Per-task `context_pointers`** in `plan.json` — strict file scope per Colleague, enforced by validator.
|
|
130
|
+
- **PRD taste rules** `R-FLOW` (ordered numeric lists in User Flows) + `R-XREF` (every `[LINK-…]` resolves) — block delivery on bad specs.
|
|
131
|
+
- **Durable project memory** `.compass/.state/project-memory.json` — FIFO 10 sessions with aggregate preservation across rotation.
|
|
132
|
+
- **Silver Tiger domains** — `ard | platform | communication | internal | access | ai` written directly into `CLAUDE.md`, so Claude Code auto-loads domain context every turn.
|
|
133
|
+
- **Owner-only perms** on `~/.compass/` (0o700) — registry + global config protected on shared hosts.
|
|
134
|
+
|
|
135
|
+
---
|
|
82
136
|
|
|
83
137
|
## Compatibility
|
|
84
138
|
|
|
85
|
-
|
|
139
|
+
Commands live in `~/.claude/commands/compass/`, which both Claude Code and OpenCode read. Install also symlinks `compass-cli` into a PATH directory (prefers `~/.local/bin`, falls back to `/usr/local/bin` or `/opt/homebrew/bin`).
|
|
86
140
|
|
|
87
|
-
|
|
141
|
+
For other AI hosts, paste a workflow directly:
|
|
88
142
|
|
|
89
|
-
|
|
143
|
+
```bash
|
|
144
|
+
cat ~/.compass/core/workflows/brief.md
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Tested with Claude Opus/Sonnet, GPT-4, Gemini, GLM, DeepSeek, Qwen.
|
|
148
|
+
|
|
149
|
+
---
|
|
90
150
|
|
|
91
151
|
## Update
|
|
92
152
|
|
|
93
153
|
```bash
|
|
94
154
|
cd ~/.compass && git fetch origin main && git reset --hard origin/main
|
|
155
|
+
./bin/install
|
|
95
156
|
```
|
|
96
157
|
|
|
158
|
+
`bootstrap.sh` preserves `~/.compass/projects.json` + `~/.compass/global-config.json` across any reset.
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
97
162
|
## Uninstall
|
|
98
163
|
|
|
99
164
|
```bash
|
|
100
|
-
|
|
165
|
+
npx compass-st --uninstall # removes commands, keeps ~/.compass/ source
|
|
166
|
+
rm -rf ~/.compass # remove everything (and user-level state)
|
|
101
167
|
```
|
|
102
168
|
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## Contributing
|
|
172
|
+
|
|
173
|
+
Bug reports + pull requests welcome at [mrmandovn/compass](https://github.com/mrmandovn/compass/issues).
|
|
174
|
+
|
|
175
|
+
Development:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
git clone https://github.com/mrmandovn/compass.git ~/.compass
|
|
179
|
+
cd ~/.compass/cli && cargo build --release && cargo test
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
103
184
|
## License
|
|
104
185
|
|
|
105
|
-
MIT
|
|
186
|
+
[MIT](LICENSE) © Mando
|
package/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
1.1.
|
|
1
|
+
1.1.3
|
package/cli/Cargo.lock
CHANGED
package/cli/Cargo.toml
CHANGED
package/cli/src/cmd/version.rs
CHANGED
|
@@ -81,8 +81,8 @@ mod tests {
|
|
|
81
81
|
// a partial bump (e.g. VERSION updated but Cargo.toml not)
|
|
82
82
|
// even if all sources agree on the wrong value.
|
|
83
83
|
assert_eq!(
|
|
84
|
-
version_txt, "1.1.
|
|
85
|
-
"expected VERSION to be 1.1.
|
|
84
|
+
version_txt, "1.1.3",
|
|
85
|
+
"expected VERSION to be 1.1.3; got {}",
|
|
86
86
|
version_txt
|
|
87
87
|
);
|
|
88
88
|
}
|
package/core/manifest.json
CHANGED