feat(opencode): improve reviewability guidance

.oc_local/rules/project-release-source.md

@@ -10,7 +10,6 @@ release that consuming repositories mount at `.opencode/`.
 - Shared commands belong in `commands/`.
 - Shared skills belong in `skills/`.
 - Shared helper scripts belong in `ai-scripts/`.
-- Shared plugin source belongs in `plugin/`.
 - Shared MCP runtime config belongs in root release paths such as
   `playwright-mcp.json` when `opencode.json` references it.
 - Release documentation source belongs in `README_release.md` when it is meant
@@ -23,7 +22,7 @@ release that consuming repositories mount at `.opencode/`.
 - Do not add or update `.opencode/rules/*`, `.opencode/commands/*`,
   `.opencode/skills/*`, or `.opencode/ai-scripts/*` unless the task explicitly
   targets the release/submodule state.
-- When a shared rule, command, skill, script, or plugin changes, make the source
+- When a shared rule, command, skill, or script changes, make the source
   change in the matching root directory and let the release workflow propagate
   it to `.opencode/`.
 

.oc_local/rules/readme-release.md

@@ -22,14 +22,12 @@ Use this rule when creating or updating `README_release.md`.
   release changes setup, commands, rule loading, submodule expectations, local
   overlays, or workflow contracts.
 - The upstream workflow for adding generic shared commands, rules, skills,
-  scripts, plugin files, or release documentation to this agent kit.
+  scripts, config files, or release documentation to this agent kit.
 - Agent startup guidance that applies inside consuming repositories.
 - High-value shared commands that consumers should prefer for git, memory, task,
   submodule, and release-related workflows.
 - Commit, git safety, GitHub CLI, documentation, memory, and local-rule guidance
   that consumers need immediately.
-- Optional subsystem notes, such as Graphify, when they affect how consumers
-  should use the released workspace.
 - Maintainer notes for this source repository only when they explain how the
   release branch is generated, tested, or synchronized.
 - Troubleshooting entries for common release-submodule issues.

INDEX.md

@@ -5,7 +5,7 @@ Agent-owned navigation map for the shared OpenCode workspace.
 ## When To Read This
 
 - Read this when starting work in the shared agent kit or when looking for the
-  right command, rule, skill, or plugin file.
+  right command, rule, or skill file.
 - In this source repository and consuming repositories, `opencode.json` loads
   this as the repository-root `INDEX.md`.
 
@@ -15,12 +15,11 @@ Agent-owned navigation map for the shared OpenCode workspace.
 - `commands/` - reusable slash-command workflow definitions.
 - `rules/` - durable instructions loaded by `opencode.json`.
 - `skills/` - specialized workflows that can be loaded on demand.
-- `plugin/` - optional Graphify OpenCode integration.
 - `docs/tasks/` - source-repository task guide and local implementation specs for
   accepted work.
 - `.github/workflows/ci.yml` - read-only contributor CI that runs `task test`.
 - `opencode.json` - runtime configuration that loads shared instructions,
-  plugins, MCP servers, and permissions.
+  MCP servers, and permissions.
 - `playwright-mcp.json` - Playwright MCP browser launch configuration copied
   into the generated release bundle.
 - `README.md` - source-repository overview for maintainers.

README.md

@@ -45,8 +45,7 @@ multiple repositories via a checked-out `.opencode/` directory.
 Consuming repositories should add the generated `release` branch as their
 `.opencode` submodule. The release branch contains only the files needed at
 runtime: `.gitignore`, `LICENSE`, `README.md`, `opencode.json`,
-`playwright-mcp.json`, `ai-scripts/`, `commands/`, `rules/`, `skills/`, and
-`plugin/`.
+`playwright-mcp.json`, `ai-scripts/`, `commands/`, `rules/`, and `skills/`.
 
 ```bash
 git submodule add -b release <repository-url> .opencode
@@ -110,8 +109,7 @@ analysis flows should live in local overlays such as:
 - Commands: see `commands/README.md`
 - Rules: see `rules/README.md`
 - Skills: currently `skills/gh-auth/SKILL.md`,
-  `skills/commit-message-guard/SKILL.md`, and
-  `skills/graphify/SKILL.md`
+  `skills/commit-message-guard/SKILL.md`
 - Directory indexes: `rules/directory-index.md` defines agent-owned `INDEX.md`
   files for navigable local context in large directories. A repository-root
   `INDEX.md` lists known directory indexes and is loaded by `opencode.json`

README_release.md

@@ -2,12 +2,12 @@
 
 This repository provides a reusable OpenCode workspace that consuming git
 repositories mount as a `.opencode` submodule. It gives an LLM coding agent a
-shared set of rules, commands, skills, helper scripts, and OpenCode plugin
+shared set of rules, commands, skills, helper scripts, and OpenCode runtime
 configuration while leaving project-specific behavior in the consuming repo.
 
 ## What This Submodule Provides
 
-- `opencode.json` loads the shared instructions, MCP servers, plugin files, and
+- `opencode.json` loads the shared instructions, MCP servers, and
   external-directory permissions expected by OpenCode.
 - `opencode.json` can load a repository-root `INDEX.md` owned by the consuming
   repository; the shared `.opencode` submodule does not ship that file.
@@ -18,12 +18,10 @@ configuration while leaving project-specific behavior in the consuming repo.
 - `commands/` contains reusable slash-command workflows such as `/save`,
   `/commit`, `/learn`, `/update-chat`, `/git-sync`, `/rebase`, `/task`,
   `/update-index`, and `/update-submodules`.
-- `skills/` contains targeted reusable workflows, currently `gh-auth`,
-  `commit-message-guard`, and `graphify`.
+- `skills/` contains targeted reusable workflows, currently `gh-auth` and
+  `commit-message-guard`.
 - `ai-scripts/` contains helper scripts used by the commands and skills, such
   as `commit-message-guard.sh`.
-- `plugin/` contains Graphify OpenCode integration files. Graphify is optional
-  and should only build or update graphs when the user explicitly asks for it.
 - `playwright-mcp.json` contains shared browser launch settings used by the
   `playwright` MCP server in `opencode.json`.
 - `LICENSE` carries the Zero-Clause BSD terms for Codegeist-owned material in
@@ -33,7 +31,7 @@ The generated `release` branch is intentionally minimal. During release copy,
 this source file is renamed from `README_release.md` to `README.md`. The release
 branch should contain only runtime files needed by consuming repositories:
 `.gitignore`, `LICENSE`, `README.md`, `opencode.json`, `playwright-mcp.json`,
-`ai-scripts/`, `commands/`, `rules/`, `skills/`, and `plugin/`.
+`ai-scripts/`, `commands/`, `rules/`, and `skills/`.
 
 ## Changelog
 
@@ -45,9 +43,29 @@ branch should contain only runtime files needed by consuming repositories:
 - Added the canonical `0BSD` `LICENSE` to generated release bundles so the
   distributed Codegeist-owned runtime content carries its license. No consumer
   action is required beyond receiving a future submodule update.
+- Removed the shared `repomix` MCP server while keeping the Repomix CLI
+  available as a standalone analysis tool.
+- Consumer action: after updating `.opencode`, restart OpenCode. Workflows that
+  relied on Repomix MCP tools must use the CLI or a repo-local MCP configuration;
+  standalone Repomix CLI usage is unchanged.
+- Expanded AI-ready source guidance so non-trivial modules, classes, functions,
+  and blocks carry contract-level comments or docstrings and may link to focused
+  repo-owned Markdown documentation for deeper context.
+- Added operation-boundary logging guidance for scripts and source code, with
+  stable structured events, separate diagnostic and payload streams, and
+  explicit requirements for output evaluated by LLMs or automation.
+- Consumer action: after updating `.opencode`, restart OpenCode so coding agents
+  load the new reviewability rules. No repository migration is required; apply
+  the comment, documentation, and logging contract when creating or changing
+  non-trivial behavior.
 - Moved Playwright MCP snapshots, console logs, screenshots, and related output
   under the workspace-local ignored `.chrome/playwright-mcp/` directory instead
   of creating `.playwright-mcp/` at the workspace root.
+- Removed the Graphify OpenCode plugin, instruction, and skill from the shared
+  runtime bundle.
+- Consumer action: after updating `.opencode`, restart OpenCode. Consumers that
+  relied on Graphify must move that behavior to a repo-local overlay or external
+  tool; consumers that did not use Graphify require no migration.
 - Explicitly pass Playwright MCP's `--sandbox` CLI override in addition to the
   browser launch option so current `@playwright/mcp@latest` releases no longer
   add the unsupported `--no-sandbox` Chrome argument during config merging.
@@ -62,10 +80,6 @@ branch should contain only runtime files needed by consuming repositories:
 - Kept the narrow `/save` safety rule for rebased feature branches: use
   `--force-with-lease` only for the current non-base branch after fetching its
   upstream, and only when a rebase rewrote commits already present upstream.
-- Updated shared AI-ready documentation guidance to prefer detailed explanatory
-  class and function comments when they help later coding agents understand
-  behavior, inputs, outputs, side effects, failure paths, constraints, and major
-  branches.
 - Added a shared `playwright` MCP server that starts `@playwright/mcp@latest`
   through `npx` and loads `.opencode/playwright-mcp.json` for browser launch
   settings.
@@ -262,7 +276,7 @@ Expected autonomous workflow for the agent:
    create it as root-owned and unwritable to the workspace user.
 3. Implement the requested shared `command`, `rule`, `skill`, or `config` in the
    source paths of that temporary checkout: `commands/`, `rules/`, `skills/`,
-   `ai-scripts/`, `plugin/`, `opencode.json`, `playwright-mcp.json`, and
+   `ai-scripts/`, `opencode.json`, `playwright-mcp.json`, and
    `README_release.md` as applicable. For `move`, start only from the explicitly
    selected
    `.oc_local/commands/`, `.oc_local/rules/`, or `.oc_local/skills/` overlays
@@ -387,16 +401,6 @@ authentication.
 - Use `/learn` for reusable guidance that should become a durable rule.
 - Prefer updating an existing rule over adding broad or duplicative guidance.
 
-## Graphify Notes
-
-Graphify is available as an optional OpenCode aid. For normal coding tasks:
-
-- Read existing graph reports under `docs/graphify/` when they are relevant.
-- Prefer graph queries only when a matching existing `graph.json` is available.
-- Do not run graph-building commands such as `graphify install`,
-  `graphify update`, or `graphify extract` unless the user explicitly requests
-  graph generation.
-
 ## Maintaining This Shared Repository
 
 The source repository contains development-only files that are not part of the

Taskfile.yml

@@ -21,7 +21,7 @@
 #
 # Related files:
 # - README_release.md copied as README.md, LICENSE, opencode.json,
-#   playwright-mcp.json, ai-scripts/, commands/, rules/, skills/, plugin/
+#   playwright-mcp.json, ai-scripts/, commands/, rules/, skills/
 # - INDEX.md is intentionally excluded from RELEASE_PATHS because it belongs to
 #   the consuming repository root, not the generated .opencode submodule.
 
@@ -32,7 +32,7 @@ vars:
   RELEASE_REMOTE: '{{default "origin" .RELEASE_REMOTE}}'
   RELEASE_SOURCE: '{{default "HEAD" .RELEASE_SOURCE}}'
   RELEASE_WORKTREE: '{{default ".release-build" .RELEASE_WORKTREE}}'
-  RELEASE_PATHS: README_release.md LICENSE opencode.json playwright-mcp.json ai-scripts commands rules skills plugin
+  RELEASE_PATHS: README_release.md LICENSE opencode.json playwright-mcp.json ai-scripts commands rules skills
   TEST_RELEASE_DIR: '{{default "" .TEST_RELEASE_DIR}}'
 
 tasks:

commands/add-agent-kit.md

@@ -82,8 +82,8 @@ Then perform the upstream source workflow autonomously:
    create it as root-owned and unwritable to the workspace user.
 2. In the temporary source checkout, implement the smallest correct shared
    change in the source paths: `commands/`, `rules/`, `skills/`, `ai-scripts/`,
-   `plugin/`, `opencode.json`, `playwright-mcp.json`, and
-   `README_release.md` as applicable. For `move`, copy and generalize the local
+   `opencode.json`, `playwright-mcp.json`, and `README_release.md` as applicable.
+   For `move`, copy and generalize the local
    overlay content into the matching source path instead of keeping
    consumer-specific assumptions.
 3. Keep all durable repository text, command text, rule text, comments, commit

commands/create-ai-script.md

@@ -16,8 +16,10 @@ Then:
    rule, or built-in tool.
 2. If a script is justified, create the smallest useful implementation under
    `.opencode/ai-scripts/`.
-3. Keep the script non-interactive by default and make its output structured and
-   easy for future AI sessions to scan.
+3. Keep the script non-interactive by default. Emit stable structured logs for
+   start, important decisions, side effects, completion, and failures so future
+   AI sessions can reconstruct the run; keep parseable payloads separate from
+   diagnostics.
 4. Add or update `.opencode/ai-scripts/README.md` when the directory changes.
 5. Refresh `@.opencode/rules/ai-scripts.md` if the new script changes durable
    guidance.

commands/task.md

@@ -88,8 +88,11 @@ implementation pass.
 5. Outside plan mode, implement the smallest correct change. Every line of code
    must earn its place; avoid speculative abstractions, boilerplate, and broad
    rewrites.
-6. Document why non-obvious code changes exist in task notes or nearby durable
-   docs. Add code comments only when they materially improve understanding.
+6. Make changed behavior reviewable as required by the documentation and
+   scripting rules. Add or update contract-level comments and docstrings for
+   non-trivial modules, classes, functions, and blocks; link focused repo-owned
+   Markdown docs for deeper context; and add meaningful operation-boundary logs
+   where runtime behavior must be reconstructed by humans, LLMs, or automation.
 7. Update tests, documentation, task status, and implementation notes according
    to the task's acceptance criteria and repo rules.
 8. Run enough verification to prove the acceptance criteria. At minimum, run:

commands/update-documentation.md

@@ -20,9 +20,13 @@ Then:
    directly affected docs under `docs/` if that tree exists.
 3. Refresh counts, command lists, and file-path references when they are now
    stale.
-4. Keep documentation proportional; do not create a large new docs structure
+4. Create a focused Markdown document when rationale, diagrams, examples, log
+   fields, or operational detail would overload source comments. Add stable
+   repository-relative links from the source and a backlink to the relevant
+   implementation files.
+5. Keep documentation proportional; do not create a large new docs structure
    unless the change truly requires it.
-5. Report which files were updated, what changed, and any remaining manual
+6. Report which files were updated, what changed, and any remaining manual
    follow-up.
 
 Do not rewrite unrelated documentation just to make it look uniform.

commands/verify-documentation.md

@@ -13,13 +13,17 @@ $ARGUMENTS
 
 Then:
 1. Inventory the repo's current documentation surface, including `README.md`,
-   any project-memory file such as `docs/memory-bank/chat.md`, `.opencode/rules/*.md`,
+   source comments and docstrings, any project-memory file such as
+   `docs/memory-bank/chat.md`, `.opencode/rules/*.md`,
    `.opencode/commands/*.md`, and `docs/` content if present.
-2. Verify that command and rule references point to real files.
+2. Verify that command, rule, source-comment, and Markdown references point to
+   real files and useful sections.
 3. Check that command lists, file counts, and workflow descriptions still match
    the repo.
-4. Flag stale references, broken paths, contradictory guidance, and obvious
-   language-policy violations.
+4. Flag stale references, broken paths, contradictory guidance, missing
+   contract-level source context, unclear operation-boundary diagnostics, and
+   obvious language-policy violations. Pay particular attention to output that
+   an LLM or automation must evaluate.
 5. Report the result as a concise verification summary with concrete file paths
    for any issues.
 

opencode.json

@@ -22,8 +22,7 @@
     ".opencode/rules/software-tests.md",
     ".opencode/rules/task-workflow.md",
     ".opencode/rules/taskfile-and-script-creation.md",
-    ".opencode/README.md",
-    "plugin/graphify.md"
+    ".opencode/README.md"
   ],
   "watcher": {
     "ignore": [
@@ -75,20 +74,8 @@
       ],
       "enabled": true,
       "timeout": 15000
-    },
-    "repomix": {
-      "type": "local",
-      "command": [
-        "npx",
-        "-y",
-        "repomix",
-        "--mcp"
-      ]
     }
   },
-  "plugin": [
-    "plugin/graphify.js"
-  ],
   "permission": {
     "external_directory": {
       "/tmp/**": "allow"

rules/README.md

@@ -29,9 +29,11 @@ Shared AI rules intended to work across repos.
   `INDEX.md` navigation files for large directories, outside shared `.opencode`
   release content.
 - `language-policy.md` - English for code and durable repo text.
-- `ai-ready-documentation.md` - documentation standards for non-trivial files.
-- `bash-scripts.md` - minimal Bash style for repo-owned shell scripts.
-- `scripting-best-practices.md` - shell and automation guidance.
+- `ai-ready-documentation.md` - source comments, diagnostics, and documentation
+  standards for reviewable non-trivial behavior.
+- `bash-scripts.md` - direct, documented, and observable Bash style.
+- `scripting-best-practices.md` - shell automation and structured logging
+  guidance, including output consumed by LLMs.
 - `software-documentation.md` - how repo-local software documentation should be
   structured and maintained.
 - `software-tests.md` - how to write, update, and verify software tests.