parallax-opencode 0.3.9 → 0.3.10

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.
Files changed (2) hide show
  1. package/README.md +264 -260
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,260 +1,264 @@
1
- [![Parallax Banner](https://capsule-render.vercel.app/api?type=waving&height=200&color=6c63ff&desc=PARALLAX%20ENGINE&descAlignY=65&fontColor=ffffff&section=header&reversal=true&textBg=false&animation=fadeIn)](https://github.com/Master0fFate/parallax-opencode)
2
-
3
- # PARALLAX ENGINE
4
-
5
- **The first AI coding assistant that shows its work.**
6
-
7
- [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
8
- [![OpenCode](https://img.shields.io/badge/OpenCode-plugin-6c63ff)](https://opencode.ai)
9
- [![npm](https://img.shields.io/npm/v/parallax-opencode)](https://www.npmjs.com/package/parallax-opencode)
10
- [![Tests](https://img.shields.io/badge/tests-30%20passing-brightgreen)]()
11
- [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)]()
12
-
13
- ---
14
-
15
- ## Quick Install
16
-
17
- ```bash
18
- npx parallax-opencode
19
- ```
20
-
21
- After install, restart OpenCode and press **Tab** to cycle to the Parallax agent.
22
-
23
- ---
24
-
25
- ## What Makes Parallax Different
26
-
27
- Every AI coding tool gives you code. None of them show you **how they got there**.
28
-
29
- Parallax captures the complete reasoning trace of every session -- the ambiguity assessment, the invariants analysis, every verification result, every decision -- and makes it visible, exportable, and replayable.
30
-
31
- > "Here is my complete reasoning trace. Review it. Score it. Compare it. See for yourself."
32
-
33
- ### The 4 Invariants
34
-
35
- | Question | Why It Matters |
36
- |---|---|
37
- | Where does state live? | Ownership & truth, consistency, blast radius |
38
- | Where does feedback live? | Observability, debugging, monitoring |
39
- | What breaks if I delete this? | Coupling & fragility, safe refactoring |
40
- | When does timing matter? | Async & ordering, race conditions, correctness |
41
-
42
- Based on [@acidgreenservers AGENTS.md](https://gist.github.com/acidgreenservers/001185d63e5cd65f9fbe6f7a1c70a200)
43
-
44
- ### The Coherence Score
45
-
46
- After every session, Parallax computes an evidence-based quality score (0-100):
47
-
48
- - **Protocol Coverage (30%)** -- Were all 6 protocol phases completed?
49
- - **Verification Integrity (35%)** -- Pass rate on first attempt?
50
- - **Edge Case Coverage (20%)** -- How many edge categories were analyzed?
51
- - **Timing Discipline (15%)** -- Were phases in correct order?
52
-
53
- Track scores over time:
54
-
55
- ```bash
56
- parallax trace trend
57
- parallax trace report --week
58
- ```
59
-
60
- ### Trace in Your PR
61
-
62
- The AI calls `parallax_trace_pr_comment` at session end and outputs a formatted markdown block directly in the chat. Copy it into your PR. No terminal needed.
63
-
64
- ### CI/CD Gate
65
-
66
- ```yaml
67
- - name: Parallax Gate
68
- run: parallax gate --min-score 70
69
- ```
70
-
71
- Pre-commit hook:
72
- ```bash
73
- echo 'parallax pre-commit' >> .git/hooks/pre-commit
74
- ```
75
-
76
- ---
77
-
78
- ## Comparison
79
-
80
- | Feature | Plain OpenCode | Cursor | Copilot | Parallax |
81
- |---|---|---|---|---|
82
- | Structured reasoning trace | No | No | No | **Yes** |
83
- | Trace as PR comment (inline) | No | No | No | **Yes** |
84
- | Evidence-based quality score | No | No | No | **Yes** |
85
- | Protocol enforcement (6 steps) | No | No | No | **Yes** |
86
- | Mode switching (plan/build/debug) | No | No | No | **Yes** |
87
- | CI coherence gate | No | No | No | **Yes** |
88
- | Session retrospective | No | No | No | **Yes** |
89
- | Design doc enforcement | No | No | No | **Yes** |
90
- | Multi-agent state sharing | No | No | No | **Yes** |
91
- | Shell env injection | No | No | No | **Yes** |
92
- | Trace analytics | No | No | No | **Yes** |
93
-
94
- ---
95
-
96
- ## Architecture
97
-
98
- ```
99
- Parallax Agent (system prompt)
100
- |
101
- +-- Plugin hooks (8)
102
- | event --> session ID + agent switches
103
- | tool.execute.before --> protocol enforcement + friction + design doc gate
104
- | tool.execute.after --> auto-verify + trace recording + state persistence
105
- | experimental.chat.system.transform --> protocol status + mode skill + agent context
106
- | experimental.session.compacting --> state preservation + trace export
107
- | shell.env --> PARALLAX_MODE, PARALLAX_SESSION_ID in shell
108
- |
109
- +-- Custom tools (9)
110
- | parallax_verify auto-verify after writes
111
- | parallax_analyze multi-perspective analysis
112
- | parallax_checkin protocol step checkin (6 steps incl. design)
113
- | parallax_plan / _build / _debug mode switching
114
- | parallax_trace_export export session trace to JSON file
115
- | parallax_trace_pr_comment generate trace as PR-ready markdown
116
- | parallax_trace_view show full reasoning trace inline in chat
117
- |
118
- +-- State files
119
- | .parallax/state.json written on every transition (debounced)
120
- | .parallax/traces/ per-session JSON trace files
121
- | .parallax/scores.jsonl append-only score history
122
- | .parallax/config.json per-project config (optional)
123
- |
124
- +-- CLI (parallax) -- 11 commands
125
- init | trace list/show/score/export/trend/report/compare/compliance
126
- gate --min-score <n> | pre-commit
127
- ```
128
-
129
- ### Three Modes
130
-
131
- | Mode | Tool | When |
132
- |---|---|---|
133
- | **PLAN** | `parallax_plan` | Vague requirements, before writing code |
134
- | **BUILD** | `parallax_build` | Executing, writing code (default) |
135
- | **DEBUG** | `parallax_debug` | Post-build quality and security audit |
136
-
137
- ### Six Protocol Steps
138
-
139
- | Step | Checkin | Enforced |
140
- |---|---|---|
141
- | 1. Ambiguity Check | `parallax_checkin("ambiguity")` | Blocks all writes until done |
142
- | 2. 4 Invariants | `parallax_checkin("invariants")` | Warns after 3 writes without checkin |
143
- | 3. Verification Gate | `parallax_checkin("gate")` | Requires invariants first |
144
- | 4. Design Doc *(opt-in)* | `parallax_checkin("design")` | Per project via config |
145
- | 5. Commit Decision | `parallax_checkin("commit")` | Any time after gate |
146
- | 6. Summary | `parallax_checkin("summary")` | Generates retrospective |
147
-
148
- ---
149
-
150
- ## Project Config (.parallax/config.json)
151
-
152
- ```json
153
- {
154
- "strictness": "standard",
155
- "minScore": 70,
156
- "adaptiveProtocol": false,
157
- "designDocRequired": false,
158
- "trivialPatterns": ["*.md", "*.json"],
159
- "highRiskPatterns": ["**/auth/**", "**/*.env*"]
160
- }
161
- ```
162
-
163
- | Key | Default | Description |
164
- |---|---|---|
165
- | `strictness` | `"standard"` | `"strict"` / `"standard"` / `"relaxed"` |
166
- | `minScore` | `70` | Gate threshold for CI |
167
- | `adaptiveProtocol` | `false` | Auto-skip gate steps for trivial changes |
168
- | `designDocRequired` | `false` | Block writes until design doc produced |
169
- | `trivialPatterns` | `[]` | File patterns considered low-risk |
170
- | `highRiskPatterns` | `[]` | Patterns always requiring full protocol |
171
-
172
- ---
173
-
174
- ## Manual Install
175
-
176
- ```bash
177
- cp dist-standalone/parallax-engine.js ~/.config/opencode/plugins/
178
- cp agents/parallax.md ~/.config/opencode/agents/
179
- cp -r skills/parallax ~/.config/opencode/skills/
180
- cp -r skills/parallax-plan ~/.config/opencode/skills/
181
- cp -r skills/parallax-debug ~/.config/opencode/skills/
182
- cd ~/.config/opencode && npm init -y && npm install @opencode-ai/plugin
183
- ```
184
-
185
- ---
186
-
187
- ## Project Status
188
-
189
- **v0.3.0** -- Trace Protocol + Protocol Intelligence + Analytics
190
-
191
- | Phase | Status | What |
192
- |---|---|---|
193
- | 1: Trace Artifact | Complete | PR comments, inline viewer, CI gate, pre-commit |
194
- | 2: Protocol Intelligence | Complete | State persistence, retrospective, multi-agent sharing, shell env, design doc |
195
- | 3: Developer Experience | Partial | Config system, design doc gate. Adaptive protocol deferred |
196
- | 4: TUI Integration | Planned | Sidebar protocol status widget |
197
- | 5: Analytics | Complete | Weekly reports, trace comparison, compliance reports |
198
-
199
- See [ROADMAP.md](ROADMAP.md) for the full strategic plan.
200
-
201
- ---
202
-
203
- ## Commands
204
-
205
- ### Plugin Tools (AI calls in OpenCode chat)
206
-
207
- ```
208
- parallax_verify Run project verification
209
- parallax_analyze {topic} Multi-perspective analysis
210
- parallax_checkin {step} Protocol step (ambiguity/invariants/gate/design/commit/summary)
211
- parallax_plan / _build / _debug Mode switching
212
- parallax_trace_export Export session trace to JSON
213
- parallax_trace_pr_comment Generate trace as PR-ready markdown
214
- parallax_trace_view Show reasoning trace inline in chat
215
- ```
216
-
217
- ### CLI (for CI and analytics)
218
-
219
- ```
220
- parallax init Create .parallax/ directory
221
- parallax trace list List all traces
222
- parallax trace show <id> Show trace details
223
- parallax trace score <id> Show coherence score breakdown
224
- parallax trace export <id> Export trace as pretty JSON
225
- parallax trace trend Show score trend over time
226
- parallax trace report --week Weekly analytics report
227
- parallax trace compare <a> <b> Side-by-side trace comparison
228
- parallax trace compliance <id> Protocol compliance report
229
- parallax gate --min-score <n> CI coherence gate
230
- parallax pre-commit Git pre-commit hook wrapper
231
- ```
232
-
233
- ---
234
-
235
- ## Files
236
-
237
- ```
238
- parallax_plugin/
239
- agents/parallax.md # Primary agent definition
240
- src/plugin.ts # Canonical plugin (TypeScript, 900+ lines)
241
- src/types.ts # Shared type definitions
242
- src/detect.ts # Project detection
243
- src/trace.ts # Trace recording and export
244
- src/score.ts # Coherence score + analytics
245
- src/cli.ts # CLI entry point (11 commands)
246
- src/tests/ # 30 tests across 5 files
247
- dist/ # Compiled output
248
- dist-standalone/ # Standalone bundled plugin (34KB)
249
- skills/ # Protocol skills
250
- scripts/ # Install and publish scripts
251
- .parallax/ # Runtime state + traces + scores
252
- ROADMAP.md # Strategic roadmap
253
- CHANGELOG.md # Version history
254
- ```
255
-
256
- ---
257
-
258
- ## License
259
-
260
- MIT (c) [@Master0fFate](https://github.com/Master0fFate)
1
+ [![Parallax Banner](https://capsule-render.vercel.app/api?type=waving&height=200&color=6c63ff&desc=PARALLAX%20ENGINE&descAlignY=65&fontColor=ffffff&section=header&reversal=true&textBg=false&animation=fadeIn)](https://github.com/Master0fFate/parallax-opencode)
2
+
3
+ # PARALLAX ENGINE
4
+
5
+ **The first AI coding assistant that shows its work.**
6
+
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
8
+ [![OpenCode](https://img.shields.io/badge/OpenCode-plugin-6c63ff)](https://opencode.ai)
9
+ [![npm](https://img.shields.io/npm/v/parallax-opencode)](https://www.npmjs.com/package/parallax-opencode)
10
+ [![Tests](https://img.shields.io/badge/tests-30%20passing-brightgreen)]()
11
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)]()
12
+
13
+ ---
14
+
15
+ ## Quick Install
16
+
17
+ ```bash
18
+ npx parallax-opencode
19
+ ```
20
+
21
+ After install, restart OpenCode and press **Tab** to cycle to the Parallax agent.
22
+
23
+ ---
24
+
25
+ ## What Makes Parallax Different
26
+
27
+ Every AI coding tool gives you code. None of them show you **how they got there**.
28
+
29
+ Parallax captures the complete reasoning trace of every session -- the ambiguity assessment, the invariants analysis, every verification result, every decision -- and makes it visible, exportable, and replayable.
30
+
31
+ > "Here is my complete reasoning trace. Review it. Score it. Compare it. See for yourself."
32
+
33
+ ### The 4 Invariants
34
+
35
+ | Question | Why It Matters |
36
+ |---|---|
37
+ | Where does state live? | Ownership & truth, consistency, blast radius |
38
+ | Where does feedback live? | Observability, debugging, monitoring |
39
+ | What breaks if I delete this? | Coupling & fragility, safe refactoring |
40
+ | When does timing matter? | Async & ordering, race conditions, correctness |
41
+
42
+ Based on [@acidgreenservers AGENTS.md](https://gist.github.com/acidgreenservers/001185d63e5cd65f9fbe6f7a1c70a200)
43
+
44
+ ### The Coherence Score
45
+
46
+ After every session, Parallax computes an evidence-based quality score (0-100):
47
+
48
+ - **Protocol Coverage (30%)** -- Were all 6 protocol phases completed?
49
+ - **Verification Integrity (35%)** -- Pass rate on first attempt?
50
+ - **Edge Case Coverage (20%)** -- How many edge categories were analyzed?
51
+ - **Timing Discipline (15%)** -- Were phases in correct order?
52
+
53
+ Track scores over time:
54
+
55
+ ```bash
56
+ parallax trace trend
57
+ parallax trace report --week
58
+ ```
59
+
60
+ ### Trace in Your PR
61
+
62
+ The AI calls `parallax_trace_pr_comment` at session end and outputs a formatted markdown block directly in the chat. Copy it into your PR. No terminal needed.
63
+
64
+ ### CI/CD Gate
65
+
66
+ ```yaml
67
+ - name: Parallax Gate
68
+ run: parallax gate --min-score 70
69
+ ```
70
+
71
+ Pre-commit hook:
72
+ ```bash
73
+ echo 'parallax pre-commit' >> .git/hooks/pre-commit
74
+ ```
75
+
76
+ ---
77
+
78
+ ## Comparison
79
+
80
+ | Feature | Plain OpenCode | Cursor | Copilot | Parallax |
81
+ |---|---|---|---|---|
82
+ | Structured reasoning trace | No | No | No | **Yes** |
83
+ | Trace as PR comment (inline) | No | No | No | **Yes** |
84
+ | Evidence-based quality score | No | No | No | **Yes** |
85
+ | Protocol enforcement (6 steps) | No | No | No | **Yes** |
86
+ | Mode switching (plan/build/debug) | No | No | No | **Yes** |
87
+ | CI coherence gate | No | No | No | **Yes** |
88
+ | Session retrospective | No | No | No | **Yes** |
89
+ | Design doc enforcement | No | No | No | **Yes** |
90
+ | Multi-agent state sharing | No | No | No | **Yes** |
91
+ | Shell env injection | No | No | No | **Yes** |
92
+ | Trace analytics | No | No | No | **Yes** |
93
+
94
+ ---
95
+
96
+ ## Architecture
97
+
98
+ ```
99
+ Parallax Agent (system prompt)
100
+ |
101
+ +-- Plugin hooks (8)
102
+ | event --> session ID + agent switches
103
+ | tool.execute.before --> protocol enforcement + friction + design doc gate
104
+ | tool.execute.after --> auto-verify + trace recording + state persistence
105
+ | experimental.chat.system.transform --> protocol status + mode skill + agent context
106
+ | experimental.session.compacting --> state preservation + trace export
107
+ | shell.env --> PARALLAX_MODE, PARALLAX_SESSION_ID in shell
108
+ |
109
+ +-- Custom tools (9)
110
+ | parallax_verify auto-verify after writes
111
+ | parallax_analyze multi-perspective analysis
112
+ | parallax_checkin protocol step checkin (6 steps incl. design)
113
+ | parallax_plan / _build / _debug mode switching
114
+ | parallax_trace_export export session trace to JSON file
115
+ | parallax_trace_pr_comment generate trace as PR-ready markdown
116
+ | parallax_trace_view show full reasoning trace inline in chat
117
+ |
118
+ +-- State files (at ~/.parallax/ in user home)
119
+ | state.json written on every transition (immediate on checkins)
120
+ | traces/ per-session JSON trace files
121
+ | scores.jsonl append-only score history
122
+ | config.json per-project config (optional)
123
+ |
124
+ | Note: Plugin process cwd is the user home directory (~), so all
125
+ | state persists at ~/.parallax/. The project .parallax/ dir is
126
+ | used by the CLI only.
127
+ |
128
+ +-- CLI (parallax) -- 11 commands
129
+ init | trace list/show/score/export/trend/report/compare/compliance
130
+ gate --min-score <n> | pre-commit
131
+ ```
132
+
133
+ ### Three Modes
134
+
135
+ | Mode | Tool | When |
136
+ |---|---|---|
137
+ | **PLAN** | `parallax_plan` | Vague requirements, before writing code |
138
+ | **BUILD** | `parallax_build` | Executing, writing code (default) |
139
+ | **DEBUG** | `parallax_debug` | Post-build quality and security audit |
140
+
141
+ ### Six Protocol Steps
142
+
143
+ | Step | Checkin | Enforced |
144
+ |---|---|---|
145
+ | 1. Ambiguity Check | `parallax_checkin("ambiguity")` | Blocks all writes until done |
146
+ | 2. 4 Invariants | `parallax_checkin("invariants")` | Warns after 3 writes without checkin |
147
+ | 3. Verification Gate | `parallax_checkin("gate")` | Requires invariants first |
148
+ | 4. Design Doc *(opt-in)* | `parallax_checkin("design")` | Per project via config |
149
+ | 5. Commit Decision | `parallax_checkin("commit")` | Any time after gate |
150
+ | 6. Summary | `parallax_checkin("summary")` | Generates retrospective |
151
+
152
+ ---
153
+
154
+ ## Project Config (.parallax/config.json)
155
+
156
+ ```json
157
+ {
158
+ "strictness": "standard",
159
+ "minScore": 70,
160
+ "adaptiveProtocol": false,
161
+ "designDocRequired": false,
162
+ "trivialPatterns": ["*.md", "*.json"],
163
+ "highRiskPatterns": ["**/auth/**", "**/*.env*"]
164
+ }
165
+ ```
166
+
167
+ | Key | Default | Description |
168
+ |---|---|---|
169
+ | `strictness` | `"standard"` | `"strict"` / `"standard"` / `"relaxed"` |
170
+ | `minScore` | `70` | Gate threshold for CI |
171
+ | `adaptiveProtocol` | `false` | Auto-skip gate steps for trivial changes |
172
+ | `designDocRequired` | `false` | Block writes until design doc produced |
173
+ | `trivialPatterns` | `[]` | File patterns considered low-risk |
174
+ | `highRiskPatterns` | `[]` | Patterns always requiring full protocol |
175
+
176
+ ---
177
+
178
+ ## Manual Install
179
+
180
+ ```bash
181
+ cp dist-standalone/parallax-engine.js ~/.config/opencode/plugins/
182
+ cp agents/parallax.md ~/.config/opencode/agents/
183
+ cp -r skills/parallax ~/.config/opencode/skills/
184
+ cp -r skills/parallax-plan ~/.config/opencode/skills/
185
+ cp -r skills/parallax-debug ~/.config/opencode/skills/
186
+ cd ~/.config/opencode && npm init -y && npm install @opencode-ai/plugin
187
+ ```
188
+
189
+ ---
190
+
191
+ ## Project Status
192
+
193
+ **v0.3.9** -- Cross-context protocol enforcement + full plugin integration
194
+
195
+ | Phase | Status | What |
196
+ |---|---|---|
197
+ | 1: Trace Artifact | Complete | PR comments, inline viewer, CI gate, pre-commit |
198
+ | 2: Protocol Intelligence | Complete | State persistence, retrospective, multi-agent sharing, shell env, design doc |
199
+ | 3: Developer Experience | Partial | Config system, design doc gate. Adaptive protocol deferred |
200
+ | 4: TUI Integration | Planned | Sidebar protocol status widget |
201
+ | 5: Analytics | Complete | Weekly reports, trace comparison, compliance reports |
202
+
203
+ See [ROADMAP.md](ROADMAP.md) for the full strategic plan.
204
+
205
+ ---
206
+
207
+ ## Commands
208
+
209
+ ### Plugin Tools (AI calls in OpenCode chat)
210
+
211
+ ```
212
+ parallax_verify Run project verification
213
+ parallax_analyze {topic} Multi-perspective analysis
214
+ parallax_checkin {step} Protocol step (ambiguity/invariants/gate/design/commit/summary)
215
+ parallax_plan / _build / _debug Mode switching
216
+ parallax_trace_export Export session trace to JSON
217
+ parallax_trace_pr_comment Generate trace as PR-ready markdown
218
+ parallax_trace_view Show reasoning trace inline in chat
219
+ ```
220
+
221
+ ### CLI (for CI and analytics)
222
+
223
+ ```
224
+ parallax init Create .parallax/ directory
225
+ parallax trace list List all traces
226
+ parallax trace show <id> Show trace details
227
+ parallax trace score <id> Show coherence score breakdown
228
+ parallax trace export <id> Export trace as pretty JSON
229
+ parallax trace trend Show score trend over time
230
+ parallax trace report --week Weekly analytics report
231
+ parallax trace compare <a> <b> Side-by-side trace comparison
232
+ parallax trace compliance <id> Protocol compliance report
233
+ parallax gate --min-score <n> CI coherence gate
234
+ parallax pre-commit Git pre-commit hook wrapper
235
+ ```
236
+
237
+ ---
238
+
239
+ ## Files
240
+
241
+ ```
242
+ parallax_plugin/
243
+ agents/parallax.md # Primary agent definition
244
+ src/plugin.ts # Canonical plugin (TypeScript, 1000+ lines)
245
+ src/types.ts # Shared type definitions
246
+ src/detect.ts # Project detection
247
+ src/trace.ts # Trace recording and export
248
+ src/score.ts # Coherence score + analytics
249
+ src/cli.ts # CLI entry point (11 commands)
250
+ src/tests/ # 30 tests across 5 files
251
+ dist/ # Compiled output
252
+ dist-standalone/ # Standalone bundled plugin (34KB)
253
+ skills/ # Protocol skills
254
+ scripts/ # Install and publish scripts
255
+ .parallax/ # Runtime state + traces + scores
256
+ ROADMAP.md # Strategic roadmap
257
+ CHANGELOG.md # Version history
258
+ ```
259
+
260
+ ---
261
+
262
+ ## License
263
+
264
+ MIT (c) [@Master0fFate](https://github.com/Master0fFate)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "parallax-opencode",
3
- "version": "0.3.9",
3
+ "version": "0.3.10",
4
4
  "description": "PARALLAX ENGINE plugin for OpenCode -- protocol enforcement, friction-loop verification, mode switching (plan/build/debug), trace recording, coherence scoring, CI gate, and PR-ready trace artifacts",
5
5
  "type": "module",
6
6
  "main": "./dist/plugin.js",