@opencoven/coven-code 0.0.3 → 0.0.6

package/docs/DOGFOOD-PROTOCOL.md

@@ -1,263 +0,0 @@
-# Coven Dogfood Protocol
-
-This protocol defines how Coven is used to build Coven and CastCodes every day.
-The goal is to prove orchestration through repeated use: every meaningful task
-should leave behind a clear packet, harness assignment, handoff, verification
-record, retrospective note, and captured issue when the work exposes a product
-gap.
-
-## Operating Rules
-
-- Use Coven as the default coordination surface for Coven and CastCodes work.
-- Keep work packets small enough to finish, review, or hand off in one session.
-- Assign the narrowest harness that can prove the task, then record why.
-- Prefer evidence from the repo, runtime, tests, screenshots, logs, or GitHub.
-- Treat dogfood friction as product evidence, not background annoyance.
-- Keep public product docs, marketing copy, and visible product surfaces
-  maintainer-authored and free of provider or generation credit.
-- PR metadata, commit metadata, and required coauthor trailers remain allowed
-  when project policy requires them.
-
-## Artifact Location
-
-Store dogfood packets where future maintainers can find the proof.
-
-- For GitHub-attached work, put the task packet, handoff, verification record,
-  retrospective, and issue capture in the relevant issue, PR comment, or review
-  thread.
-- For local or non-GitHub work, put the record in a dated local dogfood log or
-  Coven session artifact. Use `.local/dogfood/YYYY-MM-DD.md` only when `.local/`
-  is ignored (for example via `.git/info/exclude` or a global gitignore), so the
-  log cannot be committed by accident.
-- For sensitive or internal-only context, keep a minimal public summary in the
-  normal artifact and store the sensitive detail in private memory or private
-  notes.
-
-## Daily Cadence
-
-1. Open the day with a queue scan across Coven and CastCodes.
-2. Select one task that improves the product or validates a current integration
-   path.
-3. Write a task packet before starting implementation or review.
-4. Assign the task to the right harness and record the expected proof.
-5. Execute the work through Coven wherever the current product surface allows.
-6. Produce a handoff packet before switching context or requesting review.
-7. Run the verification gate and attach exact commands plus results.
-8. Capture any product gap discovered during the run as an issue or backlog
-   entry.
-9. Close with a short retrospective that names one protocol adjustment, product
-   fix, or explicit no-change decision.
-
-## Task Packet
-
-Create a task packet before changing code, review state, docs, or release
-metadata.
-
-```markdown
-## Task Packet
-
-- Repo:
-- Branch/worktree:
-- Objective:
-- Trigger:
-- Current evidence:
-- Scope:
-- Out of scope:
-- Harness:
-- Required proof:
-- Risk:
-- Stop condition:
-```
-
-Field rules:
-
-- `Repo`: `OpenCoven/coven-code`, `OpenCoven/coven`,
-  `OpenCoven/cast-codes`, or another exact repo.
-- `Branch/worktree`: current branch, detached worktree label, or canonical path.
-- `Objective`: one sentence with the user-visible outcome.
-- `Trigger`: issue, PR, release need, local failure, audit item, or direct ask.
-- `Current evidence`: links, file paths, failing commands, screenshots, logs, or
-  live state that justify the task.
-- `Scope`: the smallest set of files, surfaces, or workflow steps expected to
-  change.
-- `Out of scope`: adjacent ideas that should not expand the task.
-- `Harness`: the assigned execution harness from the table below.
-- `Required proof`: commands or artifacts needed before handoff.
-- `Risk`: what could regress if this is wrong.
-- `Stop condition`: the point where the task is complete, blocked, or should be
-  handed off.
-
-## Harness Assignment
-
-Assign one primary harness per task. Add a secondary harness only when the proof
-requires a different runtime or interface.
-
-| Harness | Use For | Required Output |
-| --- | --- | --- |
-| `coven-code execute` | Deterministic CLI, SDK, thread, tool, MCP, skill, plugin, and JSON-stream checks | Command, stdout summary, exit status |
-| `coven-code panel` | Interactive panel behavior, keyboard flow, visible state, and operator ergonomics | Scripted path or screenshot plus observed result |
-| `coven runtime` | Coven CLI/runtime, daemon, socket, TUI, harness launch, and local machine capability work | Command bundle, logs, and exact runtime state |
-| `cast-codes app` | CastCodes desktop/app behavior, settings, LSP, indexing, browser panels, and UI flows | App/test command, focused screenshot or log, issue/PR link |
-| `repo tests` | Narrow implementation or regression coverage | Exact test command and pass/fail result |
-| `maintainer review` | PR review, conflict repair, release follow-through, and issue triage | Live GitHub state, review-thread state, and final blocker |
-
-Assignment rules:
-
-- Prefer `coven-code execute` for deterministic orchestration checks.
-- Prefer `coven-code panel` when operator experience is the thing being tested.
-- Prefer `coven runtime` when the task touches Coven's own Rust runtime,
-  daemon, socket, local machine capabilities, or harness launch behavior.
-- Prefer `cast-codes app` when the proof depends on the CastCodes application
-  rather than a library or CLI unit.
-- Prefer `repo tests` for the smallest code-level regression proof.
-- Prefer `maintainer review` when the task is primarily GitHub state, PR
-  cleanup, merge readiness, or issue accuracy.
-
-## Handoff Packet
-
-Produce a handoff packet before requesting review, switching harnesses, pausing,
-or closing the task.
-
-```markdown
-## Handoff Packet
-
-- Outcome:
-- Changed files:
-- Verification:
-- Product gaps found:
-- Issues captured:
-- Remaining risk:
-- Next action:
-```
-
-Field rules:
-
-- `Outcome`: shipped, reviewed, blocked, no actionable bug, or follow-up needed.
-- `Changed files`: exact paths or `none`.
-- `Verification`: exact commands and result summaries.
-- `Product gaps found`: dogfood friction observed while using Coven.
-- `Issues captured`: issue links, draft titles, or `none`.
-- `Remaining risk`: what was not proven.
-- `Next action`: the one concrete action another maintainer can take.
-
-## Verification Gate
-
-Every dogfood task needs proof proportional to the change.
-
-Minimum docs-only gate:
-
-```sh
-git diff --check
-```
-
-Minimum Coven Code gate:
-
-```sh
-git diff --check
-node ./bin/coven-code.mjs --help
-node ./bin/coven-code.mjs -x "what is 2+2?"
-npm test
-```
-
-Minimum Coven runtime gate:
-
-```sh
-cargo test
-```
-
-Add focused runtime commands that exercise the touched Coven surface, such as a
-daemon launch, socket call, TUI smoke path, or harness command construction
-check.
-
-Minimum CastCodes gate:
-
-```sh
-./script/check_ai_attribution
-./script/check_rebrand
-git diff --check
-```
-
-Add the narrow CastCodes command that proves the touched surface, such as a
-focused test target, `rustfmt --check` on changed Rust files, an app launch, or
-a screenshot-backed UI check.
-
-Run `./script/check_rebrand` when touching public docs, UI, settings,
-templates, release notes, marketing, or other user-visible surfaces. This
-protects the CastCodes product and Coven runtime framing.
-
-Verification rules:
-
-- Run the narrowest command that can fail for the changed behavior.
-- Record the exact command, result, and any known baseline noise.
-- If a broad suite fails from unrelated drift, keep the failure in the handoff
-  and add a focused passing command for the touched behavior.
-- Never mark a handoff complete when the required proof was skipped.
-
-## Retrospective
-
-End each day or substantial task with a short retrospective.
-
-```markdown
-## Retrospective
-
-- What Coven made easier:
-- What Coven made harder:
-- Missing product affordance:
-- Protocol adjustment:
-- Follow-up:
-```
-
-Retrospective rules:
-
-- Keep it concrete and tied to the day's packets.
-- Record one product gap at most unless multiple gaps blocked the work.
-- Use `none` when no issue is warranted.
-- Do not rewrite the protocol unless repeated evidence supports the change.
-
-## Issue Capture
-
-Capture an issue when dogfood use exposes a reproducible product gap, missing
-affordance, confusing handoff, unreliable harness path, or verification hole.
-
-Issue packet:
-
-```markdown
-## Dogfood Issue
-
-- Title:
-- Repo:
-- Surface:
-- Reproduction:
-- Expected:
-- Actual:
-- Evidence:
-- Severity:
-- Suggested owner:
-```
-
-Severity:
-
-- `P0`: blocks daily Coven or CastCodes work.
-- `P1`: forces a manual workaround or makes proof unreliable.
-- `P2`: slows handoff, review, or issue capture.
-- `P3`: polish, naming, or ergonomics with a clear fix path.
-
-Capture rules:
-
-- File issues from evidence, not speculation.
-- Link the task packet and handoff packet when available.
-- Keep implementation suggestions separate from the reproduction.
-- If the gap is actually a docs or protocol mismatch, patch the protocol instead
-  of opening a product issue.
-
-## Daily Closeout
-
-Use this checklist before ending a dogfood run:
-
-- Task packet exists.
-- Harness assignment is recorded.
-- Handoff packet exists or the task is explicitly still active.
-- Verification commands and results are recorded.
-- Product gaps were captured or marked `none`.
-- Retrospective note exists.
-- Next action is one concrete maintainer step.

package/docs/MCP-SKILLS-PLUGINS.md

@@ -1,127 +0,0 @@
-# MCP, Skills, and Plugins
-
-## MCP Servers
-
-Add a user or workspace MCP server:
-
-```sh
-coven-code mcp add local-tools -- node ./tools/server.mjs
-coven-code mcp add --workspace local-tools -- node ./tools/server.mjs
-```
-
-Inspect and approve servers:
-
-```sh
-coven-code mcp list
-coven-code mcp doctor
-coven-code mcp approve local-tools
-```
-
-Remote MCP servers can use headers, OAuth credentials, Streamable HTTP session
-reuse, and SSE fallback. Configured servers can also filter exposed tools.
-
-Workspace MCP servers require approval before their tools appear in stream JSON
-or tool discovery.
-
-## MCP Registry Enforcement
-
-`covenCode.mcpRegistry.url` can point to a registry of approved remote servers.
-When enabled, unlisted servers are blocked. If the registry is unreachable, MCP
-activation fails closed.
-
-This behavior is intentional: local projects should not silently connect to new
-tool endpoints when a registry policy is present.
-
-## Skills
-
-List and inspect skills:
-
-```sh
-coven-code skill list
-coven-code skill show building-skills
-```
-
-Skill discovery checks configured roots, project roots, `.agents/skills`,
-legacy `.claude/skills`, and built-in skills. Project skills take precedence
-over user-wide or legacy roots with the same name.
-
-Add one-run skill roots:
-
-```sh
-coven-code --skills ./skills -x "use the data-map skill"
-```
-
-Skill-bundled MCP tools stay hidden until the skill is referenced.
-
-## Plugins
-
-Project plugins live under:
-
-```text
-.coven-code/plugins/*.ts
-```
-
-User plugins live under:
-
-```text
-${XDG_CONFIG_HOME:-~/.config}/coven-code/plugins/*.ts
-```
-
-Inspect plugins:
-
-```sh
-coven-code plugins list
-coven-code plugins reload
-```
-
-Plugins can register:
-
-- tools
-- commands
-- `session.start` handlers
-- `agent.start` handlers
-- `agent.end` handlers
-- `tool.call` handlers
-- `tool.result` handlers
-- status items
-- configuration subscriptions
-- UI fallbacks for prompts, selects, confirms, and notifications
-
-## Tool Lifecycle Hooks
-
-Plugin `tool.call` handlers can:
-
-- allow execution
-- reject and continue with a message
-- modify input
-- synthesize a result
-- stop execution with an error
-
-Plugin `tool.result` handlers can:
-
-- preserve results
-- replace results
-- mark results as errors
-
-The helper APIs classify shell commands, modified files, unavailable UI, and
-paired tool call/result messages.
-
-## Toolbox Tools
-
-Toolbox tools are discovered from:
-
-- `COVEN_CODE_TOOLBOX`
-- `--toolbox <path>`
-- `${XDG_CONFIG_HOME:-~/.config}/coven-code/tools`
-
-Common flow:
-
-```sh
-coven-code tools make --bash my-tool
-coven-code tools list
-coven-code tools show tb__my-tool
-coven-code tools use tb__my-tool
-```
-
-Toolbox executions receive `AGENT=coven-code` and
-`COVEN_CODE_THREAD_ID=<thread-id>` in their environment.

package/docs/README.md

@@ -1,39 +0,0 @@
-# Coven Code Documentation
-
-Coven Code is a local-first Node CLI for exercising agentic command, thread,
-tool, MCP, skill, plugin, and SDK workflows without depending on a hosted
-service. The package is intentionally small and deterministic so it can be used
-as a harness for OpenCoven integration work, local demos, and regression tests.
-
-## Contents
-
-- [CLI reference](CLI.md)
-- [Configuration](CONFIGURATION.md)
-- [MCP, skills, and plugins](MCP-SKILLS-PLUGINS.md)
-- [SDK](SDK.md)
-- [Development](DEVELOPMENT.md)
-- [Coven Dogfood Protocol](DOGFOOD-PROTOCOL.md)
-- [Demo](DEMO.md)
-
-## Core Ideas
-
-- `coven-code` is the user-facing CLI.
-- `coven-code-sdk` installs or resolves a CLI binary for SDK-driven workflows.
-- Threads are persisted locally under Coven Code config/state paths.
-- Execute mode is deterministic and suitable for tests and automation.
-- Stream JSON mode mirrors the event-oriented shape expected by agent
-  frontends and SDK integrations.
-- Tools, MCP servers, skills, and plugins are local extension points.
-
-## Local Smoke Test
-
-From the repository root:
-
-```sh
-npm run coven-code -- --help
-npm run coven-code -- -x "what is 2+2?"
-npm test
-```
-
-Expected result: help prints, execute mode prints `4`, and the test suite exits
-with no failures.

package/docs/RELEASE.md

@@ -1,33 +0,0 @@
-# Coven Code Release Runbook
-
-This package publishes as `@opencoven/coven-code`.
-
-## One-time setup
-
-1. Make `OpenCoven/coven-code` public before provenance-backed publishing.
-2. Publish the first public package version manually if npm does not yet have the package. npm trusted publishing can be configured only after the package exists.
-3. Configure npm trusted publishing for GitHub Actions:
-   - Package: `@opencoven/coven-code`
-   - Repository: `OpenCoven/coven-code`
-   - Workflow filename: `release-npm.yml`
-   - Allowed action: `npm publish`
-4. Add the GitHub repository variable `NPM_RELEASE_ALLOWED_SIGNERS`.
-
-The signer variable must contain one or more SSH allowed-signers lines. For the current release key, use the Git commit signing principal and public key:
-
-```text
-68980965+BunsDev@users.noreply.github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILs6nKUsP+OVzoTXNYcZ98IePpd4j+aeuweVS/cozV8D
-```
-
-## Release
-
-1. Bump `package.json` and `package-lock.json` to the next semver version.
-2. Commit the verified release changes on the default branch.
-3. Create a signed annotated tag that matches the package version:
-
-```bash
-git tag -s v0.0.1 -m "v0.0.1"
-git push origin v0.0.1
-```
-
-The tag workflow refuses lightweight tags, unsigned tags, `v0.0.0`, mismatched package versions, tags whose target commit is not on the repository default branch, and package contents containing `.github/`, `.superpowers/`, or `test/`.

package/docs/SDK.md

@@ -1,107 +0,0 @@
-# SDK
-
-The package root exports local SDK helpers:
-
-```js
-import {
-  execute,
-  createUserMessage,
-  createPermission,
-  threads,
-} from "@opencoven/coven-code";
-```
-
-## CLI Install Helper
-
-The `coven-code-sdk` binary installs or resolves a CLI for SDK-managed runs:
-
-```sh
-coven-code-sdk install
-coven-code-sdk install --force
-```
-
-Resolution order includes:
-
-- `COVEN_CODE_CLI_PATH`
-- local npm package bins
-- `COVEN_CODE_HOME` managed bin
-- `coven-code` on `PATH`
-
-## Execute
-
-```js
-for await (const message of execute({
-  prompt: "what is 2+2?",
-  options: {
-    cwd: process.cwd(),
-    visibility: "workspace",
-  },
-})) {
-  console.log(message);
-}
-```
-
-SDK execution streams the same JSONL events produced by:
-
-```sh
-coven-code --stream-json -x "prompt"
-```
-
-## Options
-
-SDK options map to CLI arguments and environment:
-
-- `cwd`
-- `env`
-- `mode`
-- `reasoningEffort`
-- `thinking`
-- `labels`
-- `visibility`
-- `archive`
-- `continue`
-- `settingsFile`
-- `toolbox`
-- `skills`
-- `mcpConfig`
-- `permissions`
-- `enabledTools`
-- `systemPrompt`
-- `logFile`
-- `logLevel`
-- permission bypass for trusted local harnesses
-
-## User Messages
-
-```js
-const message = createUserMessage("summarize @README.md");
-```
-
-Structured image content is supported through the same stream JSON input path
-that the CLI uses.
-
-## Permissions
-
-```js
-const permission = createPermission("Bash", "delegate", {
-  to: "local-policy",
-  message: "This command is blocked in this workspace.",
-});
-```
-
-Custom reject messages are preserved in CLI and SDK results.
-
-## Threads
-
-```js
-const threadId = await threads.new({ visibility: "workspace" });
-const markdown = await threads.markdown({ threadId });
-```
-
-Thread helpers operate on the same local persistence layer as the CLI.
-
-## Abort Handling
-
-SDK execution supports aborting while waiting on async input. Consumers should
-wire cancellation from UI or server request lifecycles so long-running local
-agent turns can be stopped promptly.