@wefter/opencode 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 - 2026-06-02
+
+Initial public release of Wefter for OpenCode.
+
+- Added the `wefter` CLI for installing and validating OpenCode workflow packs.
+- Added documentation audit workflow generation, profile import, profile scaffolding, and doctor validation.
+- Added documentation repair workflow generation from validated audit reports.
+- Added work-unit implementation workflow generation and task/review guard validation.
+- Added reusable OpenCode agents, skills, commands, workflow manifests, prompt templates, and schemas.
+- Added path-safety checks and automated CLI tests for core workflow operations.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wuerike
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# Wefter for OpenCode
+
+Wefter installs reusable OpenCode workflows that weave product intent into audited specs, executable tasks, and validated implementation.
+
+## Status
+
+Early product extraction. The package is usable locally for `documentation-audit`, `documentation-repair`, and `work-unit-implementation`; the other workflows are architecture scaffolds.
+
+## Package
+
+```text
+package: @wefter/opencode
+repo: opencode-wefter
+cli: wefter
+config: wefter.config.json
+local workflow files: .wefter/
+runtime artifacts: .audit/wefter/
+```
+
+## Workflows
+
+| Workflow ID | Status | Purpose |
+| --- | --- | --- |
+| `product-shaping` | Planned | Shape an initial idea into product docs, scope and explicit decisions. |
+| `documentation-audit` | Available | Run redundant, adversarial documentation consistency audits. |
+| `documentation-repair` | Available | Repair docs from a validated audit report without mixing detection and correction. |
+| `technical-shaping` | Planned | Convert product docs into explicit technical decisions and implementation constraints. |
+| `work-unit-implementation` | Available | Generate planning runs, orchestrate plan review, enforce task/review guards, and validate a work unit. |
+
+## Local Development
+
+```bash
+npm run check
+node bin/wefter.js --help
+```
+
+Install into another project from this checkout:
+
+```bash
+node <path-to-opencode-wefter>/bin/wefter.js init --target <path-to-project> --yes
+```
+
+## Intended User Flow
+
+```bash
+npx @wefter/opencode init
+```
+
+Restart OpenCode, then use:
+
+```text
+/wefter-generate-doc-audit-profile
+/wefter-audit-docs
+/wefter-repair-docs
+/wefter-run-work-unit
+```
+
+CLI checks are also available:
+
+```bash
+wefter doctor
+wefter docs audit --passes-per-lens 1 --max-audits 12
+wefter docs audit --profile-path docs/audits/lenses.json --passes-per-lens 1 --max-audits 12
+wefter profile import --source docs/audits/lenses.json --force
+wefter docs repair --audit-report .audit/wefter/documentation-audit/<run-id>/final/final-documentation-audit-report.md
+wefter new-run documentation-audit --passes-per-lens 1 --max-audits 12
+```
+
+## Default Config
+
+```json
+{
+  "version": 1,
+  "workflowRoot": ".wefter/workflows",
+  "profilePath": ".wefter/workflows/documentation-audit/profile.json",
+  "artifactRoot": ".audit/wefter/documentation-audit",
+  "templateRoot": ".wefter/workflows/documentation-audit/templates",
+  "processDocPath": ".wefter/workflows/documentation-audit/README.md",
+  "runnerCommand": "node <path-to-wefter>/bin/wefter.js",
+  "workflows": {
+    "product-shaping": { "status": "planned", "enabled": false },
+    "documentation-audit": { "status": "available", "enabled": true },
+    "documentation-repair": { "status": "available", "enabled": true },
+    "technical-shaping": { "status": "planned", "enabled": false },
+    "work-unit-implementation": {
+      "status": "available",
+      "enabled": true,
+      "configPath": ".wefter/workflows/work-unit-implementation/config.json",
+      "profilePath": ".wefter/workflows/work-unit-implementation/profile.json"
+    }
+  }
+}
+```
+
+## Safety Model
+
+- Installed audit agents render permissions using the configured artifact root and profile path.
+- `docs audit` writes through a staging directory and only moves the final run after all files are generated.
+- `docs audit --profile-path` can use a repository-specific audit profile for one run without changing `wefter.config.json`.
+- `profile import` validates and copies an existing repository-relative audit profile into the configured Wefter profile path.
+- `docs repair` writes through a staging directory and requires an existing repository-relative audit report path.
+- Paths in `wefter.config.json` must be relative to the target repository and must not contain `..`.
+- Run names are plain directory names and cannot contain path separators.
+- Audit execution must not edit source documentation; correction is a separate workflow.
+- Repair execution must pause when validated findings require unresolved human decisions.
+
+## Product Direction
+
+Next steps before a stable release:
+
+1. Add installation manifest/uninstall support.
+2. Harden release and package publishing automation.

package/bin/wefter.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli/main.js";
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/docs/ARCHITECTURE.md

@@ -0,0 +1,79 @@
+# Architecture
+
+Wefter separates reusable workflow infrastructure from repository-specific product, documentation and implementation intent.
+
+## Reusable Engine
+
+The reusable engine contains:
+
+- CLI command runner.
+- Workflow manifests.
+- OpenCode agents and skills.
+- Generic prompt templates.
+- Config, profile and run schemas.
+
+These files must not encode any single product domain.
+
+## Local Configuration
+
+`wefter.config.json` stores installation choices for one repository:
+
+- `workflowRoot`: versioned Wefter workflow files installed in the target repository.
+- `artifactRoot`: generated runtime output root for the currently available documentation audit workflow.
+- `profilePath`: project-specific documentation audit profile.
+- `templateRoot`: installed documentation audit prompt templates.
+- `processDocPath`: installed workflow documentation.
+- `runnerCommand`: command used by OpenCode orchestrators to invoke Wefter.
+- `workflows`: registry of available and planned workflow IDs, with workflow-specific paths such as work-unit `configPath` and `profilePath`.
+
+Paths are repository-relative and validated before use.
+
+## Workflow Modules
+
+Workflow modules live under `src/workflows/<workflow-id>/` and expose `workflow.json` as their contract. The initial architecture registers:
+
+- `product-shaping`
+- `documentation-audit`
+- `documentation-repair`
+- `technical-shaping`
+- `work-unit-implementation`
+
+`documentation-audit` is executable end-to-end through the CLI. `documentation-repair` generates gated repair runs from validated audit reports. `work-unit-implementation` can generate planning runs, install OpenCode agents, enforce deterministic task/review guards and validate completed work units.
+
+## Documentation Audit Run
+
+`wefter docs audit` reads config and profile, then writes a run under the configured artifact root.
+
+Run generation uses staging:
+
+```text
+<artifactRoot>/.tmp/<run-id>/
+  -> <artifactRoot>/<run-id>/
+```
+
+This avoids exposing partially generated final runs after an interrupted creation.
+
+## Documentation Repair Run
+
+`wefter docs repair --audit-report <path>` reads config and creates a run under `.audit/wefter/documentation-repair/`.
+
+Repair runs contain prompts for planning, applying approved repairs and reviewing the repaired documentation. The generated flow separates safe documentation edits from human-decision items and recommends a follow-up audit after repair.
+
+## OpenCode Integration
+
+The installer writes:
+
+- `.opencode/agent/wefter-doc-audit-orchestrator.md`
+- `.opencode/agent/wefter-doc-auditor.md`
+- `.opencode/agent/wefter-doc-audit-consolidator.md`
+- `.opencode/agent/wefter-doc-audit-validator.md`
+- `.opencode/agent/wefter-doc-audit-profile-builder.md`
+- `.opencode/agent/wefter-doc-repair-orchestrator.md`
+- `.opencode/agent/wefter-doc-repair-planner.md`
+- `.opencode/agent/wefter-doc-repairer.md`
+- `.opencode/agent/wefter-doc-repair-reviewer.md`
+- `.opencode/skills/documentation-audit/SKILL.md`
+- `.opencode/skills/documentation-repair/SKILL.md`
+- `opencode.json` commands `/wefter-audit-docs`, `/wefter-generate-doc-audit-profile`, `/wefter-repair-docs` and `/wefter-run-work-unit`
+
+OpenCode must be restarted after installation because configuration is loaded once at startup.

package/docs/INSTALLATION.md

@@ -0,0 +1,46 @@
+# Installation
+
+From a published package:
+
+```bash
+npx @wefter/opencode init
+```
+
+From a local checkout:
+
+```bash
+node <path-to-opencode-wefter>/bin/wefter.js init --target <path-to-project> --yes
+```
+
+Then restart OpenCode and run:
+
+```text
+/wefter-generate-doc-audit-profile
+/wefter-audit-docs
+/wefter-repair-docs
+/wefter-run-work-unit
+```
+
+Validate an installation with:
+
+```bash
+wefter doctor
+```
+
+Import an existing repository-specific documentation audit profile, such as a legacy `docs/audits/lenses.json`, with:
+
+```bash
+wefter profile import --source docs/audits/lenses.json --force
+```
+
+Run a one-off audit with a repository-specific profile without changing config:
+
+```bash
+wefter docs audit --profile-path docs/audits/lenses.json --passes-per-lens 1 --max-audits 12
+```
+
+Generate a documentation repair run from a validated audit report with:
+
+```bash
+wefter docs repair --audit-report .audit/wefter/documentation-audit/<run-id>/final/final-documentation-audit-report.md
+```

package/docs/SAFETY_MODEL.md

@@ -0,0 +1,17 @@
+# Safety Model
+
+Wefter workflows are designed as gated loops, not free-form agent prompts.
+
+Core rules:
+
+- Detection and correction are separate workflows.
+- Documentation audit agents must not edit source documentation.
+- Documentation repair must plan before editing and pause on unresolved human decisions.
+- Runtime artifacts are written under `.audit/wefter/` by default.
+- Versioned workflow configuration is written under `.wefter/` by default.
+- Paths are target-repository relative and must not contain `..`.
+- Run directories are staged before becoming visible as final runs.
+- OpenCode agent permissions restrict write access to configured artifact paths.
+- Implementation work must be task-level, reviewed and validated before moving to the next work unit.
+
+OpenCode must be restarted after installing or changing agents, skills or commands.

package/docs/WORKFLOWS.md

@@ -0,0 +1,13 @@
+# Workflows
+
+Wefter workflow IDs are stable nouns. CLI and OpenCode commands use verbs.
+
+| Workflow ID | CLI | OpenCode | Status |
+| --- | --- | --- | --- |
+| `product-shaping` | `wefter product shape` | `/wefter-shape-product` | Planned |
+| `documentation-audit` | `wefter docs audit` | `/wefter-audit-docs` | Available |
+| `documentation-repair` | `wefter docs repair` | `/wefter-repair-docs` | Available |
+| `technical-shaping` | `wefter technical shape` | `/wefter-shape-technical` | Planned |
+| `work-unit-implementation` | `wefter work-unit run`, `wefter work-unit guard` | `/wefter-run-work-unit` | Available |
+
+The first implementation release keeps `documentation-audit` executable and registers the full architecture. `documentation-repair` can generate repair runs from final audit reports with planning, human-decision gates, repair application and review prompts. `work-unit-implementation` can generate planning runs, orchestrate plan review, enforce deterministic task/review guards and validate a completed work unit.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@wefter/opencode",
+  "version": "0.1.0",
+  "description": "Installable Wefter workflows for OpenCode projects.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Wuerike/wefter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Wuerike/wefter/issues"
+  },
+  "homepage": "https://github.com/Wuerike/wefter#readme",
+  "bin": {
+    "wefter": "bin/wefter.js"
+  },
+  "scripts": {
+    "check": "node --check bin/wefter.js && node --check src/cli/main.js",
+    "doctor:self": "node bin/wefter.js --help",
+    "test": "node --test"
+  },
+  "keywords": [
+    "opencode",
+    "wefter",
+    "documentation",
+    "audit",
+    "workflow",
+    "llm"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "schemas/",
+    "docs/",
+    "CHANGELOG.md",
+    "README.md"
+  ]
+}

package/schemas/documentation-audit-profile.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wefter.dev/schemas/documentation-audit-profile.schema.json",
+  "type": "object",
+  "required": ["version", "corpus", "variants", "lenses"],
+  "properties": {
+    "version": { "const": 1 },
+    "corpus": {
+      "type": "object",
+      "required": ["include", "exclude"],
+      "properties": {
+        "include": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "exclude": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "additionalProperties": false
+    },
+    "variants": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "instruction"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "title": { "type": "string", "minLength": 1 },
+          "instruction": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "lenses": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "focus"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "title": { "type": "string", "minLength": 1 },
+          "focus": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/run-manifest.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wefter.dev/schemas/run-manifest.schema.json",
+  "type": "object",
+  "required": ["version", "runId", "generatedAt", "paths"],
+  "properties": {
+    "version": { "const": 1 },
+    "workflowId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "runId": { "type": "string", "minLength": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "paths": { "type": "object" }
+  },
+  "additionalProperties": true
+}

package/schemas/wefter.config.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wefter.dev/schemas/wefter.config.schema.json",
+  "type": "object",
+  "required": ["version", "workflowRoot", "profilePath", "artifactRoot", "templateRoot", "processDocPath", "runnerCommand", "workflows"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "workflowRoot": { "type": "string", "minLength": 1 },
+    "profilePath": { "type": "string", "minLength": 1 },
+    "artifactRoot": { "type": "string", "minLength": 1 },
+    "templateRoot": { "type": "string", "minLength": 1 },
+    "processDocPath": { "type": "string", "minLength": 1 },
+    "runnerCommand": { "type": "string", "minLength": 1 },
+    "workflows": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["status", "enabled"],
+        "properties": {
+          "status": { "enum": ["available", "planned"] },
+          "enabled": { "type": "boolean" },
+          "profilePath": { "type": "string", "minLength": 1 },
+          "configPath": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/work-unit-config.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wefter.dev/schemas/work-unit-config.schema.json",
+  "type": "object",
+  "required": ["version", "workflowName", "releaseId", "workUnitsDocument", "sourceDocs", "runArtifactsRoot", "versionedArtifacts", "defaultWorkUnitId", "defaultPlanAuditPassesPerLens", "gatePolicy"],
+  "properties": {
+    "version": { "const": 1 },
+    "workflowName": { "const": "work-unit-implementation" },
+    "releaseId": { "type": "string", "minLength": 1 },
+    "workUnitsDocument": { "type": "string", "minLength": 1 },
+    "sourceDocs": {
+      "type": "object",
+      "required": ["include", "exclude"],
+      "properties": {
+        "include": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "exclude": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "additionalProperties": false
+    },
+    "runArtifactsRoot": { "type": "string", "minLength": 1 },
+    "versionedArtifacts": {
+      "type": "object",
+      "required": ["executionRoot", "decisionLogRoot"],
+      "properties": {
+        "executionRoot": { "type": "string", "minLength": 1 },
+        "decisionLogRoot": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "defaultWorkUnitId": { "type": "string", "minLength": 1 },
+    "defaultPlanAuditPassesPerLens": { "type": "integer", "minimum": 1 },
+    "gatePolicy": {
+      "type": "object",
+      "required": ["mode", "structuralWorkUnits", "alwaysPauseOn"],
+      "properties": {
+        "mode": { "type": "string", "minLength": 1 },
+        "structuralWorkUnits": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "alwaysPauseOn": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/work-unit-profile.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wefter.dev/schemas/work-unit-profile.schema.json",
+  "type": "object",
+  "required": ["version", "variants", "lenses"],
+  "properties": {
+    "version": { "const": 1 },
+    "variants": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "instruction"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "title": { "type": "string", "minLength": 1 },
+          "instruction": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "lenses": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "focus"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "title": { "type": "string", "minLength": 1 },
+          "focus": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/work-unit-review-result.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wefter.dev/schemas/work-unit-review-result.schema.json",
+  "type": "object",
+  "required": ["taskId", "result", "reviewIteration", "blockingFindings"],
+  "properties": {
+    "taskId": { "type": "string", "minLength": 1 },
+    "result": { "enum": ["Pass", "Needs Fix", "Blocked"] },
+    "reviewIteration": { "type": "integer", "minimum": 1 },
+    "blockingFindings": { "type": "array", "items": { "type": "string" } }
+  },
+  "additionalProperties": false
+}

package/schemas/workflow-manifest.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wefter.dev/schemas/workflow-manifest.schema.json",
+  "type": "object",
+  "required": ["id", "status", "title", "summary", "commands"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "status": { "enum": ["available", "planned"] },
+    "title": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string", "minLength": 1 },
+    "commands": {
+      "type": "object",
+      "properties": {
+        "cli": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "opencode": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": true
+}