{"_id":"@alvadorncorp/gopher","_rev":"2-88939cab74eea2bb9fa8df8460077527","name":"@alvadorncorp/gopher","dist-tags":{"latest":"1.0.0"},"versions":{"0.7.0":{"name":"@alvadorncorp/gopher","version":"0.7.0","keywords":["go","golang","opencode","architecture","security","code-review"],"author":{"name":"Igor Sant'Ana @ Alvadorn Corp"},"license":"MIT","_id":"@alvadorncorp/gopher@0.7.0","maintainers":[{"name":"alvadorn","email":"igorba2005@gmail.com"}],"dist":{"shasum":"b7b0f5d0848e1c1dc1495aacd967ba151f70253e","tarball":"https://registry.npmjs.org/@alvadorncorp/gopher/-/gopher-0.7.0.tgz","fileCount":190,"integrity":"sha512-44T/rrlQD9m9+VA/dNUmJds3JD4SIVcDaFIoN2lJnhu7yL6nGnQy+vj77lxUJzwbKSu/S1hLocRg8UE/PslEuA==","signatures":[{"sig":"MEUCIDScHiDOcXzdcXipb5zxVKWzQJDKbITI3OgCgFiCM5YeAiEApTCXZSV0VzVX9XyeHEmNESd7m7eLsSOjfSa60jz738M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":588900},"main":"plugins/gopher/opencode/plugin.js","type":"module","engines":{"opencode":">=1.18.15"},"exports":{".":"./plugins/gopher/opencode/plugin.js"},"gitHead":"42aee2f945683ae8377990c898f450d8c0081f21","_npmUser":{"name":"alvadorn","email":"igorba2005@gmail.com"},"_npmVersion":"11.11.0","description":"Evidence-driven Go engineering workflows for design, implementation, diagnosis, security, and multi-lens review.","directories":{},"_nodeVersion":"24.14.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gopher_0.7.0_1787358673787_0.061146885248536176","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@alvadorncorp/gopher","version":"1.0.0","description":"Evidence-driven Go engineering workflows for design, implementation, diagnosis, security, and multi-lens review.","license":"MIT","author":{"name":"Igor Sant'Ana @ Alvadorn Corp"},"type":"module","main":"plugins/gopher/opencode/plugin.js","exports":{".":"./plugins/gopher/opencode/plugin.js"},"publishConfig":{"access":"public"},"engines":{"opencode":">=1.18.15"},"keywords":["go","golang","opencode","architecture","security","code-review"],"gitHead":"ad004279208bbf7e09000aed1a045f2934ecc505","_id":"@alvadorncorp/gopher@1.0.0","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-CNyjWwvEZdo58XkJJyTglgq+uUBGB6yT9O2JnAT9qu1u60YYXB23VMajnYT6Q9hrQrZyBxGV3JFgmetteUsNWQ==","shasum":"9ba88b21727492b666d3dbd16528ebae7df8eb06","tarball":"https://registry.npmjs.org/@alvadorncorp/gopher/-/gopher-1.0.0.tgz","fileCount":190,"unpackedSize":588900,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCUnfg0wc09UBvDv98CG26Sb4G3TW6RdwRRy2EXhAodOgIgc6Th5qnpJhgBTaGzuErHJEHLZ/ebQpS+dVPM//Qb3x8="}]},"_npmUser":{"name":"alvadorn","email":"igorba2005@gmail.com"},"directories":{},"maintainers":[{"name":"alvadorn","email":"igorba2005@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gopher_1.0.0_1787359247236_0.5486082682345554"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-22T00:31:13.663Z","modified":"2026-08-22T00:40:47.572Z","0.7.0":"2026-08-22T00:31:13.949Z","1.0.0":"2026-08-22T00:40:47.410Z"},"author":{"name":"Igor Sant'Ana @ Alvadorn Corp"},"license":"MIT","keywords":["go","golang","opencode","architecture","security","code-review"],"description":"Evidence-driven Go engineering workflows for design, implementation, diagnosis, security, and multi-lens review.","maintainers":[{"name":"alvadorn","email":"igorba2005@gmail.com"}],"readme":"# Gopher Plugin\n\n

\n \"Gopher\n

\n\nGopher packages evidence-driven Go engineering workflows as one installable\nplugin for Codex, Claude Code, Grok Build, Kimi Code, and OpenCode. Its goal is to help\nan agent diagnose before it prescribes, choose idiomatic Go designs, make small\nreversible changes, review code through explicit risk lenses, and coordinate\nlarger refactors with documented evidence.\n\nThe repository keeps one shared plugin implementation at `plugins/gopher/` and\nexposes it through native marketplace manifests for each host. Codex reads the\n`.agents/plugins/marketplace.json` catalog and the plugin's\n`.codex-plugin/plugin.json` manifest. Claude Code reads\n`.claude-plugin/marketplace.json` and the plugin's `.claude-plugin/plugin.json`\nmanifest. Grok Build reads `.grok-plugin/marketplace.json` and the plugin's\n`.grok-plugin/plugin.json` manifest. Kimi Code reads\n`.kimi-plugin/marketplace.json` and the plugin's `.kimi-plugin/plugin.json`\nmanifest. OpenCode installs the npm package `@alvadorncorp/gopher`, whose config\nhook registers the same `skills/` tree and three native role agents. All five\nhosts load the same physical skill tree.\n\n## What Gopher provides\n\nGopher is not a Go formatter, linter, or language server. It is a collection of\nagent skills and references that guide engineering decisions and workflows for\nGo repositories:\n\n- Diagnose unexplained symptoms before choosing an owner or fix path, and check\n known readiness invariants before an action.\n- Select Go-appropriate construction, value, error, and behavior patterns.\n- Implement routine Go changes with local tests and proportional validation.\n- Review diffs through exact lenses for correctness, tests, security,\n architecture, and concurrency/performance.\n- Measure complexity and test quality, then separate safe local cleanup from\n broader design work.\n- Modernize code against the project's declared Go version.\n- Coordinate repository-wide refactors with baselines, sequencing, handoffs,\n and evidence.\n\nThe installable package intentionally ships no user-triggered hooks, MCP servers,\napps, LSP servers, or runtime visual assets. The OpenCode adapter uses only a\nstartup config hook to register the shared skills and native role agents.\n\n## Package layout\n\n- Codex marketplace: `.agents/plugins/marketplace.json`\n- Claude Code marketplace: `.claude-plugin/marketplace.json`\n- Grok Build marketplace: `.grok-plugin/marketplace.json`\n- Kimi Code marketplace: `.kimi-plugin/marketplace.json`\n- Shared plugin: `plugins/gopher/`\n- Codex manifest: `plugins/gopher/.codex-plugin/plugin.json`\n- Claude Code manifest: `plugins/gopher/.claude-plugin/plugin.json`\n- Grok Build manifest: `plugins/gopher/.grok-plugin/plugin.json`\n- Kimi Code manifest: `plugins/gopher/.kimi-plugin/plugin.json`\n- OpenCode package: `package.json`\n- OpenCode adapter: `plugins/gopher/opencode/plugin.js`\n- Shared skills: `plugins/gopher/skills/`\n- Packaged agents (Claude Code, Grok Build): `plugins/gopher/agents/`\n- Packaged agents (Codex): `plugins/gopher/agents/codex/`\n- Packaged agents (OpenCode): `plugins/gopher/agents/opencode/`\n- Structural and forward tests: `tests/`\n- Architecture notes: `docs/`\n\n## Skills and ownership\n\nEach request has one primary owner. Skills exchange stable `gopher:` and\n`pattern.*`/`go.*` identifiers through textual handoffs; no skill depends on a\nrelative path into a peer.\n\n| Skill | Primary ownership |\n|---|---|\n| `design-patterns` | Language-agnostic code/module pattern diagnosis and selection; peers reverse-hand off open pattern forces |\n| `application-architecture` | Language-agnostic internal application boundaries |\n| `developer` | Config-aware, local and reversible Go implementation with adaptive test-first evidence; hands broad modernization and specialist work to their canonical owners |\n| `architecture` | Go packages, modules/workspaces, dependency direction, seams, and public APIs |\n| `concurrency` | Goroutine lifetime, channels, synchronization, context, races, deadlocks, leaks, and backpressure mechanics |\n| `performance` | Asymptotic and algorithmic cost, allocations, GC, cache behavior, parsing, I/O amplification, benchmarks, profiles, latency, and throughput |\n| `diagnose` | Evidence-driven attribution of unexplained Go symptoms |\n| `security` | Go threat modeling, reachability, safe verification, remediation, debug and profiling endpoint exposure, and the ruling on what a telemetry attribute may carry |\n| `review` | Read-only exact-mode review fan-out, consolidation, and verdict |\n| `config` | The `.gopher-plugin.toml` project contract: bootstrap, validation, explanation, migration, and schema evolution |\n| `complexity` | Cyclomatic/cognitive complexity, hotspots, reduction plans, and complexity CI policy |\n| `test-quality` | Coverage, mutation, test effectiveness, and refactoring safety nets |\n| `modernize` | Declared-version-aware Go language, API, module, dependency, and toolchain modernization |\n| `refactor` | Repository-wide or multidimensional refactoring orchestration, sequencing, and evidence |\n| `doctor` | Proactive readiness of the project, configuration, toolchain, module state, generated output, and a pending action against known invariants |\n| `resilience` | Failure semantics, runtime safeguards, distributed degradation, recovery, and explicit reliability assessment |\n| `observability` | Telemetry contracts and instrumentation for logs, metrics, traces, profile exposure, dashboards, alerts, correlation, cardinality, and redaction application |\n| `codegen` | Lifecycle and trustworthiness of generated code: inventory, provenance, reproduction, staleness, and artifact verification |\n| `cgo` | Go/C boundaries: ABI and representation, ownership and lifetime, pointer rules, callbacks and thread affinity, linking, and build matrices |\n| `fuzz` | Native Go fuzz targets and invariants, seed corpora, bounded campaigns, crash triage, and regression promotion |\n\n## Agents\n\nGopher ships three packaged role agents. Each one is a thin wrapper over a\ncanonical skill: the agent carries the binding and the constraint envelope, and\nthe skill keeps the workflow, the evidence discipline, and the output. The agents\nadd no ownership row and no orchestrator, so each one's primary owner stays the\nskill it wraps.\n\n| Agent | Skill | Markdown binding | Codex binding | OpenCode binding | Declared edit envelope |\n|---|---|---|---|---|---|\n| `developer` | `gopher:developer` | `sonnet`, effort `medium` | sandbox `workspace-write` | `gopher-developer` subagent | local and reversible, inside one package |\n| `architect` | `gopher:architecture` | `opus`, effort `high` | sandbox `read-only` | `gopher-architect` subagent, `edit: deny` | existing files only, under an explicit approval; never creates a file |\n| `reviewer` | `gopher:review` | `opus`, effort `high` | sandbox `read-only` | `gopher-reviewer` primary agent, `edit: deny` | none |\n\nThe markdown dialect binds the model, the reasoning effort, and the tool set. The\nCodex agent dialect accepts `name`, `description`, `sandbox_mode`, and\n`developer_instructions` and nothing else, so a Codex agent binds the sandbox\nalone and its model and reasoning effort stay whatever the session carries.\n\nThe last column states what each agent is instructed to do, not what a host\nprevents. All three agents retain `Bash`, and `Bash` can write, so outside the\nCodex `read-only` sandbox these envelopes rest on the agent instructions rather\nthan on the host.\n\nClaude Code and Grok Build load `plugins/gopher/agents/*.md`, and Codex loads\n`plugins/gopher/agents/codex/*.toml`.\nOpenCode loads the native agent definitions through the package config hook. All\nthree OpenCode roles inherit the session model and variant; `gopher-reviewer` is\na primary agent so it can dispatch read-only built-in `explore` children without\nchanging the global subagent-depth setting.\nKimi Code does not load packaged plugin agents, so the Kimi review and refactor\nadapters restate the constraint envelope inline as instruction text with no\nbinding behind it at all: the review adapter dispatches through the runtime\n`Agent` and `AgentSwarm` tools, and the refactor adapter through `Agent`.\n\nThe definitions shipped in the package are the authoritative binding: the host\nreads them when it loads the agent, so a project file cannot rebind the model,\nthe effort, or the tools an agent actually receives. The `[agents]` table of\n`.gopher-plugin.toml` is the project's declared policy — disable the roster,\nbound the reviewer's parallel window, tighten the authorization gate.\nIt may narrow an agent and it can never widen one.\nEvery agent reports a `policy_status` of `NOT_CONFIGURED`, `ALIGNED`,\n`DIVERGED`, `UNVERIFIABLE`, or `BLOCKED_BY_POLICY`, so a declared value is never\npresented as an applied one.\n\n## Install locally in Codex\n\nFrom this repository root, add the local marketplace and install the plugin:\n\n```bash\ncodex plugin marketplace add .\ncodex plugin add gopher@alvadorncorp\n```\n\nThen start a new Codex CLI session or open a new Codex task in the desktop app\nso the installed plugin snapshot is loaded.\n\nFor desktop installation through the plugin browser, add the marketplace with\nthe same `codex plugin marketplace add .` command, restart the ChatGPT desktop\napp, open **Plugins** from Codex or Work mode, choose the `alvadorncorp`\nmarketplace, and install **Gopher**.\n\nTo confirm Codex can see the marketplace and plugin:\n\n```bash\ncodex plugin marketplace list\ncodex plugin list\n```\n\n## Install locally in Claude Code\n\nFrom this repository root, add the local marketplace and install the plugin:\n\n```bash\nclaude plugin marketplace add . --scope user\nclaude plugin install gopher@alvadorncorp --scope user\n```\n\nUse `--scope project` instead of `--scope user` when the marketplace or\ninstallation should be declared for the current project, or `--scope local` for\nmachine-local project state. Start a new Claude Code session after installation.\n\nFor development without installing from the marketplace, load the plugin only\nfor the current Claude Code session:\n\n```bash\nclaude --plugin-dir ./plugins/gopher\n```\n\nTo confirm Claude Code can see the plugin:\n\n```bash\nclaude plugin marketplace list\nclaude plugin list\n```\n\n## Install locally in Grok Build\n\nFrom this repository root, add the local marketplace and install the plugin:\n\n```bash\ngrok plugin marketplace add .\ngrok plugin install gopher --trust\n```\n\nThen enable the plugin if it is listed as disabled (`grok plugin enable gopher`\nor Space in the Plugins tab) and start a new Grok session, or press `r` in the\nPlugins tab to reload.\n\nFor development without installing from the marketplace, load the plugin for a\nsingle process with `--plugin-dir`:\n\n```bash\ngrok agent --plugin-dir ./plugins/gopher --no-leader stdio\n```\n\nTo confirm Grok can see the marketplace and plugin:\n\n```bash\ngrok plugin marketplace list\ngrok plugin list\ngrok plugin validate plugins/gopher\n```\n\n## Install locally in Kimi Code\n\nFrom this repository root, install the plugin from the local directory inside a\nKimi Code session:\n\n```text\n/plugins install ./plugins/gopher\n```\n\nAlternatively, browse the local marketplace catalog and install from it:\n\n```text\n/plugins marketplace ./.kimi-plugin/marketplace.json\n```\n\nKimi Code installs plugins per user and copies the plugin to\n`$KIMI_CODE_HOME/plugins/managed/gopher/`; editing this repository after\ninstallation has no effect until you reinstall. Run `/reload` or start a new\nsession so the installed plugin snapshot is loaded.\n\nTo confirm Kimi Code can see the plugin:\n\n```text\n/plugins list\n/plugins info gopher\n```\n\n## Install in OpenCode\n\nInstall the published package for the current project:\n\n```bash\nopencode plugin @alvadorncorp/gopher\n```\n\nFor local development from this repository root, install the local package into\nthe current project instead:\n\n```bash\nopencode plugin \"$(pwd)\"\n```\n\nAdd `--global` to either command to install it in the user configuration. Quit\nand restart OpenCode after installation or an update because plugins and skills\nare loaded at startup. Verify the installed package configuration with:\n\n```bash\nopencode debug config\n```\n\nThen start an OpenCode session and select `gopher-reviewer` when you need an\nexplicit read-only multi-lens review.\n\n## Use Gopher\n\nAfter installation, ask naturally for Go engineering help or select a bundled\nskill explicitly. Codex can route from the prompt or from an installed plugin\nskill. Claude Code and Grok Build expose plugin skills as namespaced commands\nsuch as `/gopher:review --mode full`. Kimi Code routes from the prompt or from\nexplicit skill invocation such as `/skill:review`. OpenCode exposes the skills\nby their canonical names, such as `review`; it does not apply a `gopher:`\nnamespace, so users must avoid duplicate skill names in their OpenCode setup.\n\nExamples:\n\n- `Diagnose this Go problem before proposing a fix.`\n- `Choose an idiomatic pattern for this Go design.`\n- `Review this Go change with --mode tests,security.`\n- `Coordinate a repository-wide refactor that reduces complexity and modernizes APIs together.`\n\nReview lenses are `correctness`, `tests`, `security`, `architecture`,\n`concurrency`, `performance`, and `complexity`. `--mode full` selects all seven.\nA comma-separated mode selects exactly that subset. Without a mode, `review`\nrecommends lenses and waits for confirmation before dispatch.\n\n## Project configuration\n\nThe optional `.gopher-plugin.toml` project contract lets repositories declare\nmodule roots, package patterns, complexity thresholds, test-quality targets,\nmodernization policy, refactor safeguards, and tool selection. The default\ntemplate lives at:\n\n```text\nplugins/gopher/skills/config/templates/default.gopher-plugin.toml\n```\n\nUse the `config` skill to bootstrap, validate, or explain the effective project\nconfiguration. The current schema version `5` includes the `[developer]` policy\ntable and the `[workflow]` session policy table:\n\n```toml\n[developer]\nidiom_policy = \"latest-compatible\"\ntest_workflow = \"adaptive-tdd\"\n\n[workflow]\nplanning_preflight = [\"architecture:triage\"]\nplanning_require_structure_decision = false\nimplementation_owner = \"developer\"\npost_implementation_review = \"off\"\npost_implementation_lenses = \"heuristic\"\nmax_auto_review_files = 20\n```\n\n`idiom_policy` accepts `latest-compatible`, `project-aligned`, or\n`explicit-only`; `test_workflow` accepts `adaptive-tdd`, `strict-tdd`, or\n`test-after`. The defaults are `latest-compatible` and `adaptive-tdd`.\nEach developer key resolves independently in this order: an explicit\ncurrent-session instruction, `.gopher-plugin.toml`, adopted project\nconfiguration and commands, then the Gopher default.\n\nThe `[workflow]` keys are session policy hints only. They do not install hooks,\ndo not mutate the tree, and cannot widen packaged agent bindings.\n`post_implementation_review` accepts `off`, `recommend`, or `auto` (default\n`off`). Planning modes include `architecture` triage and `refactor` plan;\ndevelopment modes include `review` auto/delta after local implementation when\nthe host session honors the policy.\n\nSchema versions `1`, `2`, `3`, and `4` keep working as `MIGRATION_AVAILABLE`.\nBefore migration, missing `[developer]` and `[workflow]` values use the\ndefaults without writing them to the project. Only a confirmed\n`config --bootstrap` migration persists the schema version `5` additions; it\npreserves existing values. The developer workflow uses these policies for local\nimplementation and its focused test evidence. It does not perform broad\nmodernization or rewrite unrelated code; those remain with the appropriate\nspecialist skill.\n\n## Development and validation\n\nRun deterministic gates:\n\n```bash\npython3 tests/validate_repo.py\npython3 -m unittest discover -s tests -p 'test_*.py'\npython3 \"${CODEX_HOME:-$HOME/.codex}/skills/.system/plugin-creator/scripts/validate_plugin.py\" plugins/gopher\nclaude plugin validate . --strict\ngrok plugin validate plugins/gopher\nnode --check plugins/gopher/opencode/plugin.js\npython3 tests/run_forward_tests.py --validate-only\n```\n\nLive forward tests require authenticated local harnesses and installed Codex,\nClaude Code, Grok Build, Kimi Code, and/or OpenCode plugin snapshots:\n\n```bash\npython3 tests/run_forward_tests.py --harness codex --harness claude --harness grok --harness kimi --harness opencode\n```\n\nReview official, version-sensitive Go references after every stable Go release\nand at least quarterly. All repository documentation is written in English.\n\n## License\n\nMIT - see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}