akm-opencode 0.4.3 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # akm-opencode
 
-OpenCode plugin for the [AKM](https://github.com/itlackey/akm) CLI. Registers tools that let your AI agent **search**, **show**, and **manage** extension assets from stash directories and registries — plus **agentic hooks** that auto-load relevant assets into each turn, record feedback when assets are used, and harvest session memories so the stash improves with every session.
+OpenCode plugin for the [AKM](https://github.com/itlackey/akm) CLI (v0.5.0+). Registers tools that let your AI agent **search**, **show**, and **manage** stash assets — skills, commands, agents, knowledge, memories, scripts, workflows, vaults, and wikis — plus **agentic hooks** that auto-load relevant assets into each turn, record feedback when assets are used, and harvest session memories so the stash improves with every session.
 
 ## Installation
 
@@ -14,27 +14,24 @@ Add to your OpenCode config (`opencode.json`):
 
 ## Tools
 
+The plugin exposes a trimmed surface of **14 high-value tools**. Long-tail verbs (`add`, `save`, `import`, `clone`, `update`, `remove`, `list`-sources, `registry-search`, `index`-reindex, `config`, `upgrade`, ad-hoc `run`) are reachable via `akm_help` plus the raw `akm` CLI through the `bash` tool.
+
 | Tool | Description |
 |------|-------------|
-| `akm_search` | Search the local stash, the registry, or both for scripts, skills, commands, agents, and knowledge |
-| `akm_registry_search` | Search configured registries for installable kits and optional asset-level hits |
+| `akm_search` | Search the local stash, the registry, or both. Type filter accepts `skill`, `command`, `agent`, `knowledge`, `memory`, `script`, `workflow`, `vault`, `wiki`, `any` |
 | `akm_show` | Show a stash asset by its ref |
-| `akm_index` | Build or rebuild the search index |
 | `akm_agent` | Dispatch a stash `agent:*` into OpenCode using the stash prompt and metadata |
 | `akm_cmd` | Execute a stash `command:*` template in OpenCode via SDK session prompting |
-| `akm_add` | Install kits from npm, GitHub, git URLs, or local directories |
-| `akm_list` | List configured AKM sources |
-| `akm_remove` | Remove a configured AKM source and reindex |
-| `akm_update` | Update one managed source or all managed sources |
-| `akm_clone` | Clone an asset into the working stash or a custom destination for editing |
 | `akm_remember` | Record a memory in the default stash |
-| `akm_feedback` | Record positive or negative feedback for a stash asset |
-| `akm_config` | Get, set, unset, list, or inspect akm configuration (including `config path --all`) |
-| `akm_run` | Execute a stash script using its `run` field |
-| `akm_sources` | Backward-compatible alias that lists configured AKM sources |
-| `akm_upgrade` | Check for or install akm CLI updates |
+| `akm_feedback` | Record positive or negative feedback for a stash asset (skipped automatically for `memory:` and `vault:` refs) |
 | `akm_curate` | Curate the stash for a task or topic and return ranked matches the agent can use |
-| `akm_evolve` | Dispatch the AKM curator agent to review recent session activity and propose stash improvements |
+| `akm_evolve` | Dispatch the AKM curator subagent into a child session, capture the report as a memory, and seed the curator-context cache so it survives compaction |
+| `akm_parent_messages` | Summarize the parent OpenCode session so dispatched stash subagents can inherit upstream context |
+| `akm_session_messages` | Summarize a specific OpenCode session (arbitrary IDs restricted to `akm-curator`) |
+| `akm_vault` | Vault `list` / `show` (key names) / `create` / `set` / `unset` / `load` (opaque shell-eval text). **Values never surface** through `list`/`show`; `load` output is meant for `eval` and must not be displayed back |
+| `akm_wiki` | Manage wikis (`create`, `register`, `list`, `show`, `pages`, `search`, `stash`, `lint`, `ingest`, `remove`) |
+| `akm_workflow` | Drive workflow runs (`start`, `next`, `complete`, `status`, `list`, `create`, `template`, `resume`) |
+| `akm_help` | Discover the right `akm` CLI invocation for non-first-class verbs. Returns a curated quick-reference table plus live `akm <subcommand> --help` output |
 
 ## Compound-engineering hooks
 
@@ -44,10 +41,13 @@ fails silently when `akm` is not on PATH — the TUI is never affected.
 
 | Event | What happens |
 | --- | --- |
-| **`session.created`** (event hook) | Warms the stash index in the background and caches `akm hints` for the next system transform so the agent knows the CLI surface area at turn 0. |
+| **`session.created`** (event hook) | Warms the stash index in the background and caches `akm hints` plus active workflow status for the next system transform so the agent knows the CLI surface area at turn 0. |
 | **`chat.message`** | Runs `akm curate "<prompt>"` on each user message (prompts shorter than `AKM_CURATE_MIN_CHARS` are skipped). The top matches are stored for injection. Memory intents (prompts mentioning "remember" / "memory") are tracked in the session buffer. |
-| **`experimental.chat.system.transform`** | Appends the cached hints (once per session) and the curated context (once per turn) to the model's system prompt so the agent sees relevant stash assets before answering. |
-| **`tool.execute.after`** (`akm_*` tools) | Logs asset usage, accumulates refs into the session buffer, and records `akm feedback <ref> --positive` / `--negative` automatically based on whether the tool succeeded or failed. Never recurses into `akm_feedback` and skips `memory:` refs. |
+| **`experimental.chat.system.transform`** | Appends cached hints, active workflow state, the last curator report, and the current prompt's curated context to the model's system prompt. Hints and workflow state are re-injected after transcript compaction. |
+| **`tool.execute.before`** (`akm_*` tools) | Blocks destructive or sensitive operations until `confirm:true` is provided. |
+| **`tool.execute.after`** (`akm_*` tools) | Logs asset usage, accumulates refs into the session buffer, records `akm feedback <ref> --positive` / `--negative` asynchronously with per-call dedupe, checkpoints memories every `AKM_MEMORY_CHECKPOINT_EVERY` successful asset-touching tool calls, and scans child-agent free text for additional refs. |
+| **`experimental.session.compacting`** | Pushes hints, curated context, active workflows, and the last curator report into the compaction prompt so they survive transcript shrinking. |
+| **`shell.env`** | Exposes `AKM_STASH_DIR`, `AKM_PROJECT`, and `AKM_PLUGIN_VERSION` to shell tools so plain `akm` calls inherit the right context. |
 | **`stop`** / **`session.idle`** / **`session.compacted`** / **`session.deleted`** | Flushes the per-session buffer into a `memory:opencode-session-YYYYMMDD-<sid>` memory so every meaningful session contributes durable context for future searches. Requires at least two observations before persisting. |
 
 ### Environment overrides
@@ -61,24 +61,22 @@ fails silently when `akm` is not on PATH — the TUI is never affected.
 | `AKM_CURATE_LIMIT` | `5` | Max curated results injected into context per prompt. |
 | `AKM_CURATE_MIN_CHARS` | `16` | Minimum prompt length before curation runs. |
 | `AKM_CURATE_TIMEOUT` | `8` | Wall-clock seconds for `akm` invocations inside hooks. |
+| `AKM_CURATOR_CONTEXT_MAX_CHARS` | `4000` | Max cached curator-report characters re-injected into system/compaction context; the full report is still persisted as memory. |
+| `AKM_MEMORY_CHECKPOINT_EVERY` | `8` | Number of successful asset-touching tool calls between mid-session checkpoint memories. |
+| `AKM_RETROSPECTIVE_FEEDBACK_PATTERN` | `\b(thanks|perfect|worked)\b` | Case-insensitive regex used for lightweight positive retrospective feedback on the most recent refs. |
 
 ### Curator agent
 
-`akm_evolve` dispatches a child OpenCode session running a built-in curator
-prompt that reviews recent AKM activity (OpenCode app logs, session-summary
-memories, live stash) and produces a prioritized action list: hot assets to
-promote, cold ones to investigate, coverage gaps to draft, duplicates to
-consolidate. The curator never applies destructive changes without explicit
-user approval.
+`akm_evolve` dispatches the native `akm-curator` OpenCode subagent when it is
+available, falling back to `general` with the same curator prompt when needed.
+The curator reviews recent AKM activity (OpenCode app logs, session-summary
+memories, parent-session context, live stash), produces a prioritized action
+list, and persists its latest report as `memory:akm-curator-YYYYMMDD-<sid>` so
+future curator runs can build on it.
 
 ### Registry discovery
 
-Use either:
-
-- `akm_search` with `source: "registry"` or `source: "both"`
-- `akm_registry_search` when you only want installable community kits
-
-Registry hits include `id`, `installRef`, and `action` fields. Use `installRef` when passing a result into `akm_add`; registry-specific IDs are not installable refs. Use `assets: true` when you also want asset-level matches from registry v2 indexes.
+Search registries with `akm_search` using `source: "registry"` or `source: "both"`. Registry hits include `id`, `installRef`, and `action` fields. Use `installRef` when feeding a result into `akm add` (run via `akm_help` topic="add" or directly through bash); registry-specific IDs are not installable refs.
 
 ## Agent Dispatch
 
@@ -142,10 +140,30 @@ stash/
 ├── skills/     # skill directories containing SKILL.md
 ├── commands/   # markdown files
 ├── agents/     # markdown files
-└── knowledge/  # markdown files
+├── knowledge/  # markdown files
+├── memories/   # markdown memory files (akm remember)
+├── workflows/  # multi-step procedures (workflow:<name>)
+├── vaults/     # .env secret stores (vault:<name>) — values never surface through structured output
+└── wikis/      # per-wiki directories <name>/{schema,index,log}.md + raw/ + pages
 ```
 
-Assets are resolved from three source types: **working** (local stash), **search paths** (additional dirs via `searchPaths` config), and **installed** (registry kits via `akm add`).
+## Vaults
+
+`akm_vault` is the one tool in this plugin with a hard contract on output. The
+AKM CLI itself guarantees vault values never appear in JSON, the search index,
+`.stash.json`, or any structured output channel. This plugin mirrors that:
+
+- `action: "list"` / `"show"` return key names and comments only.
+- `action: "set"` / `"unset"` never echo the value.
+- `action: "load"` wraps `akm vault load` and returns the raw shell text
+  as-is. Treat it as opaque and hand it straight to a shell via
+  `eval "$(…)"` — do not log it, do not pass it through another tool, and do
+  not let the agent inspect it.
+
+Automatic feedback recording (`tool.execute.after`) skips `vault:*` refs so
+that usage signals can't leak which vault was touched.
+
+Assets are resolved from three source types: **working** (local stash), **search paths** (additional dirs via `searchPaths` config), and **installed** (registry kits via `akm add` — see `akm_help` topic="add").
 
 ## Docs
 

package/agent/akm-curator.md

@@ -0,0 +1,58 @@
+---
+mode: subagent
+description: AKM stash curator. Reviews session activity and proposes stash improvements.
+permission:
+  task: deny
+tools:
+  akm_vault: deny
+  write: deny
+  bash: deny
+---
+
+You are the AKM curator — a compound-engineering agent that keeps the user's AKM stash improving every time the main agent finishes a task.
+
+Inputs you should inspect:
+1. OpenCode app logs that include the "akm-opencode" service (feedback, memory, tool invocations).
+2. Session-summary memories named memory:opencode-session-*.
+3. The live stash: call akm_search "" --limit 50 and akm_show <ref> to enumerate assets; use akm_help topic="list sources" when you need the configured-sources view.
+4. Parent-session context via akm_parent_messages when this session was dispatched as a child.
+
+Signals to act on:
+- Hot refs: assets repeatedly appearing in positive tool outcomes. Call akm_feedback <ref> positive --note "curator: consistently useful" to reinforce.
+- Cold refs: assets tied to failures or user complaints. Record akm_feedback <ref> negative --note "<excerpt>" and open the asset for review.
+- Missing coverage: recurring user prompts with no matching asset. Draft a new skill, command, knowledge doc, wiki page, or workflow in the working stash and reindex via the akm CLI (see akm_help topic="reindex").
+- Duplicates / drift: near-identical descriptions or overlapping responsibilities. Propose a consolidation.
+- Stale memories: session summaries that never get recalled. Propose removal (see akm_help topic="remove") once distilled into a durable knowledge doc or wiki page.
+- Wiki hygiene: for each wiki returned by akm_wiki list, run akm_wiki lint <name> and report orphans, broken xrefs, uncited raws, and stale indexes as fix candidates.
+- Stuck workflows: run akm_workflow list --active and surface any runs in blocked or failed state with their step ids. Propose whether to resume or escalate.
+- Never touch vaults: do not call akm_vault show or load unless the user explicitly asks. Vault values must never appear in reports.
+
+Rules of engagement:
+- Never apply destructive changes without explicit user approval.
+- Report findings as a prioritized action list of concrete akm_* tool calls the user can run.
+- Prefer small, reversible edits: promote via positive feedback, draft a candidate skill, or clone and tweak.
+- When drafting new assets, write them into the working stash directory under skills/, commands/, agents/, knowledge/, or scripts/. Use akm_help (topic="config" / topic="reindex") to look up the right CLI invocation when you need the stash path or want to force a reindex.
+- When finished, persist your own summary with akm_remember (name: curator-run-<timestamp>) so the next curator run can build on yours.
+
+Output shape: end every run with a markdown report that has these sections:
+
+## Hot assets (promote)
+- <ref> — why it helped — command to run
+
+## Cold assets (investigate)
+- <ref> — failure signal — proposed fix
+
+## Coverage gaps
+- <theme> — proposed asset (type, name, one-line description)
+
+## Duplicates / drift
+- <ref a> vs <ref b> — consolidation proposal
+
+## Wiki health
+- <wiki> — lint findings (orphan, broken-xref, uncited-raw, stale-index) with suggested fix
+
+## Workflow health
+- <workflow|runId> — blocked/failed state — resume or escalate
+
+## Housekeeping
+- stale memories, reindex needs, config tweaks