agentpostmortem 0.1.0

package/INSTALL.md

@@ -0,0 +1,96 @@
+# Installation Guide
+
+## npm (recommended)
+
+### 1. Add the plugin to your OpenCode config
+
+In your project root, add the plugin to `opencode.json` (create the file if it doesn't exist):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["agentpostmortem"]
+}
+```
+
+OpenCode automatically installs npm plugins using Bun. No `npm install` or `bun install` needed in your project.
+
+### 2. Install command and skill templates (optional but recommended)
+
+Run the init command to copy command wrappers and skill definitions into your project:
+
+```bash
+npx --package agentpostmortem postmortem-init
+```
+
+This copies:
+- `.opencode/commands/*.md` — slash command wrappers (`/inspect`, `/retry`, `/failures`, etc.)
+- `.opencode/skills/*/SKILL.md` — skill definitions for OpenCode agents
+- `.opencode/postmortem.json` — empty per-project config stub
+
+The init command is safe to re-run: it skips files that already exist.
+
+### 3. Restart OpenCode
+
+The plugin loads at OpenCode startup. Restart OpenCode after adding it to the config.
+
+---
+
+## Local file install (fallback)
+
+If you cannot use npm or prefer a self-contained setup, use the bundled plugin file.
+
+### 1. Download the bundled plugin
+
+Get `dist/postmortem.plugin.js` from the npm CDN (or build it yourself: `bun run build`).
+```bash
+curl -fsSL https://unpkg.com/agentpostmortem@latest/dist/postmortem.plugin.js -o postmortem.plugin.js
+```
+### 2. Place it in your project
+
+```bash
+mkdir -p .opencode/plugins
+cp postmortem.plugin.js .opencode/plugins/
+```
+
+OpenCode automatically loads all `.js` and `.ts` files from `.opencode/plugins/`.
+
+### 3. Install templates
+
+Run the init command (requires Node.js):
+
+```bash
+npx --package agentpostmortem postmortem-init
+```
+
+Or manually copy templates from the [src/templates/](src/templates/) directory.
+
+### 4. Restart OpenCode
+
+---
+
+## Per-project configuration
+
+The plugin works out of the box with no configuration. By default, postmortem data is stored in your user data directory (scoped by project).
+
+To enable repo-local storage (stored in `.opencode/postmortems/` inside your project), create or edit `.opencode/postmortem.json`:
+
+```json
+{
+  "storage": "repo"
+}
+```
+
+> **Note**: Repo-local storage is only safe if `.opencode/` is not a symlink. The plugin checks this automatically.
+
+---
+
+## Verifying the install
+
+In an OpenCode session, run:
+
+```
+tool: postmortem_config --action show --json
+```
+
+You should see the config, storage path, and project ID.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tpypan
+
+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,116 @@
+# AgentPostmortem
+
+`agentpostmortem` adds a complete postmortem loop to OpenCode: capture failures, analyze root causes, create guardrails, and retry with context-aware constraints.
+
+This repository is the standalone plugin distribution (not the OpenCode source tree).
+
+## Why this plugin is useful
+
+- Persist failure history across sessions instead of losing context after one run.
+- Generate deterministic failure analysis and reusable prevention rules.
+- Keep retries bounded and explainable (`/retry --explain`).
+- Evaluate repeat-failure trends locally (`/postmortem-eval`) without telemetry.
+
+## What this plugin adds
+
+- `postmortem_inspect`: view the latest redacted last-run snapshot
+- `postmortem_record_failure`: persist a durable failure record
+- `postmortem_why_failed`: deterministic analysis + 1-3 prevention rules
+- `postmortem_rules`: list/show/enable/disable/edit/rate/import rules
+- `postmortem_failures`: list/show/forget/delete/prune/purge failures
+- `postmortem_retry`: generate a retry prompt with relevant guardrails (`--explain` supported)
+- `postmortem_disable_lessons`: disable/enable injection for the current session
+- `postmortem_config`: show/set storage mode (`user` or `repo`)
+- `postmortem_eval`: local-only repeat-failure evaluation metrics
+
+## Install
+
+See [INSTALL.md](INSTALL.md) for full setup.
+
+Quick start:
+
+1. Add "agentpostmortem" to your `opencode.json` plugin array.
+2. Run `npx --package agentpostmortem postmortem-init` in your project.
+3. Restart OpenCode.
+
+## Usage examples
+
+The sections below show realistic command sequences you can run in OpenCode.
+For the full per-command catalog, see [commands.md](examples/minimal/commands.md).
+
+### 1) Capture and analyze a failure in minutes
+
+```text
+/inspect --json --errors
+/record-failure --yes --json
+/why-failed --latest --json
+```
+
+Use this when a run fails and you want a durable record plus deterministic hypotheses before trying fixes.
+
+### 2) Build guardrails, then retry with context
+
+```text
+/rules --action list --json
+/retry --explain
+/retry --yes
+```
+
+This sequence helps you review active rules, see why each rule was selected, then execute a guarded retry prompt.
+
+### 3) Tune behavior during a long debugging session
+
+```text
+/disable-lessons --json
+/disable-lessons --enable --json
+/postmortem-config --action show --json
+```
+
+Use `/disable-lessons` when you want a temporary clean session, then re-enable guardrail injection when you are ready.
+
+### 4) Manage failure memory and clean up stale records
+
+```text
+/failures --action list --json
+/failures --action show --id <failure-id> --json
+/forget <failure-id>
+```
+
+You can inspect specific incidents and retire low-value memory entries while preserving the rest of your history.
+
+### 5) Evaluate if failures are repeating
+
+```text
+/postmortem-eval --json --window 20
+```
+
+This reports repeat-failure metrics so you can measure whether new rules are reducing recurrence.
+
+## Examples folder
+
+- `examples/minimal/opencode.json` - minimal plugin config for a project
+- `examples/minimal/README.md` - minimal setup walkthrough and file map
+- `examples/minimal/commands.md` - full flag-by-flag reference for every command
+- `examples/minimal/playbooks.md` - end-to-end incident response and maintenance workflows
+- `examples/minimal/commands/` - per-command deep-dive examples
+
+## Repository layout
+
+- `src/` - plugin implementation (TypeScript source)
+- `src/templates/` - command and skill templates copied by `postmortem-init`
+- `test/` - test suite
+- `scripts/` - init script source
+- `examples/` - runnable configuration and command examples
+- `dist/` - build output (npm ESM + bundled fallback)
+
+## Storage and safety
+
+- Default storage is user-data scoped by project ID.
+- Optional repo-local storage can be enabled with `.opencode/postmortem.json` and `{ "storage": "repo" }`.
+- Redaction and caps are applied before persistence and before display/injection.
+
+## References
+
+- Plugins docs: https://opencode.ai/docs/plugins
+- Commands docs: https://opencode.ai/docs/commands
+- Skills docs: https://opencode.ai/docs/skills