@sorenllm/opencode-forge 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# opencode-forge
+
+Single general-purpose **forge** agent + a plan harness for
+[opencode](https://opencode.ai) ≥ 1.18. Plans become first-class files on
+disk with tool-enforced structure, a hard write-ban while planning, user
+confirmation gates for approve/close, and tick-as-you-go task tracking.
+
+```
+/plan fix login timeout   → read-only recon → plan_write (draft, writes denied)
+                           → present → plan_approve (user dialog = approval gate)
+                           → execute task by task, plan_tick on each (timestamped audit)
+                           → all ticked → per-criterion self-check → plan_close
+                             (user dialog = completion gate) → done
+/plan                     → list in-progress plans with progress
+/plan resume              → continue the most recent unfinished plan
+/plan discard             → abandon the current plan (abandoned, writes restored)
+```
+
+- Plan files: `.opencode/plan/<date>-<slug>.md` in your project, frontmatter
+  state machine `draft → approved → done` (exit: `abandoned`).
+- While a plan is in draft, `write` / `edit` / `bash` / `task` are **denied
+  at the permission layer** — including your own `allow` config. The only
+  exits are approval and discard. This is deliberate; see Design stance.
+- `plan_approve` / `plan_close` are pinned to a confirmation dialog: the
+  model can never flip the state itself.
+- The native `build` / `plan` agents are hidden while the plugin is loaded
+  (runtime injection, nothing written to your config). Uninstall restores
+  them automatically; plan files are never deleted.
+
+## Install
+
+Requires opencode ≥ 1.18.
+
+```bash
+# npm (recommended)
+opencode plugin @sorenllm/opencode-forge --global
+# or GitHub source
+opencode plugin github:ChengZiiii/opencode-forge --global
+```
+
+Local development: add `"file:///<repo abs path>"` to the `plugin` array in
+your opencode config. Single-file install: copy `dist/index.js` to
+`~/.config/opencode/plugin/forge.js` **and manually copy `SKILL.md`** to
+`~/.config/opencode/skills/plan/SKILL.md` (the package has no installer
+script; that mode has no bundled skill otherwise).
+
+Note: do not enable opencode's experimental plan mode
+(`OPENCODE_EXPERIMENTAL_PLAN_MODE`) together with forge — two plan mechanisms
+would overlap.
+
+## Configuration
+
+Everything works with zero config. Optional knobs (your config, your files —
+the plugin never writes them):
+
+```jsonc
+{
+  "agent": {
+    "forge": {
+      "model": "provider/model",   // pick any model for forge
+      "disable": true              // one-knob return to native: no forge,
+                                   // build/plan restored, no tools/commands/skill
+    }
+  }
+}
+```
+
+If you already have a `command.plan` of your own, it wins and the plugin's
+`/plan` is not registered.
+
+## Uninstall (four steps, restores native opencode)
+
+1. Remove the plugin entry from the `plugin` array in
+   `~/.config/opencode/opencode.json` (global installs).
+2. Delete the package store dir:
+   `~/.cache/opencode/packages/github_ChengZiiii/opencode-forge/` (github
+   installs, owner/repo layout; for npm installs it is
+   `~/.cache/opencode/packages/opencode-forge/`).
+3. Delete the `agent["forge"]` block from your config if you added one
+   (otherwise the name lingers in the agent list).
+4. Done — the hidden native `build`/`plan` agents come back automatically
+   (the hide was runtime-only). Your `.opencode/plan/` files are yours;
+   delete them yourself if you want.
+
+## File ledger
+
+What this plugin touches, exhaustively:
+
+| Where | What | Lifetime |
+| --- | --- | --- |
+| `<project>/.opencode/plan/*.md` | plan files | user data — kept forever, uninstall never deletes |
+| merged config object (RAM only) | forge agent, native build/plan `disable`, `skills.paths` entry, `command.plan` | vanishes when the plugin is removed; nothing is written to disk |
+| `~/.cache/opencode/packages/...` | installed package copy | written by the `opencode plugin` installer, not the plugin |
+| `~/.config/opencode/opencode.json` | `plugin` array entry | written by the installer |
+
+The plugin writes no temp files, no logs, nothing outside the table.
+
+## Design stance (read before filing "bash is blocked" issues)
+
+During a plan's draft phase every mutating tool — `bash` included — is
+denied, and an `allow` in your config does not override it. Reconnaissance is
+read/grep/glob; if you genuinely need a shell command to decide the plan,
+approve the plan first (revising after approval is allowed via a new `/plan`).
+The escape hatches are `plan_approve` and `/plan discard`, by design.
+
+A process restart forgets the session binding: the write-ban soft-disables
+(safety over strictness) and the next session's system notice + `/plan
+resume` re-bind from the plan file on disk, which is the source of truth.
+
+## Development
+
+```bash
+npm install
+bun run typecheck     # tsc --noEmit
+node --test tests/*.test.mjs
+bun run bundle        # rebuild self-contained dist/index.js (committed)
+```
+
+Architecture: `plugin.ts` (dual entry — v1 `server` full-featured + v2
+`setup` defensive forward-compat) + `src/plan-file.ts` (pure plan document
+core, unit-tested, no opencode imports) + `SKILL.md` (planning discipline,
+discovered via `config.skills.paths`). Behavioral changes go through the
+OpenSpec workflow in `openspec/` — see AGENTS.md. Common pitfalls live in
+`../opencode-plugin-dev-pitfalls.md`.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: plan
+description: >-
+  The plan discipline for the forge agent. You **MUST** load this skill when
+  the /plan command routes a task goal to you, OR the user asks to "plan
+  first", "make a plan", "think before coding" before implementation. It
+  governs the whole plan lifecycle: read-only reconnaissance, clarifying
+  questions, plan_write (structured, tool-rendered), user-approval via
+  plan_approve, tick-as-you-go execution via plan_tick, per-criterion
+  self-check at plan_close, and the OpenSpec boundary for long-horizon work.
+  Do NOT load it for direct implementation requests with no planning intent.
+---
+
+# Plan Discipline (forge)
+
+Plans are short-horizon, single-task-goal documents on disk
+(`.opencode/plan/<date>-<slug>.md`). The harness (tools + permission layer)
+enforces the hard parts; you supply the engineering judgment.
+
+## Phase 1 — Reconnaissance (read-only)
+
+- Explore with read/grep/glob only. **All write tools, bash, and task
+  (subagents) are denied while a draft exists** — do not attempt them, do not
+  ask the user to bypass.
+- Gather concrete evidence with `file:line` references; the plan's Context
+  Findings section must contain findings you actually verified, not guesses.
+- If the goal is ambiguous on scope, behavior, or acceptance — ask the user
+  1-3 focused questions FIRST. Do not plan against assumptions the user could
+  settle in one line.
+
+## Phase 2 — Write the plan (plan_write)
+
+Call `plan_write` with structured fields; the tool renders and validates the
+fixed sections (Goal / Non-Goals / Context Findings / Approach and
+Alternatives / Task List / Risks / Acceptance Criteria), so a malformed plan
+cannot exist.
+
+Quality bar for each field:
+
+- **goal**: one line, the outcome — not the activity.
+- **context**: verified findings with `file:line` evidence; include what you
+  ruled out and why.
+- **approach**: the chosen approach AND at least one rejected alternative
+  with the reason. A plan with no considered alternative is a guess.
+- **tasks**: 3-8 concrete, independently verifiable steps, each doable in one
+  sitting. A task like "improve the code" is invalid; "extract timeout
+  constant into config.ts and default it to 3000" is valid.
+- **risks**: what could break, blast radius, rollback path.
+- **acceptance**: criteria you can verify with a command, a file, or an
+  observable behavior. Vague criteria will fail the plan_close self-check.
+- **nonGoals**: explicit out-of-scope items (what the user might expect but
+  will NOT get).
+
+Revising: calling `plan_write` again while still in draft overwrites the same
+file. Do this after user feedback instead of hand-editing.
+
+## Phase 3 — Approval gate (plan_approve)
+
+Present to the user, briefly: goal, chosen approach (one line why), the
+numbered task list, and the acceptance criteria. Then call `plan_approve`.
+The user confirms in a dialog — that confirmation IS the approval. If they
+object, revise with `plan_write` and present again. Never proceed to
+implementation before approval succeeds.
+
+## Phase 4 — Execution (tick as you go)
+
+- Execute tasks in order; after EACH task's work is actually done, call
+  `plan_tick` with its number immediately. Never batch ticks; never tick
+  ahead of reality — the tick timestamp is an audit trail.
+- If mid-execution you discover the plan is wrong, do not silently improvise:
+  tell the user what changed and either finish the affected task anyway or
+  ask whether to revise (/plan with the same goal re-enters planning).
+
+## Phase 5 — Completion gate (plan_close)
+
+When all tasks are ticked: self-check EVERY acceptance criterion with
+concrete evidence (`file:line`, command output, test result). Call
+`plan_close` with one check per criterion, `pass` honest — a ✗ fails the
+close and that is the design working, not an inconvenience. The user
+confirms closure in a dialog.
+
+## Boundaries
+
+- **Abandon**: user cancels → `/plan discard` (or plan_discard). Terminal,
+  file kept as history, writes restored.
+- **Resume**: new session with unfinished plan → the system notice carries
+  the path; `/plan resume` continues from the remaining tasks.
+- **Spec-workflow boundary**: work expected to span multiple sessions, days
+  of multi-file change, or multi-round requirement review is spec work, not
+  plan work. Say so once (e.g. "this fits a spec workflow like OpenSpec
+  better"), let the user choose, and proceed with a plan only if they insist.