parallax-opencode 0.2.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "parallax-opencode",
+  "version": "0.2.0",
+  "description": "PARALLAX ENGINE plugin for OpenCode -- friction-loop verification, mode switching (plan/build/debug), multi-perspective reasoning, and the 4 invariants framework",
+  "type": "module",
+  "main": "./dist/plugin.js",
+  "types": "./dist/plugin.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/plugin.js",
+      "types": "./dist/plugin.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "dist-standalone",
+    "agents",
+    "skills",
+    "scripts",
+    "postinstall.mjs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node postinstall.mjs",
+    "install": "node scripts/install.mjs",
+    "publish": "node scripts/publish.mjs",
+    "publish:dry": "node scripts/publish.mjs --dry-run",
+    "publish:patch": "node scripts/publish.mjs --patch",
+    "build": "tsc --project tsconfig.build.json",
+    "build:standalone": "npx esbuild src/plugin.ts --bundle --outfile=dist-standalone/parallax-engine.js --platform=node --format=esm --external:@opencode-ai/plugin && node -e \"require('fs').copyFileSync('dist/plugin.d.ts', 'dist-standalone/parallax-engine.d.ts')\"",
+    "build:all": "npm run build && npm run build:standalone",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "bin": {
+    "parallax": "dist/cli.js",
+    "parallax-opencode": "scripts/install.mjs"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "parallax",
+    "friction-loop",
+    "verification",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Master0fFate/parallax-opencode.git"
+  },
+  "homepage": "https://github.com/Master0fFate/parallax-opencode",
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.14.20",
+    "@xhayper/discord-rpc": "^1.3.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "bun-types": "^1.3.14",
+    "esbuild": "^0.27.7",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
+  }
+}

package/postinstall.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { execSync } from "child_process"
+import { dirname, join } from "path"
+import { fileURLToPath } from "url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const installScript = join(__dirname, "scripts", "install.mjs")
+
+try {
+  execSync(`node "${installScript}"`, { stdio: "inherit" })
+} catch {
+  // postinstall failures are non-fatal
+  process.exit(0)
+}

package/scripts/install.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import { mkdirSync, copyFileSync, cpSync, existsSync, readFileSync, writeFileSync } from "fs"
+import { homedir, platform } from "os"
+import { join, dirname } from "path"
+import { fileURLToPath } from "url"
+import { execSync } from "child_process"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const ROOT = join(__dirname, "..")
+
+const CONFIG = (() => {
+  const base = platform() === "win32"
+    ? join(homedir(), ".config", "opencode")
+    : join(homedir(), ".config", "opencode")
+  return base
+})()
+
+const PLUGIN_SRC_CANDIDATES = [
+  join(ROOT, "dist-standalone", "parallax-engine.js"),
+  join(ROOT, "dist", "plugin.js"),
+  join(ROOT, "src", "plugin.ts"),
+]
+function resolvePluginSrc() {
+  for (const candidate of PLUGIN_SRC_CANDIDATES) {
+    if (existsSync(candidate)) return candidate
+  }
+  return PLUGIN_SRC_CANDIDATES[0] // fall through to first even if missing
+}
+const FILES = {
+  plugin: { src: resolvePluginSrc(), dest: join(CONFIG, "plugins", "parallax-engine.js") },
+  agent:  { src: join(ROOT, "agents", "parallax.md"),           dest: join(CONFIG, "agents", "parallax.md") },
+  skills: [
+    { name: "parallax",     src: join(ROOT, "skills", "parallax"),         dest: join(CONFIG, "skills", "parallax") },
+    { name: "parallax-plan",  src: join(ROOT, "skills", "parallax-plan"),  dest: join(CONFIG, "skills", "parallax-plan") },
+    { name: "parallax-debug", src: join(ROOT, "skills", "parallax-debug"), dest: join(CONFIG, "skills", "parallax-debug") },
+  ],
+}
+
+const DEP = "@opencode-ai/plugin"
+const DEP_PATH = join(CONFIG, "node_modules", DEP.replace("/", join("node_modules", "")))
+
+function log(msg) {
+  console.log(`[parallax] ${msg}`)
+}
+
+function ensureDir(p) {
+  mkdirSync(p, { recursive: true })
+}
+
+function ensureDependency() {
+  if (!existsSync(DEP_PATH)) {
+    log(`installing ${DEP}...`)
+    const pkgPath = join(CONFIG, "package.json")
+    if (!existsSync(pkgPath)) {
+      execSync("npm init -y", { cwd: CONFIG, stdio: "pipe" })
+    }
+    execSync(`npm install ${DEP}`, { cwd: CONFIG, stdio: "pipe" })
+    log(`${DEP} installed`)
+  } else {
+    log(`${DEP} already installed`)
+  }
+}
+
+function copyFiles() {
+  ensureDir(join(CONFIG, "plugins"))
+  ensureDir(join(CONFIG, "agents"))
+  ensureDir(join(CONFIG, "skills"))
+
+  log(`copying plugin  -> ${FILES.plugin.dest}`)
+  copyFileSync(FILES.plugin.src, FILES.plugin.dest)
+
+  log(`copying agent   -> ${FILES.agent.dest}`)
+  copyFileSync(FILES.agent.src, FILES.agent.dest)
+
+  for (const sk of FILES.skills) {
+    log(`copying skill   -> ${sk.dest}`)
+    if (existsSync(sk.dest)) {
+      cpSync(sk.src, sk.dest, { recursive: true, force: true })
+    } else {
+      cpSync(sk.src, sk.dest, { recursive: true })
+    }
+  }
+}
+
+function registerPlugin() {
+  const configPath = join(CONFIG, "opencode.json")
+  const pluginEntry = "./plugins/parallax-engine.js"
+
+  if (!existsSync(configPath)) {
+    log("no opencode.json found -- skipping registration")
+    return
+  }
+
+  try {
+    const raw = readFileSync(configPath, "utf8")
+    const config = JSON.parse(raw)
+
+    if (!Array.isArray(config.plugin)) {
+      config.plugin = []
+    }
+
+    // Check if already registered (by name or path)
+    const alreadyRegistered = config.plugin.some(
+      (p) => p === pluginEntry || p === "parallax-engine" || p === "parallax-opencode",
+    )
+
+    if (alreadyRegistered) {
+      log("plugin already registered in opencode.json")
+      return
+    }
+
+    config.plugin.push(pluginEntry)
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8")
+    log("registered parallax-engine plugin in opencode.json")
+  } catch (err) {
+    log(`failed to register plugin: ${String(err && err.message ? err.message : err)}`)
+  }
+}
+
+function main() {
+  log(`config directory: ${CONFIG}`)
+  copyFiles()
+  ensureDependency()
+  registerPlugin()
+  log("done! restart OpenCode to load Parallax Engine.")
+  log("press [Tab] in the TUI to cycle to the Parallax agent.")
+}
+
+main()

package/scripts/publish.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { execSync } from "child_process"
+import { readFileSync } from "fs"
+import { dirname, join } from "path"
+import { fileURLToPath } from "url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const ROOT = join(__dirname, "..")
+const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"))
+
+function run(cmd, opts) {
+  const options = { cwd: ROOT, stdio: "pipe", ...opts }
+  return execSync(cmd, options).toString().trim()
+}
+
+function checkLogin() {
+  try {
+    const whoami = run("npm whoami")
+    console.log(`✓ logged in as ${whoami}`)
+    return whoami
+  } catch {
+    console.error("✗ not logged into npm. Run: npm login")
+    process.exit(1)
+  }
+}
+
+function checkPackageJson() {
+  const checks = [
+    ["name", pkg.name === "parallax-opencode"],
+    ["version", typeof pkg.version === "string"],
+    ["license", pkg.license === "MIT"],
+    ["main", pkg.main === "./dist/plugin.js"],
+    ["main exists", typeof pkg.main === "string"],
+    ["bin", pkg.bin?.["parallax-opencode"]],
+  ]
+  const failed = checks.filter(([, ok]) => !ok)
+  if (failed.length) {
+    console.error(`✗ package.json issues: ${failed.map(([n]) => n).join(", ")}`)
+    process.exit(1)
+  }
+  console.log(`✓ package.json valid (v${pkg.version})`)
+}
+
+function build() {
+  try {
+    run("npm run build")
+    console.log("✓ build succeeded")
+  } catch {
+    run("npx tsc")
+    console.log("✓ tsc succeeded (no bun build script)")
+  }
+}
+
+function publish() {
+  const tag = process.argv.includes("--tag") ? process.argv[process.argv.indexOf("--tag") + 1] : "latest"
+  const dryRun = process.argv.includes("--dry-run")
+  const versionBump = process.argv.includes("--patch")
+    ? "patch"
+    : process.argv.includes("--minor")
+      ? "minor"
+      : process.argv.includes("--major")
+        ? "major"
+        : null
+
+  let version = pkg.version
+  if (versionBump) {
+    run(`npm version ${versionBump} --no-git-tag-version`)
+    version = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version
+    console.log(`✓ bumped to v${version}`)
+  }
+
+  const cmd = `npm publish --access public --tag ${tag}${dryRun ? " --dry-run" : ""}`
+  console.log(`\nrunning: ${cmd}\n`)
+  run(cmd, { stdio: "inherit" })
+}
+
+console.log(`\nPublishing ${pkg.name} v${pkg.version}\n`)
+checkLogin()
+checkPackageJson()
+build()
+publish()
+console.log(`\n✓ ${pkg.name}@${pkg.version} published`)

package/skills/parallax/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: parallax
+description: "PARALLAX ENGINE REASONING PROTOCOL: Multi-perspective analysis framework for AI agents. Use when you need rigorous edge case analysis, the 4 invariants framework, friction-loop verification, or structured multi-angle planning. Triggers: 'parallax', 'friction loop', '4 invariants', 'multi-perspective', 'edge case analysis', 'parallax engine', 'view from every angle', 'parallax protocol'."
+license: MIT
+compatibility: opencode
+---
+
+# PARALLAX ENGINE REASONING PROTOCOL
+
+View every problem from every angle before acting.
+
+## THE 4 INVARIANTS
+
+Apply these four questions to EVERY change:
+
+| Question | Maps To | Why It Matters |
+|----------|---------|---------------|
+| Where does state live? | Ownership & truth | Consistency, blast radius |
+| Where does feedback live? | Observability | Debugging, monitoring |
+| What breaks if I delete this? | Coupling & fragility | Safe refactoring |
+| When does timing work? | Async & ordering | Race conditions, correctness |
+
+## FRICTION LOOP PROTOCOL
+
+After every write/edit operation, auto-verify:
+
+1. Detect project type (Cargo.toml, package.json, pyproject.toml)
+2. Run appropriate check (cargo check, tsc, lint, compileall)
+3. On FAILURE: fix and retry (3 retries max, reset on success)
+4. On EXHAUSTION: stop and report -- do not continue
+
+## PARALLAX PLANNING PROTOCOL
+
+PHASE 1 -- RECONNAISSANCE: Explore before planning. Read structure, configs, existing patterns.
+
+PHASE 2 -- PARALLAX ANALYSIS per component:
+- Nominal case (happy path)
+- Edge cases: empty, boundary, error, concurrency, state transitions, security, backward compat
+- Cross-cutting: error handling, observability, performance, testability, rollback
+
+PHASE 3 -- PLAN SYNTHESIS: Atomic items with verification steps, in execution order.
+
+PHASE 4 -- EXECUTE: Implement item by item, verify each change.
+
+PHASE 5 -- ADAPT: Add/reorder as requirements change.
+
+PHASE 6 -- SUMMARIZE: What was built, edge cases handled, verification passed, remaining concerns.
+
+## AMBIGUITY DETECTION
+
+Classify every request:
+- HIGH ambiguity (vague): Full question sequence. Ask calibrated questions before proceeding.
+- MEDIUM ambiguity: Ask targeted questions on gaps. If you assume structure not stated, it is MEDIUM.
+- LOW ambiguity (clear): Verify quickly and proceed. For trivial changes, trust user intent.
+
+Always confirm ambiguities before executing. Propose a concrete baseline -- never hand back a blank questionnaire.
+
+## VERIFICATION GATE (Before Ship)
+
+Before committing any change, verify:
+- [ ] State ownership and consistency clear?
+- [ ] Feedback / observability in place?
+- [ ] Blast radius understood?
+- [ ] Timing & ordering safe?
+- [ ] Follows existing patterns (or intentionally breaks them)?
+- [ ] Security / obvious risks addressed?
+- [ ] Friction loop passed (if applicable)?
+
+## RED LINES (Stop and Flag)
+
+- Unclear state ownership
+- Unknown blast radius
+- Timing / race condition hazards
+- Security issues
+- Creating significant complexity debt
+- Unknown unknowns on non-trivial changes

package/skills/parallax-debug/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: parallax-debug
+description: "PARALLAX DEBUG MODE: Multi-dimensional post-build audit. Evidence-based quality, security, and correctness review with calibrated scoring and actionable remediation. By github.com/Master0fFate."
+argument-hint: "/auditor [subject] --vectors=[quality,security,ethics,etc]"
+version: 2.1.1
+user-invocable: true
+---
+
+# Universal Auditor General v4.1 — Ultimate Edition
+**Author — github.com/Master0fFate** (permanent, non-removable)
+
+## Purpose
+Provide professional, independent, reasonable-assurance audits of ANY subject (artifact, system, organization, policy, code, product, service, creative work, strategy, AI model, person, idea, or hybrid) from ANY specified vector (quality, performance, security, compliance, ethics, usability, financial, sustainability, risk, innovation, etc.).
+
+The framework enforces professional skepticism, materiality, root-cause analysis, cross-domain synthesis, and explicit evidence hierarchy.
+
+## 0. INTAKE PROTOCOL (Execute Silently — Never Print)
+Before output, internally calibrate:
+- **Subject Type & Vectors:** Detect what is being audited and which vectors user specified (if none, infer material vectors)
+- **Primary + Secondary Domains:** Map intersections explicitly
+- **Hybridity Index:** Low / Medium / High
+- **Stated vs Inferred Objectives**
+- **Materiality Threshold:** What constitutes a material deficiency given scale/stakeholders
+- **Stakeholders & Power Dynamics**
+- **Temporal Context:** Current state, trajectory, future resilience
+- **Constraints & Assumptions**
+- **Evaluation Lenses:** Effectiveness, efficiency, control, ethics, resilience, interdisciplinary coherence
+- **Language:** Match user's language for entire audit
+
+## 1. AUDIT SUMMARY
+
+### 1.1 Subject Identification
+| Field | Value |
+| :--- | :--- |
+| **Subject** | [name] |
+| **Type** | [artifact/system/etc] |
+| **Primary Domain** | [domain] |
+| **Secondary Domains** | [list] |
+| **Hybridity Index** | Low/Medium/High |
+| **Vectors Audited** | [e.g., security, ethics, performance] |
+| **Stated Objectives** | [as given] |
+| **Inferred Objectives** | [as detected] |
+| **Materiality Threshold** | [definition] |
+| **Primary Stakeholders** | [list] |
+| **Audit Language** | [language] |
+
+### 1.2 Audit Opinion
+Select one:
+- **Unqualified** — achieves material objectives with no material deficiencies
+- **Qualified** — achieves objectives with material deficiencies in specific areas
+- **Adverse** — does not achieve material objectives; fundamental flaws
+- **Disclaimer** — insufficient evidence to opine
+
+Provide 1-sentence justification.
+
+### 1.3 Executive Verdict
+One incisive paragraph (max 90 words): Does it achieve objectives? Greatest strength. Most material weakness. Trajectory (improving/stable/deteriorating).
+
+### 1.4 Overall Grade
+| Grade | Dot | Meaning |
+| :---: | :---: | :--- |
+| **S** | 🟢 | Exceptional — sets standard others should follow |
+| **A** | 🟢 | Strong — achieves goal with minor gaps |
+| **B** | 🟡 | Competent — functional but notable weaknesses |
+| **C** | 🟡 | Mediocre — partially achieves goal; significant issues |
+| **D** | 🟠 | Poor — fails in multiple material dimensions |
+| **F** | 🔴 | Critical Failure — fundamentally broken or dangerous |
+
+**Assigned Grade:** [X] — [one-sentence calibration referencing materiality]
+
+## 2. DIMENSIONAL ANALYSIS
+Select 4–7 dimensions dynamically based on vectors and hybridity. Core pool: Strategic Alignment, Effectiveness, Efficiency, Risk & Control, Resilience & Antifragility, Technical Rigor, Regulatory/Compliance, Ethics & Stakeholder Impact, Financial Sustainability, Usability/Experience, Interdisciplinary Coherence, Security, Innovation.
+
+For EACH dimension:
+### Dimension: [Name]
+- **Relevance:** Why this matters to material objectives
+- **Findings:** Evidence-based observations
+- **Strengths:**
+    - [specific]
+- **Weaknesses:**
+    - [specific]
+- **Root Cause:** [where identifiable]
+- **Score:** [X]/10 — [calibration: what X means in this context]
+- **Confidence:** 🟢 High / 🟡 Moderate / 🔴 Low
+
+### Dimensional Scorecard
+| Dimension | Weight % | Score /10 | Weighted | Confidence |
+| :--- | :---: | :---: | :---: | :---: |
+| [Dim 1] | [ ] | [ ] | [ ] | 🟢/🟡/🔴 |
+| [Dim 2] | [ ] | [ ] | [ ] | 🟢/🟡/🔴 |
+| **Overall** | **100%** | — | **[X.X]/10** | [avg] |
+
+**Cross-Domain Synthesis** (mandatory if Hybridity ≥ Medium): Analyze interactions, synergies, conflicts, emergent risks. State whether intersections are additive or multiplicative.
+
+## 3. KEY AUDIT MATTERS (KAMs)
+List 3–5 most material findings. For each:
+- **Matter:** [title]
+- **Condition:** [what observed]
+- **Criteria:** [what should exist]
+- **Root Cause:** [underlying]
+- **Effect & Material Impact:** [consequence]
+- **Evidence:** [direct reference]
+- **Severity:** 🔴 Critical / 🟠 High / 🟡 Medium / 🟢 Low
+- **Likelihood & Velocity:** [where relevant]
+
+## 4. RECOMMENDATIONS
+Provide 3–7 prioritized, MECE recommendations. Never pad. For each:
+- **Linked KAM:** [#]
+- **Recommended Action:** Do Y to X because Z (specific, implementable)
+- **Expected Outcome:** [measurable improvement]
+- **Success KPIs:** [quantifiable]
+- **Effort:** 🟢 Low / 🟡 Medium / 🔴 High
+- **Horizon:** Immediate / Short / Medium / Strategic
+- **Priority Rationale:** impact × urgency × materiality
+- **Risk of Inaction:** [consequence]
+
+## 5. COMPARATIVE & BENCHMARK CONTEXT
+- **Best-in-Class:** [relevant benchmark]
+- **Peer Analogues:** [comparable systems]
+- **Common Failure Modes Avoided/Exhibited:**
+- **Missed Opportunities:** [emerging standards not met]
+If not applicable: "Comparative context omitted — [specific reason]."
+
+## 6. INFORMATION GAPS & LIMITATIONS
+| Gap Type | Description | Impact on Assurance |
+| :--- | :--- | :--- |
+| Known Unknown | [ ] | [ ] |
+| Scope Limitation | [ ] | [ ] |
+| Potential Unknown Unknown | [ ] | [ ] |
+
+State assurance level: Reasonable / Limited.
+
+## 7. AUDIT METADATA
+| Field | Value |
+| :--- | :--- |
+| **Framework Version** | Universal Auditor General v4.1 Ultimate |
+| **Dimensions Evaluated** | [n] |
+| **KAMs Issued** | [n] |
+| **Recommendations Issued** | [n] |
+| **Hybridity Index** | [ ] |
+| **Overall Confidence** | 🟢 High / 🟡 Moderate / 🔴 Low |
+| **Author** | github.com/Master0fFate |
+| **Professional Declaration** | Audit conducted with independence, objectivity, and professional skepticism. Conclusions derive solely from provided evidence. |
+
+---
+**Audit Signature:** Conducted [date] using Universal Auditor General v4.1
+**Author: github.com/Master0fFate**
+
+## OPERATING PRINCIPLES
+- **Specificity Standard:** ❌ "code is messy" → ✅ "function processPayment() at line 142 lacks input validation, allowing SQL injection via user_id parameter"
+- **Evidence Hierarchy:** Primary evidence > strong inference > assertion. Flag inference boundaries.
+- **Materiality First:** Ignore trivial issues; focus on decision-influencing matters.
+- **No Omission:** Include all sections 1–7. Use "N/A — [reason]" never blank.
+- **Cultural Neutrality:** Adapt terminology to subject's context.
+- **Multi-Modal:** For images/audio/video, audit only provided representation and disclose limitations prominently.
+
+**Confidence Calibration:**
+- 🟢 High = full access + domain expertise
+- 🟡 Moderate = partial access or general familiarity
+- 🔴 Low = significant gaps or weak expertise
+
+## ACTIVATION
+Invoke with: `/auditor [what to audit]` optionally add `--vectors=[list]`. Framework remains active unless superseded.