parallax-opencode 0.3.9 → 0.3.11

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 +167 -260
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,260 +1,167 @@
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 ENGINE
2
+
3
+ **OpenCode plugin** -- friction-loop verification, protocol enforcement, mode switching (plan/build/debug), and structured reasoning traces.
4
+
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
6
+ [![npm](https://img.shields.io/npm/v/parallax-opencode)](https://www.npmjs.com/package/parallax-opencode)
7
+ [![Tests](https://img.shields.io/badge/tests-30%20passing-brightgreen)]()
8
+
9
+ ---
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ npx parallax-opencode
15
+ ```
16
+
17
+ Restart OpenCode. The plugin hooks and tools are auto-loaded.
18
+
19
+ The plugin stores runtime state at `~/.parallax/state.json` (plugin process runs from user home directory).
20
+
21
+ ---
22
+
23
+ ## What It Does
24
+
25
+ ### Protocol Enforcement (6 steps)
26
+
27
+ The Parallax agent follows a structured reasoning protocol before writing code. The plugin enforces this via the `tool.execute.before` hook:
28
+
29
+ | Step | Checkin | What it blocks |
30
+ |---|---|---|
31
+ | 1. Ambiguity Check | `parallax_checkin("ambiguity")` | All writes until done |
32
+ | 2. 4 Invariants | `parallax_checkin("invariants")` | Warns after 3 writes without checkin |
33
+ | 3. Verification Gate | `parallax_checkin("gate")` | Requires invariants first |
34
+ | 4. Design Doc (opt-in) | `parallax_checkin("design")` | Per project via config |
35
+ | 5. Commit Decision | `parallax_checkin("commit")` | Any time after gate |
36
+ | 6. Summary | `parallax_checkin("summary")` | Generates retrospective |
37
+
38
+ ### Mode Switching
39
+
40
+ | Mode | Tool | When |
41
+ |---|---|---|
42
+ | PLAN | `parallax_plan` | Vague requirements, before writing code |
43
+ | BUILD | `parallax_build` | Executing, writing code (default) |
44
+ | DEBUG | `parallax_debug` | Post-build quality and security audit |
45
+
46
+ ### Friction Loop
47
+
48
+ After every write, the plugin auto-runs project verification. On failure, it decrements a retry counter. After 3 consecutive failures, it blocks further writes until the issue is resolved.
49
+
50
+ ### Trace Recording
51
+
52
+ Every session produces a structured reasoning trace -- phases, writes, verification results. The AI can export it to JSON or generate a PR-ready markdown summary.
53
+
54
+ ### The 4 Invariants
55
+
56
+ | Question | Why It Matters |
57
+ |---|---|
58
+ | Where does state live? | Ownership & truth, consistency, blast radius |
59
+ | Where does feedback live? | Observability, debugging, monitoring |
60
+ | What breaks if I delete this? | Coupling & fragility, safe refactoring |
61
+ | When does timing matter? | Async & ordering, race conditions, correctness |
62
+
63
+ Based on [@acidgreenservers AGENTS.md](https://gist.github.com/acidgreenservers/001185d63e5cd65f9fbe6f7a1c70a200)
64
+
65
+ ---
66
+
67
+ ## Plugin Tools
68
+
69
+ These are called by the AI in OpenCode chat:
70
+
71
+ | Tool | Purpose |
72
+ |---|---|
73
+ | `parallax_verify` | Run project verification |
74
+ | `parallax_analyze` | Multi-perspective analysis on a topic |
75
+ | `parallax_checkin` | Mark a protocol step complete |
76
+ | `parallax_plan` / `_build` / `_debug` | Switch modes |
77
+ | `parallax_trace_export` | Export session trace to JSON |
78
+ | `parallax_trace_pr_comment` | Generate trace as PR-ready markdown |
79
+ | `parallax_trace_view` | Show full reasoning trace inline |
80
+
81
+ ---
82
+
83
+ ## CLI (CI Only)
84
+
85
+ The `parallax` CLI is for CI pipelines and automation, not for interactive use:
86
+
87
+ ```bash
88
+ parallax gate --min-score 70 # CI coherence gate (exit code 0/1)
89
+ parallax pre-commit # Git pre-commit hook wrapper
90
+ parallax init # Create .parallax/ config dir
91
+ npx parallax-opencode # Install the plugin (alias for init)
92
+ ```
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, parallax_analyze, parallax_checkin,
111
+ | parallax_plan / _build / _debug,
112
+ | parallax_trace_export / _pr_comment / _view
113
+ |
114
+ +-- State (at ~/.parallax/)
115
+ | state.json protocol state (immediate on checkins)
116
+ | traces/ per-session JSON traces
117
+ | scores.jsonl append-only score history
118
+ | config.json per-project config (optional)
119
+ ```
120
+
121
+ ---
122
+
123
+ ## Project Config
124
+
125
+ Create `.parallax/config.json` in your project root:
126
+
127
+ ```json
128
+ {
129
+ "strictness": "standard",
130
+ "minScore": 70,
131
+ "designDocRequired": false,
132
+ "trivialPatterns": ["*.md", "*.json"],
133
+ "highRiskPatterns": ["**/auth/**", "**/*.env*"]
134
+ }
135
+ ```
136
+
137
+ | Key | Default | Description |
138
+ |---|---|---|
139
+ | `strictness` | `"standard"` | `"strict"` / `"standard"` / `"relaxed"` |
140
+ | `minScore` | `70` | Gate threshold for CI |
141
+ | `designDocRequired` | `false` | Block writes until design doc produced |
142
+ | `trivialPatterns` | `[]` | File patterns considered low-risk |
143
+ | `highRiskPatterns` | `[]` | Patterns always requiring full protocol |
144
+
145
+ ---
146
+
147
+ ## Source Layout
148
+
149
+ ```
150
+ parallax_plugin/
151
+ agents/parallax.md # Agent definition
152
+ src/plugin.ts # Plugin (~1000 lines)
153
+ src/types.ts # Shared types
154
+ src/detect.ts # Project detection
155
+ src/trace.ts # Trace recording + export
156
+ src/score.ts # Coherence score + analytics
157
+ src/cli.ts # CLI (CI only)
158
+ src/tests/ # 30 tests across 5 files
159
+ dist-standalone/ # Bundled plugin (~37KB)
160
+ skills/ # Parallax protocol skills
161
+ ```
162
+
163
+ ---
164
+
165
+ ## License
166
+
167
+ 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.11",
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",