@dotdotgod/opencode 0.0.0-stage → 0.6.6

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@dotdotgod/opencode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.6",
+  "description": "OpenCode V2 project memory, automatic project plans and advisory impact tracking.",
+  "type": "module",
+  "main": "./index.js",
+  "license": "Elastic-2.0",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./server": "./server.js"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.js",
+    "server.js",
+    "src",
+    "skills",
+    "commands",
+    "mcp",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "esbuild": "0.27.3",
+    "@dotdotgod/context": "0.6.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotdotgod/dotdotgod-kit.git",
+    "directory": "packages/opencode"
+  },
+  "scripts": {
+    "syntax": "node --check index.js && node --check server.js && node --check src/index.mjs && node --check src/plan.mjs && node --check src/impact.mjs && node --check src/location.mjs && node --check src/resources.mjs && node --check src/mcp.mjs && node --check scripts/smoke.mjs",
+    "test": "node --test test/*.test.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "verify": "pnpm run syntax && pnpm run test && node ../../scripts/build-adapter-runtime.mjs opencode --check",
+    "pack:dry-run": "pnpm pack --dry-run --json"
+  }
 }

package/server.js

@@ -0,0 +1 @@
+export { default } from './src/index.mjs';

package/skills/doc-first-planning/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: doc-first-planning
+description: Plan implementation from maintained docs with the native plan agent.
+---
+
+<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
+
+# Doc-First Planning
+
+Use the dotdotgod_context MCP server for project load, initialization, graph impact, execution and indexed retrieval. Discover its exact tool names in OpenCode Code Mode; inspect MCP isError and structuredContent and every execution results entry. For unknown output size use execute with a commands array and outputMode auto; search indexed.id with bounded source-scoped search. Run ancillary CLI checks through MCP execute rather than a duplicate native service. Keep direct read for short located source and images. Pending impact is advisory, never an execution gate. Preserve host permissions. Use the native plan agent, not dd:plan; concrete plans are automatically maintained in docs/plan/<task-slug>/README.md without a separate save request.
+
+## Goal
+
+Create an implementation plan from maintained repository documentation before substantial source or configuration changes.
+
+Use the native plan agent and automatically create or revise `docs/plan/<task-slug>/README.md` once a concrete implementation plan exists, without a separate save request. Initial clarification and explanation-only exchanges need no file. Use MCP project Load for focused documentation/code query.
+
+## Workflow
+
+1. Check for a matching active plan.
+2. Reuse loaded memory and the documentation map, then use focused query and README indexes to select maintained docs and verify conclusions in them.
+3. Inspect the source needed to confirm targets and constraints.
+4. Run impact review on likely changed files and refine targets, risks, and verification.
+5. Write and present the task README with scope, targets, executable steps, verification, and required completion gates.
+6. Resolve blocking decisions; stay in the native plan agent until the user switches agents. Saving is not execution approval.
+
+## Quality Rules
+
+- Prefer documented facts over inference; label inference explicitly.
+- Keep plans concise, executable, and maintainable.

package/skills/document-clarify/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: document-clarify
+description: Clarify documentation while preserving requirements and traceability.
+---
+
+<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
+
+# Document Clarify
+
+Use the dotdotgod_context MCP server for project load, initialization, graph impact, execution and indexed retrieval. Discover its exact tool names in OpenCode Code Mode; inspect MCP isError and structuredContent and every execution results entry. For unknown output size use execute with a commands array and outputMode auto; search indexed.id with bounded source-scoped search. Run ancillary CLI checks through MCP execute rather than a duplicate native service. Keep direct read for short located source and images. Pending impact is advisory, never an execution gate. Preserve host permissions. Use the native plan agent, not dd:plan; concrete plans are automatically maintained in docs/plan/<task-slug>/README.md without a separate save request.
+
+## Memory-Area Context
+
+Use `dotdotgod config <root> --json` (or the source-checkout CLI equivalent) to obtain resolved `config.areas`; reuse current resolved settings already in context when the project/config has not changed. Normalize the target to a repository-relative path. Check areas in order, applying each area's `excludePaths` before selecting the first matching `paths` entry. Keep the matched area's relevant guidance in context rather than repeatedly injecting the entire configuration. If no area matches, use the document's purpose and repository conventions without inventing metadata.
+
+## Goal
+
+Make project documentation easier to understand and act on while preserving established behavior, decisions, task state, historical meaning, and traceability.
+
+## Editing Checklist
+
+Adapted from [Google Technical Writing One](https://developers.google.com/tech-writing/one); these principles supplement repository policy. Apply them directly without requiring runtime web access.
+
+- **Audience:** distinguish what readers already know from what they need to learn or do. Add only evidence-backed context that closes that gap.
+- **Terminology:** use one consistent name per concept; explain unfamiliar terms and abbreviations when readers need them. Preserve exact API names and identifiers.
+- **Sentences:** use specific verbs and make responsibility clear. Prefer active voice when it helps; retain passive voice when appropriate and never invent an unknown actor. Keep one main idea per sentence while preserving conditions, exceptions, and logical relationships.
+- **Paragraphs:** focus each paragraph on one topic and make its main point clear near the beginning. Remove sentences that do not support that topic or relocate them within the approved scope.
+- **Lists and tables:** use numbered lists when order matters, bullets otherwise, and parallel phrasing for comparable items. Use tables when readers need to compare the same attributes across items, not merely to decorate prose.
+- **Language:** apply these principles idiomatically in the document's language. Do not impose English word order, a passive-voice ban, or sentence-length quotas on Korean or other languages.
+
+## Workflow
+
+1. Confirm the target, audience, requested outcome, and edit scope. Diagnose ambiguity, repetition, or missing information before editing; small changes need no separate diagnostic report. Use matched memory-area metadata when available: `clarify` guidance first, then `description`, `label`, and `role`.
+2. Read only the context needed to preserve meaning: the nearest README, directly linked documents, relevant query results, and targeted history when a past decision matters.
+3. Remove obsolete historical behavior and superseded conditions from current specs when maintained source, tests, or confirmed decisions establish that they no longer apply. Describe current behavior directly rather than narrating how it changed. Do not mistake currently supported compatibility behavior for obsolete history. Preserve current requirements, meaningful limitations, and unresolved uncertainty; when retirement is unverified, ask rather than delete. Preserve historical meaning in archives and reports; do not rewrite past records to look current. Apply criteria suited to the document: README navigation and starting points; spec conditions, behavior, and exceptions; test procedures and pass criteria; architecture boundaries, rationale, and constraints; plan ordering, dependencies, and completion criteria; archive decisions and outcomes in their historical context. Repository-specific guidance takes priority. Clarify terms, ownership, headings, links, and runnable examples. Preserve commands, paths, package/API names, requirement strength, conditions, exceptions, unresolved questions, limitations, and evidence unless verified sources support a change. Do not invent missing facts.
+4. Prefer direct affirmative statements. Remove repeated framing, indirect wording, mixed responsibilities, and irrelevant background. Remove negative or absence statements only when deleting them leaves the reader's understanding, actions, and decisions unchanged. Rewrite redundant contrasts affirmatively: “It is not automatic; the user starts it” becomes “The user starts it.” Preserve meaningful prohibitions, unsupported cases, exceptions, security constraints, and unverified status. Use “X is not Y; it is Z” when the contrast resolves a likely ambiguity. Accuracy takes priority over brevity.
+5. Keep edits within the agreed scope. Confirm scope before splitting or moving files, changing meaning, or editing additional documents outside that scope. Update the nearest README when approved structural changes affect navigation. Follow generated markers and canonical-source instructions. For dotdotgod traceability, edit the fenced `json dotdotgod` block as the canonical mapping. Inspect `dotdotgod traceability links <root> --check --json` before using `--write`; the root-wide write can change unrelated documents, so obtain approval if its affected files exceed the agreed scope. Apply ordinary reference policy: shared documents must not depend on concrete local file paths in inline code or Markdown links; inline-code directory, glob, and placeholder usage examples remain allowed. Preserve traceability's separate stricter local-target prohibition.
+6. Ask for a decision when the requested clarification would change established meaning or when current sources conflict.
+7. Run verification that matches the changed surface. Use documentation and traceability checks for ordinary docs; add generation checks, focused package tests, dry-runs, or workspace verification when shared resources or product behavior are affected. Report briefly: what became clearer; important meaning preserved and unresolved questions; checks run and checks not run. Do not equate shorter text with improved accuracy.
+
+When CLI-backed routing is unavailable, continue from the target document, nearest README, direct links, and repository conventions.

package/skills/impact-review/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: impact-review
+description: Review changed files and related docs/tests using graph impact.
+---
+
+<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
+
+# Impact Review
+
+Use the dotdotgod_context MCP server for project load, initialization, graph impact, execution and indexed retrieval. Discover its exact tool names in OpenCode Code Mode; inspect MCP isError and structuredContent and every execution results entry. For unknown output size use execute with a commands array and outputMode auto; search indexed.id with bounded source-scoped search. Run ancillary CLI checks through MCP execute rather than a duplicate native service. Keep direct read for short located source and images. Pending impact is advisory, never an execution gate. Preserve host permissions. Use the native plan agent, not dd:plan; concrete plans are automatically maintained in docs/plan/<task-slug>/README.md without a separate save request.
+
+## Goal
+
+Review task-relevant source, config, and documentation changes with dotdotgod impact evidence before broad verification, commits, pushes, publishing, or final handoff. OpenCode tracks observed edits per session; pending impact is advisory and never blocks tools.
+
+## Workflow
+
+1. Build the changed-file set from Git status. Preserve unrelated user work and exclude dependencies, caches, build output, secrets, and unrelated local memory.
+2. Call the shared MCP project_impact tool with up to twenty unique paths in first-seen order. Split larger sets into ordered batches of twenty. Inspect isError and structuredContent; only successful reviews of covered unchanged revisions clear pending state. Failures, cancellation and concurrent re-edits retain pending. When MCP is unavailable, follow README indexes, traceability, package metadata and focused search without claiming pending was cleared.
+3. Review the combined ranking and each seed's non-seed top results. Prioritize high-signal specs, tests, architecture, and source links, especially `implemented_by`, `verified_by`, and `related_doc` relationships.
+4. Resolve stale or contradictory related docs and tests that belong to the current task.
+5. Select focused tests, documentation validation, generated-resource checks, and package dry-runs from the evidence. For dotdotgod documentation changes, run `dotdotgod validate . --include-local-memory` and add `--check-index` when index freshness matters.
+6. Report the changed files reviewed, the strongest related findings and follow-up actions, and verification completed or skipped.
+
+Keep raw impact payloads out of normal summaries. Optional hooks may remind agents about this workflow; default package resources leave full verification, index rebuilds, initialization, archive moves, and write blocking under explicit workflow control.

package/skills/project-initializer/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: project-initializer
+description: Initialize shared project memory, documentation indexes and configuration.
+---
+
+<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
+
+# Project Initializer
+
+Use the dotdotgod_context MCP server for project load, initialization, graph impact, execution and indexed retrieval. Discover its exact tool names in OpenCode Code Mode; inspect MCP isError and structuredContent and every execution results entry. For unknown output size use execute with a commands array and outputMode auto; search indexed.id with bounded source-scoped search. Run ancillary CLI checks through MCP execute rather than a duplicate native service. Keep direct read for short located source and images. Pending impact is advisory, never an execution gate. Preserve host permissions. Use the native plan agent, not dd:plan; concrete plans are automatically maintained in docs/plan/<task-slug>/README.md without a separate save request.
+
+## Goal
+
+Create a non-destructive dotdotgod baseline with canonical agent instructions, thin agent entrypoints, documentation indexes, a project config selected from an appropriate initialization template, and local-memory ignore rules.
+
+## Template Selection
+
+1. Inspect existing agent instructions, the root README, docs indexes, major top-level directories, config, and ignore rules.
+2. Discover custom templates as individual JSON files under `~/.dotdotgod/templates/`. Built-in templates are `software`, `research`, `case-and-evidence`, `publication`, `portfolio`, and `policy`.
+3. Choose from project evidence:
+   - `software`: application, library, or infrastructure projects organized around specs, architecture, source, and tests.
+   - `research`: research diaries, dated records, reports, artifacts, and evaluation evidence.
+   - `case-and-evidence`: canonical case records, evidence or legal grounds, and case outputs.
+   - `publication`: briefs, outlines, chapters, claims, manuscripts, and research sources.
+   - `portfolio`: strategy, positions, ledgers, journals, and market research.
+   - `policy`: policy sections, integrated proposals, evidence, and submission outputs.
+4. Consider custom templates by filename and config contents. A same-name custom template replaces the built-in template completely.
+5. Ask the user when multiple choices are plausible and materially change memory areas or traceability. With insufficient evidence, use `~/.dotdotgod/config.json` `defaultTemplate`, then `software`.
+6. Report the selected template and a concise reason.
+
+## Workflow
+
+1. Preserve existing files and unrelated user work.
+2. Call the shared MCP project_initialize tool with the selected template. Keep dryRun true initially; after explicit write approval call with dryRun false and confirmWrite true. Existing files are skipped, never replaced. Switch out of the native plan agent before initialization.
+3. Use bundled scripts only as an explicit fallback when MCP is unavailable. Custom templates require the CLI; do not silently substitute a bundled template.
+4. Validate the initialized project with `dotdotgod validate <project-root>` when available.
+5. Report created and skipped files, the selected template, validation failures, and unresolved instruction conflicts.

package/skills/project-initializer/references/agent-docs.md

@@ -0,0 +1,42 @@
+# Shared Agent Docs
+
+Use `AGENTS.md` as the canonical shared instruction file.
+
+## Naming
+
+- `AGENTS.md`: preferred shared file name. OpenAI Codex recognizes this convention, and the community `agents.md` convention uses the plural form.
+- `CLAUDE.md`: Claude Code's project memory file. Keep it thin and import `AGENTS.md` with `@AGENTS.md`.
+- `CODEX.md`: project-local Codex pointer. Keep it thin and link to `AGENTS.md`.
+- OpenCode reads `AGENTS.md` natively; do not create an `OPENCODE.md` copy.
+- `.github/copilot-instructions.md`: optional Copilot surface. If present, route to `AGENTS.md`, `docs/README.md`, and project commands instead of copying the full rules body.
+- `.cursor/rules/*.md`: optional Cursor path-scoped rules. If present, keep Cursor-specific scoping there and route durable project rules to shared docs.
+- `llms.txt`: optional documentation discovery surface. If present, point to README indexes and bounded docs entrypoints instead of embedding large docs bodies.
+- `AGENT.md`: avoid for new projects unless an existing tool in the repo requires it.
+
+## Content Model
+
+Put durable, project-wide instructions in `AGENTS.md`:
+
+- project purpose and stack
+- install, test, run, and lint commands
+- architecture and ownership notes
+- documentation map
+- coding and review expectations
+- environment constraints
+
+For projects using the dotdotgod CLI, `dotdotgod validate` is the enforcement point for machine-readable docs rules such as fenced `json dotdotgod` traceability blocks in behavior specs. Keep the detailed schema in the CLI and its validation errors.
+
+Do not duplicate the same body in `CLAUDE.md`, `CODEX.md`, Copilot instructions, Cursor rules, or llms discovery surfaces; duplication causes drift.
+
+## Focused Behavior Contracts
+
+Use focused behavior contracts for user-visible rules that need clear implementation and verification links.
+
+Good focused contracts:
+
+- describe current behavior, not change history
+- stay small enough for agents to load and reason about directly
+- connect to implementation files, tests, related docs, and verification commands with a final fenced `json dotdotgod` traceability block when the project uses dotdotgod validation
+- split large product areas into `docs/spec/<domain>/README.md` plus focused UPPER_SNAKE_CASE spec files
+
+Traceability helps agents find related code and checks. It is not a semantic proof that tests cover every edge case.