agentpostmortem 0.1.0

package/dist/scripts/init.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+// scripts/init.ts
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function parseArgs(argv) {
+  let target = process.cwd();
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--target") {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error("missing value for --target");
+      }
+      target = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  return { target: path.resolve(target) };
+}
+async function resolveTemplatesDir() {
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path.resolve(scriptDir, "../../src/templates"),
+    path.resolve(scriptDir, "../src/templates")
+  ];
+  for (const candidate of candidates) {
+    if (await pathExists(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(`unable to locate templates directory from ${scriptDir}`);
+}
+async function copyIfMissing(sourcePath, destinationPath, relativePath) {
+  await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+  if (await pathExists(destinationPath)) {
+    console.log(`  [skip] ${relativePath} (already exists)`);
+    return { copied: 0, skipped: 1 };
+  }
+  await fs.copyFile(sourcePath, destinationPath);
+  console.log(`  [copy] ${relativePath}`);
+  return { copied: 1, skipped: 0 };
+}
+async function copyCommandTemplates(templatesDir, targetRoot) {
+  const commandsTemplateDir = path.join(templatesDir, "commands");
+  const commandEntries = await fs.readdir(commandsTemplateDir, { withFileTypes: true });
+  let copied = 0;
+  let skipped = 0;
+  const commandFiles = commandEntries.filter((entry) => entry.isFile() && entry.name.endsWith(".md")).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
+  for (const commandFile of commandFiles) {
+    const sourcePath = path.join(commandsTemplateDir, commandFile);
+    const relativePath = path.posix.join(".opencode", "commands", commandFile);
+    const destinationPath = path.join(targetRoot, ".opencode", "commands", commandFile);
+    const result = await copyIfMissing(sourcePath, destinationPath, relativePath);
+    copied += result.copied;
+    skipped += result.skipped;
+  }
+  return { copied, skipped };
+}
+async function copySkillTemplates(templatesDir, targetRoot) {
+  const skillsTemplateDir = path.join(templatesDir, "skills");
+  const skillEntries = await fs.readdir(skillsTemplateDir, { withFileTypes: true });
+  let copied = 0;
+  let skipped = 0;
+  const skillDirectories = skillEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
+  for (const skillName of skillDirectories) {
+    const sourcePath = path.join(skillsTemplateDir, skillName, "SKILL.md");
+    if (!await pathExists(sourcePath)) {
+      throw new Error(`missing skill template: ${sourcePath}`);
+    }
+    const relativePath = path.posix.join(".opencode", "skills", skillName, "SKILL.md");
+    const destinationPath = path.join(targetRoot, ".opencode", "skills", skillName, "SKILL.md");
+    const result = await copyIfMissing(sourcePath, destinationPath, relativePath);
+    copied += result.copied;
+    skipped += result.skipped;
+  }
+  return { copied, skipped };
+}
+async function ensurePostmortemConfig(targetRoot) {
+  const relativePath = path.posix.join(".opencode", "postmortem.json");
+  const destinationPath = path.join(targetRoot, relativePath);
+  await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+  if (await pathExists(destinationPath)) {
+    console.log(`  [skip] ${relativePath} (already exists)`);
+    return { copied: 0, skipped: 1 };
+  }
+  await fs.writeFile(destinationPath, "{}", "utf8");
+  console.log(`  [copy] ${relativePath}`);
+  return { copied: 1, skipped: 0 };
+}
+async function main() {
+  const { target } = parseArgs(process.argv.slice(2));
+  const templatesDir = await resolveTemplatesDir();
+  console.log(`Initializing templates in ${target}`);
+  const commandResult = await copyCommandTemplates(templatesDir, target);
+  const skillResult = await copySkillTemplates(templatesDir, target);
+  const configResult = await ensurePostmortemConfig(target);
+  const copied = commandResult.copied + skillResult.copied + configResult.copied;
+  const skipped = commandResult.skipped + skillResult.skipped + configResult.skipped;
+  console.log("");
+  console.log(`Done. Copied ${copied} file(s), skipped ${skipped} file(s).`);
+  console.log("Next step: Add 'agentpostmortem' to your opencode.json plugin array.");
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`init failed: ${message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "agentpostmortem",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "description": "Postmortem workflow plugin for OpenCode: failure memory, prevention rules, guardrailed retry",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tpypan/AgentPostmortem.git"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "postmortem",
+    "ai",
+    "debugging"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "postmortem-init": "dist/scripts/init.js"
+  },
+  "files": [
+    "dist",
+    "src/templates",
+    "INSTALL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:check": "bun run build && bun --eval \"import p from './dist/index.js'; process.exit(typeof p === 'function' ? 0 : 1)\"",
+    "test": "bun test",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.2.15",
+    "zod": "4.1.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.2"
+  },
+  "directories": {
+    "example": "examples",
+    "test": "test"
+  },
+  "author": "",
+  "bugs": {
+    "url": "https://github.com/Tpypan/AgentPostmortem/issues"
+  },
+  "homepage": "https://github.com/Tpypan/AgentPostmortem#readme",
+  "engines": {
+    "node": ">=16"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/templates/commands/disable-lessons.md

@@ -0,0 +1,12 @@
+---
+description: Disable or re-enable postmortem lesson injection for the active session
+subtask: true
+---
+
+/disable-lessons
+
+Call the `postmortem_disable_lessons` plugin tool with flags mapped from $ARGUMENTS. Examples:
+
+tool: postmortem_disable_lessons
+tool: postmortem_disable_lessons --enable
+tool: postmortem_disable_lessons --json

package/src/templates/commands/failures.md

@@ -0,0 +1,10 @@
+---
+description: Manage stored postmortem failures (list/show/forget/delete/prune/purge)
+subtask: true
+---
+
+/failures
+
+Call the `postmortem_failures` plugin tool with flags mapped from `$ARGUMENTS`. Example:
+
+tool: postmortem_failures --action list --json

package/src/templates/commands/forget.md

@@ -0,0 +1,11 @@
+---
+description: Forget a stored failure record by id
+subtask: true
+---
+
+/forget
+
+Forget a stored failure record by id. Expects an id argument.
+
+Example:
+tool: postmortem_failures --action forget --id $1

package/src/templates/commands/inspect.md

@@ -0,0 +1,10 @@
+---
+description: Render a safe summary of the last postmortem run
+subtask: true
+---
+
+/inspect
+
+Call the postmortem_inspect plugin tool with flags mapped from $ARGUMENTS. Example:
+
+tool: postmortem_inspect --json

package/src/templates/commands/postmortem-config.md

@@ -0,0 +1,11 @@
+---
+description: Show or set postmortem storage root selection
+subtask: true
+---
+
+/postmortem-config
+
+Call the `postmortem_config` plugin tool with flags mapped from `$ARGUMENTS`. Examples:
+
+tool: postmortem_config --action show --json
+tool: postmortem_config --action set --storage repo --json

package/src/templates/commands/postmortem-eval.md

@@ -0,0 +1,14 @@
+Command: postmortem_eval
+
+Description:
+  Local-only evaluation of repeat-failure metrics from stored failures.jsonl. Reads the project's postmortem store (no telemetry) and computes deterministic metrics.
+
+Args:
+  --json : output JSON
+  --window <n> : lookahead window size (default 10)
+
+Metrics:
+  totalRecords
+  uniqueSignatures
+  repeatRateWithinWindow
+  repeatCountsBySignature

package/src/templates/commands/record-failure.md

@@ -0,0 +1,10 @@
+---
+description: Preview or persist a durable postmortem failure record
+subtask: true
+---
+
+/record-failure
+
+Call the `postmortem_record_failure` plugin tool with flags mapped from `$ARGUMENTS`. Example:
+
+tool: postmortem_record_failure --yes --json

package/src/templates/commands/retry.md

@@ -0,0 +1,12 @@
+---
+description: Preview or emit a guardrailed retry prompt for the last user task
+subtask: true
+---
+
+/retry
+
+Call the `postmortem_retry` plugin tool with flags mapped from $ARGUMENTS. Examples:
+
+tool: postmortem_retry
+tool: postmortem_retry --skip rule-a --skip rule-b --explain
+tool: postmortem_retry --yes

package/src/templates/commands/rules.md

@@ -0,0 +1,10 @@
+---
+description: Manage stored postmortem guardrail rules (list/show/enable/disable/edit/rate/add_from_failure)
+subtask: true
+---
+
+/rules
+
+Call the `postmortem_rules` plugin tool with flags mapped from `$ARGUMENTS`. Example:
+
+tool: postmortem_rules --action list --json

package/src/templates/commands/why-failed.md

@@ -0,0 +1,10 @@
+---
+description: Deterministically analyze a stored failure and generate typed hypotheses + prevention rules
+subtask: true
+---
+
+/why-failed
+
+Call the `postmortem_why_failed` plugin tool with flags mapped from `$ARGUMENTS`. Example:
+
+tool: postmortem_why_failed --latest --json

package/src/templates/skills/disable-lessons/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: disable-lessons
+description: Disable or re-enable postmortem guardrail injection for this session.
+---
+
+## What I do
+
+- Disable or re-enable postmortem guardrail lessons for the current session
+- Can be toggled on or off as needed
+- Safe for memory by default
+
+## How to run
+
+Call the tool directly:
+
+```
+tool: postmortem_disable_lessons
+tool: postmortem_disable_lessons --enable
+tool: postmortem_disable_lessons --disable
+tool: postmortem_disable_lessons --json
+```
+
+## Argument mapping
+
+- `disable` (bool): Disable lessons
+- `enable` (bool): Enable lessons
+- `json` (bool): Output as JSON
+
+## Safety
+
+- All output is redacted by default for memory safety
+- Never request or display secrets
+- To delete all postmortem data, first run `tool: postmortem_config --action show --json` to get the `root` path, then delete it manually with `rm -rf "<root>"`.
+- Repo-local storage is opt-in via `.opencode/postmortem.json`.

package/src/templates/skills/failures/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: failures
+description: List, show, forget, delete, prune, or purge stored postmortem failures.
+---
+
+## What I do
+
+- List all stored postmortem failures
+- Show, forget, delete, prune, or purge failures by ID or session
+- Supports dry run and filtering
+
+## How to run
+
+Call the tool directly:
+
+```
+tool: postmortem_failures --action list --json
+tool: postmortem_failures --action delete --id <failureId> --yes --json
+```
+
+## Argument mapping
+
+- `action` (string): Action to perform (list, show, forget, delete, prune, purge)
+- `id` (string): Failure ID
+- `sessionId` (string): Session ID
+- `json` (bool): Output as JSON
+- `yes` (bool): Confirm destructive actions
+- `dryRun` (bool): Preview changes
+- `maxBytes` (number): Limit output size
+- `olderThanDays` (number): Filter by age
+- `keepLastN` (number): Keep last N failures
+
+## Safety
+
+- All output is redacted by default for memory safety
+- Never request or display secrets
+- To delete all postmortem data, first run `tool: postmortem_config --action show --json` to get the `root` path, then delete it manually with `rm -rf "<root>"`.
+- Repo-local storage is opt-in via `.opencode/postmortem.json`.

package/src/templates/skills/inspect/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: inspect
+description: Render the last-run postmortem snapshot for this project. Safe by default.
+---
+
+## What I do
+
+- Show the most recent postmortem snapshot for the current project
+- Optionally include files, git status, or errors in the output
+- Output is safe for memory by default (redacted)
+
+## How to run
+
+Call the tool directly:
+
+```
+tool: postmortem_inspect --json --files --git --errors
+```
+## Argument mapping
+
+- `json` (bool): Output as JSON
+- `files` (bool): Include file list
+- `git` (bool): Include git status
+- `errors` (bool): Include error details
+
+## Safety
+
+- All output is redacted by default for memory safety
+- Never request or display secrets
+- To delete all postmortem data, first run `tool: postmortem_config --action show --json` to get the `root` path, then delete it manually with `rm -rf "<root>"`.
+- Repo-local storage is opt-in via `.opencode/postmortem.json`.

package/src/templates/skills/postmortem-config/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: postmortem-config
+description: Show or set project-local postmortem storage config (user or repo root).
+---
+
+## What I do
+
+- Show or set the postmortem storage configuration for this project
+- Switch between user and repo storage, or set raw storage
+- Can output as JSON for scripting
+
+## How to run
+
+Call the tool directly:
+
+```
+tool: postmortem_config --action show --json
+tool: postmortem_config --action set --storage repo --json
+```
+
+## Argument mapping
+
+- `action` (string): Action to perform (show, set)
+- `storage` (string): Storage location (user, repo)
+- `storeRaw` (bool): Store raw data
+- `json` (bool): Output as JSON
+
+## Safety
+
+- All output is redacted by default for memory safety
+- To delete all postmortem data, first run `tool: postmortem_config --action show --json` to get the `root` path, then delete it manually with `rm -rf "<root>"`.
+- Repo-local storage is opt-in via `.opencode/postmortem.json`.

package/src/templates/skills/postmortem-eval/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: postmortem-eval
+description: Local-only evaluation of repeat-failure metrics from stored failures.jsonl.
+---
+
+## What I do
+
+- Evaluate repeat-failure metrics from stored failures
+- Operates locally, no remote calls
+- Can limit the evaluation window
+
+## How to run
+
+Call the tool directly:
+
+```
+tool: postmortem_eval --json --window 30
+```
+## Argument mapping
+
+- `json` (bool): Output as JSON
+- `window` (number): Limit to last N days
+
+## Safety
+
+- All output is redacted by default for memory safety
+- Never request or display secrets
+- To delete all postmortem data, first run `tool: postmortem_config --action show --json` to get the `root` path, then delete it manually with `rm -rf "<root>"`.
+- Repo-local storage is opt-in via `.opencode/postmortem.json`.

package/src/templates/skills/record-failure/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: record-failure
+description: Preview or persist a durable failure record from the last-run snapshot.
+---
+
+## What I do
+
+- Record a failure event based on the most recent postmortem snapshot
+- Optionally add a reason or tags
+- Can preview or persist the record
+
+## How to run
+
+Call the tool directly:
+
+```
+tool: postmortem_record_failure --yes --json --reason "..." --tags foo --tags bar
+```
+## Argument mapping
+
+- `yes` (bool): Persist immediately
+- `json` (bool): Output as JSON
+- `reason` (string): Reason for failure
+- `tags` (string[]): Tags for this failure
+
+## Safety
+
+- All output is redacted by default for memory safety
+- Never request or display secrets
+- To delete all postmortem data, first run `tool: postmortem_config --action show --json` to get the `root` path, then delete it manually with `rm -rf "<root>"`.
+- Repo-local storage is opt-in via `.opencode/postmortem.json`.

package/src/templates/skills/retry/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: retry
+description: Preview or emit a guardrailed retry prompt from the latest non-command user task.
+---
+
+## What I do
+
+- Preview or emit a retry prompt for the last failed user task
+- Can explain, skip rule IDs, or confirm retry
+- Safe for memory by default
+
+## How to run
+
+Call the tool directly:
+
+```
+tool: postmortem_retry
+tool: postmortem_retry --skip rule-a --skip rule-b --explain
+tool: postmortem_retry --yes
+```
+
+## Argument mapping
+
+- `yes` (bool): Confirm retry
+- `explain` (bool): Explain the retry
+- `skip` (string[]): Rule IDs to skip
+- `json` (bool): Output as JSON
+
+## Safety
+
+- All output is redacted by default for memory safety
+- Never request or display secrets
+- To delete all postmortem data, first run `tool: postmortem_config --action show --json` to get the `root` path, then delete it manually with `rm -rf "<root>"`.
+- Repo-local storage is opt-in via `.opencode/postmortem.json`.

package/src/templates/skills/rules/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: rules
+description: List, show, enable, disable, edit, or rate postmortem rules and import suggestions from failure analysis.
+---
+
+## What I do
+
+- List, show, enable, disable, edit, or rate postmortem rules
+- Import suggestions from failure analysis
+- Filter, update, or rate rules by ID or failure
+
+## How to run
+
+Call the tool directly:
+
+```
+tool: postmortem_rules --action list --json
+tool: postmortem_rules --action disable --id <ruleId> --json
+tool: postmortem_rules --action edit --id <ruleId> --text "..." --json
+```
+
+## Argument mapping
+
+- `action` (string): Action to perform (list, show, enable, disable, edit, rate, import)
+- `id` (string): Rule ID
+- `failureId` (string): Filter by failure
+- `json` (bool): Output as JSON
+- `includeDisabled` (bool): Include disabled rules
+- `text` (string): Rule text
+- `severity` (string): Severity level
+- `rating` (string): Rule rating
+- `note` (string): Add a note
+
+## Safety
+
+- All output is redacted by default for memory safety
+- Never request or display secrets
+- To delete all postmortem data, first run `tool: postmortem_config --action show --json` to get the `root` path, then delete it manually with `rm -rf "<root>"`.
+- Repo-local storage is opt-in via `.opencode/postmortem.json`.

package/src/templates/skills/why-failed/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: why-failed
+description: Analyze a stored failure and persist hypotheses and prevention rules.
+---
+
+## What I do
+
+- Analyze a stored failure deterministically
+- Persist hypotheses and prevention rules for the failure
+- Can target a specific failure or the latest
+
+## How to run
+
+Call the tool directly:
+
+```
+tool: postmortem_why_failed --latest --json
+tool: postmortem_why_failed --id <failureId> --json
+```
+
+## Argument mapping
+
+- `id` (string): Failure ID to analyze
+- `latest` (bool): Analyze the latest failure
+- `json` (bool): Output as JSON
+
+## Safety
+
+- All output is redacted by default for memory safety
+- Never request or display secrets
+- To delete all postmortem data, first run `tool: postmortem_config --action show --json` to get the `root` path, then delete it manually with `rm -rf "<root>"`.
+- Repo-local storage is opt-in via `.opencode/postmortem.json`.