parallax-opencode 0.3.10 → 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 +69 -166
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,34 +1,55 @@
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
1
  # PARALLAX ENGINE
4
2
 
5
- **The first AI coding assistant that shows its work.**
3
+ **OpenCode plugin** -- friction-loop verification, protocol enforcement, mode switching (plan/build/debug), and structured reasoning traces.
6
4
 
7
5
  [![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
6
  [![npm](https://img.shields.io/npm/v/parallax-opencode)](https://www.npmjs.com/package/parallax-opencode)
10
7
  [![Tests](https://img.shields.io/badge/tests-30%20passing-brightgreen)]()
11
- [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)]()
12
8
 
13
9
  ---
14
10
 
15
- ## Quick Install
11
+ ## Install
16
12
 
17
13
  ```bash
18
14
  npx parallax-opencode
19
15
  ```
20
16
 
21
- After install, restart OpenCode and press **Tab** to cycle to the Parallax agent.
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).
22
20
 
23
21
  ---
24
22
 
25
- ## What Makes Parallax Different
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 |
26
45
 
27
- Every AI coding tool gives you code. None of them show you **how they got there**.
46
+ ### Friction Loop
28
47
 
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.
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.
30
49
 
31
- > "Here is my complete reasoning trace. Review it. Score it. Compare it. See for yourself."
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.
32
53
 
33
54
  ### The 4 Invariants
34
55
 
@@ -41,58 +62,37 @@ Parallax captures the complete reasoning trace of every session -- the ambiguity
41
62
 
42
63
  Based on [@acidgreenservers AGENTS.md](https://gist.github.com/acidgreenservers/001185d63e5cd65f9fbe6f7a1c70a200)
43
64
 
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?
65
+ ---
52
66
 
53
- Track scores over time:
67
+ ## Plugin Tools
54
68
 
55
- ```bash
56
- parallax trace trend
57
- parallax trace report --week
58
- ```
69
+ These are called by the AI in OpenCode chat:
59
70
 
60
- ### Trace in Your PR
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 |
61
80
 
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.
81
+ ---
63
82
 
64
- ### CI/CD Gate
83
+ ## CLI (CI Only)
65
84
 
66
- ```yaml
67
- - name: Parallax Gate
68
- run: parallax gate --min-score 70
69
- ```
85
+ The `parallax` CLI is for CI pipelines and automation, not for interactive use:
70
86
 
71
- Pre-commit hook:
72
87
  ```bash
73
- echo 'parallax pre-commit' >> .git/hooks/pre-commit
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)
74
92
  ```
75
93
 
76
94
  ---
77
95
 
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
96
  ## Architecture
97
97
 
98
98
  ```
@@ -107,57 +107,27 @@ Parallax Agent (system prompt)
107
107
  | shell.env --> PARALLAX_MODE, PARALLAX_SESSION_ID in shell
108
108
  |
109
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
110
+ | parallax_verify, parallax_analyze, parallax_checkin,
111
+ | parallax_plan / _build / _debug,
112
+ | parallax_trace_export / _pr_comment / _view
117
113
  |
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
114
+ +-- State (at ~/.parallax/)
115
+ | state.json protocol state (immediate on checkins)
116
+ | traces/ per-session JSON traces
121
117
  | scores.jsonl append-only score history
122
118
  | 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
119
  ```
132
120
 
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
121
  ---
153
122
 
154
- ## Project Config (.parallax/config.json)
123
+ ## Project Config
124
+
125
+ Create `.parallax/config.json` in your project root:
155
126
 
156
127
  ```json
157
128
  {
158
129
  "strictness": "standard",
159
130
  "minScore": 70,
160
- "adaptiveProtocol": false,
161
131
  "designDocRequired": false,
162
132
  "trivialPatterns": ["*.md", "*.json"],
163
133
  "highRiskPatterns": ["**/auth/**", "**/*.env*"]
@@ -168,97 +138,30 @@ Parallax Agent (system prompt)
168
138
  |---|---|---|
169
139
  | `strictness` | `"standard"` | `"strict"` / `"standard"` / `"relaxed"` |
170
140
  | `minScore` | `70` | Gate threshold for CI |
171
- | `adaptiveProtocol` | `false` | Auto-skip gate steps for trivial changes |
172
141
  | `designDocRequired` | `false` | Block writes until design doc produced |
173
142
  | `trivialPatterns` | `[]` | File patterns considered low-risk |
174
143
  | `highRiskPatterns` | `[]` | Patterns always requiring full protocol |
175
144
 
176
145
  ---
177
146
 
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
147
+ ## Source Layout
240
148
 
241
149
  ```
242
150
  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
151
+ agents/parallax.md # Agent definition
152
+ src/plugin.ts # Plugin (~1000 lines)
153
+ src/types.ts # Shared types
246
154
  src/detect.ts # Project detection
247
- src/trace.ts # Trace recording and export
155
+ src/trace.ts # Trace recording + export
248
156
  src/score.ts # Coherence score + analytics
249
- src/cli.ts # CLI entry point (11 commands)
157
+ src/cli.ts # CLI (CI only)
250
158
  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
159
+ dist-standalone/ # Bundled plugin (~37KB)
160
+ skills/ # Parallax protocol skills
258
161
  ```
259
162
 
260
163
  ---
261
164
 
262
165
  ## License
263
166
 
264
- MIT (c) [@Master0fFate](https://github.com/Master0fFate)
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.10",
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",