@mcrescenzo/opencode-workflows 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and uses semantic versioning for published package releases.
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Initial public package surface for the opencode workflows plugin.
+- Durable workflow run store, approval-gated apply flow, bundled repo-review
+  workflows, live-gate probes, workflow templates, and extension seams.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,134 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+- Trolling, insulting or derogatory comments, and personal or political
+  attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action
+in response to any behavior that they deem inappropriate, threatening,
+offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, and will communicate reasons
+for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies
+when an individual is officially representing the community in public
+spaces. Examples of representing our community include using an official
+e-mail address, posting via an official social media account, or acting as
+an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+michaelcrescenzo@gmail.com. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of
+the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in
+determining the consequences for any action they deem in violation of this
+Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders,
+providing clarity around the nature of the violation and an explanation of
+why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external
+channels like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public
+or private interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, is allowed during this
+period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla coc].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available
+at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla coc]: https://github.com/mozilla/diversity
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to opencode-workflows
+
+This is an independently publishable opencode plugin package
+(`@mcrescenzo/opencode-workflows`) that can also be developed inside a private
+parent monorepo checkout. Runtime package dependencies are declared in
+`package.json`; parent-tree integrations are optional test/dev conveniences.
+These notes are for contributors running the no-token test matrix and preparing a
+public release.
+
+## Prerequisites
+
+The full no-token test matrix needs the following tools on `PATH`:
+
+| Tool | Required for | Notes |
+| --- | --- | --- |
+| **Node ≥ 20.11** | everything | See `engines` in `package.json`. The test runner is Node's built-in `node --test`. |
+| **`git`** | worktree / apply / integration / drain tests | Several suites shell out to `git` to create temporary repos and exercise the worktree + `workflow_apply` paths. |
+| **`bd` (Beads CLI)** | `beads-drain` adapter + scratch tests | A few suites shell out to `bd` to exercise the beads-drain adapter against a scratch Beads database. All `repo-*` workflows and the rest of the matrix run without it. |
+| **`opencode` binary + local config** | the live child system smoke ONLY | The required system smoke (`npm run release:system-smoke-required`) needs the opencode binary and local opencode config and is intentionally NOT part of the token-free `npm test` / `release:no-token` matrix. |
+
+If a tool is missing, the affected suites fail with a clear message rather than silently
+passing — do not treat a skipped/missing-tool run as release evidence.
+
+## Package manager and lockfile policy
+
+- The **canonical lockfile is `bun.lock`** (tracked). Use `bun install` to reproduce the
+  locked dependency set.
+- All package scripts are invoked with **`npm run <script>`** and are thin `node` wrappers
+  (e.g. `node --test tests/*.test.mjs`, `node scripts/...`). They contain no npm-specific
+  behavior, so they run identically whether you installed with Bun or npm.
+- `package-lock.json` is **gitignored** (see `.gitignore`): npm-using contributors may
+  generate one locally, but it is not tracked to avoid maintaining two divergent lockfiles.
+  `bun.lock` remains the single source of truth for the locked dependency set.
+- CI uses the same policy: `.github/workflows/ci.yml` installs dependencies with
+  `bun install --frozen-lockfile`, provisions the Beads CLI, verifies the prerequisite
+  tool versions, and then runs `npm run release:no-token`.
+
+## Running the tests
+
+From this directory:
+
+```sh
+npm test                       # full no-token matrix (all suites)
+npm run test:workflows         # workflow_run / workflow_apply / repo-* regression
+npm run test:beads-drain       # beads-drain workflow/adapter/assets/scratch coverage
+npm run test:workflow-adapters # drain adapter focused suites
+npm run test:extension-seam    # extension registration and trusted asset seams
+npm run test:live-gates        # mocked live-gate probe coverage
+npm run release:no-token       # complete public no-token release gate
+```
+
+`npm test`, `npm run test:workflows`, and `npm run release:no-token` are all runnable from
+a standalone clone (they do not depend on a private parent monorepo tree). The
+optional parent-integration regression lives in a separate, clearly named script:
+
+```sh
+npm run test:parent-integration   # OPTIONAL: only runs inside a private parent monorepo tree
+```
+
+## Public release readiness
+
+A public release must not equate "skipped" with "verified":
+
+- The public CI workflow (`.github/workflows/ci.yml`) runs on pull requests, pushes to
+  `main`, and manual dispatch. It installs Node 22, Bun, Go, and
+  `github.com/steveyegge/beads/cmd/bd@v1.0.3` with the `gms_pure_go` build tag, then
+  runs the no-token release gate.
+- `npm run release:no-token` runs lockfile sync, the full token-free `npm test` matrix,
+  and package dry-run validation, then explicitly notes that the live child system smoke is
+  a **separate required** step.
+- `npm run release:system-smoke-required` **fails closed** (non-zero exit) when live
+  system-smoke evidence is missing — see `docs/plugin-system-tests.md` for the mandatory
+  evidence checklist (child ID/PID/port, trust mode, command + tool registry entries,
+  deterministic workflow tool execution, restart/reload, and cleanup `processAlive: false`).
+
+## Style and boundaries
+
+- Pure Node ESM, no new runtime dependencies without review.
+- Do not commit local runtime state: `.opencode/`, `.beads/` Dolt DB / sockets / locks /
+  credential key, `.remember/`, `node_modules/`, logs, or workflow run dirs.
+- After changing plugin code (`opencode-workflows.js`, `workflow-kernel/`, bundled commands,
+  skills, or registration), restart opencode (or use a fresh/restarted disposable child) —
+  running sessions keep already-loaded config.
+
+## Pull request expectations
+
+- Add or update tests alongside any behavior change, and make sure `npm test`
+  (the full no-token matrix) passes before opening a pull request.
+- Keep `README.md`, `AGENTS.md`, and the relevant `docs/` file in sync with any
+  behavior or configuration change.
+- Preserve the kernel invariants in `AGENTS.md` (single plugin export, in-place
+  `hooks`/`output.parts` mutation, module-level shared state, bounded maps,
+  model IDs from config) — see `AGENTS.md` for the full list.
+- Run `npm run test:lockfile-sync` if you changed `package.json` dependencies,
+  and keep `bun.lock` (the canonical lockfile) up to date.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Crescenzo
+
+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.