akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

package/dist/assets/prompts/workflow-unit-preamble.md

@@ -0,0 +1,26 @@
+You are executing one unit of an akm workflow run.
+
+- Workflow run: {{RUN_ID}}
+- Step: {{STEP_ID}}
+- Unit: {{UNIT_ID}}
+- Run parameters: {{PARAMS_JSON}}
+
+Ground rules for this unit:
+
+1. Pull knowledge on demand instead of guessing: `akm search '<query>'` to find
+   relevant assets, `akm show <ref>` to read one, `akm curate '<query>'` to let
+   akm select the best match. Only pull what this unit actually needs.
+2. Environment values and secrets are provided through your process
+   environment when the workflow declares them. Never print secret values to
+   stdout or embed them in your answer. If you need an env file path, use
+   `akm env path <ref>`; never `cat` secrets.
+3. Do exactly the work described in the instructions below — no more. Other
+   units may be running concurrently on sibling items; do not touch files or
+   state outside the scope this unit was given.
+4. Your final output IS the unit result recorded by the engine. When a JSON
+   schema is requested, respond with ONLY the JSON value (no prose, no code
+   fences). Otherwise finish with a concise factual summary of what you did.
+
+Unit instructions follow.
+
+---

package/dist/assets/stash-skeleton/facts/conventions/assets/agent.md

@@ -0,0 +1,38 @@
+---
+category: convention
+description: Soft authoring conventions for agent assets using scoped role, tool, and maintenance rules.
+when_to_use: Surfaced to authoring agents when they write or revise an agent asset.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Agent authoring conventions
+
+An agent asset defines a reusable role. Treat it like a disciplined maintainer, not a generic personality. Its job is to know its scope, read the right rulebooks, use the right tools, and leave the stash in better shape.
+
+## Purpose
+
+Use an agent when a recurring task benefits from a specialized role, bounded responsibilities, and explicit tool behavior.
+
+## Authoring strategy
+
+- Write the description so a dispatcher knows exactly when to delegate to this agent.
+- Define the agent’s domain, authority, boundaries, and expected output.
+- Specify what the agent must read first: relevant stash standards, type conventions, reference docs, source files, or prior lessons.
+- State tool expectations plainly: what tools it may use, what it should avoid, and when it must ask for human review.
+- Give the agent maintenance duties when appropriate: update cross-references, append logs, preserve provenance, and surface contradictions.
+- Prefer a narrow role that does one thing reliably over a broad do-everything persona.
+- Include handoff behavior: what the agent should return when it cannot complete the task safely.
+
+## Maintenance strategy
+
+- Refine the agent when repeated sessions show the same delegation failure.
+- Add explicit negative guidance when the agent overreaches.
+- Keep role instructions stable and concise; move large background material into knowledge assets.
+- Use lessons to capture operational improvements, then promote stable ones into the agent when they become part of the role.

package/dist/assets/stash-skeleton/facts/conventions/assets/command.md

@@ -0,0 +1,38 @@
+---
+category: convention
+description: Soft authoring conventions for command assets using repeatable LLM operation patterns.
+when_to_use: Surfaced to authoring agents when they write or revise a command asset.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Command authoring conventions
+
+A command is a reusable markdown prompt template invoked by name. Treat it like an operation in the stash: every vague instruction will compound into repeated vague output.
+
+## Purpose
+
+Use a command when the user or agent needs to perform the same prompt-shaped task repeatedly with different arguments or context.
+
+## Authoring strategy
+
+- Put the task, inputs, constraints, and expected output shape near the top.
+- Make argument placeholders obvious and describe what each one should contain.
+- Tell the model what to inspect before acting, especially relevant stash assets, facts, standards, or reference docs.
+- State the decision boundary: what the command should do directly, what it should only propose, and what it should refuse or defer.
+- Include output requirements that are stable across runs.
+- Keep the prompt tight. A command should be easy to invoke and hard to misinterpret.
+- Avoid embedding one-time project details unless the command is intentionally project-specific.
+
+## Maintenance strategy
+
+- If users repeatedly clarify the same missing detail, add that detail to the command.
+- If command output regularly becomes useful durable knowledge, instruct the agent to file the result into the right asset type.
+- If the command starts handling multiple unrelated tasks, split it into smaller commands.
+- Preserve a clear invocation contract so future agents can call the command safely.

package/dist/assets/stash-skeleton/facts/conventions/assets/fact.md

@@ -0,0 +1,39 @@
+---
+category: convention
+description: Soft authoring conventions for fact assets using pinned-core and just-in-time context principles.
+when_to_use: Surfaced to authoring agents when they write or revise a fact asset.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Fact authoring conventions
+
+A fact is durable stash-level context: personal, team, project, convention, or meta knowledge. Treat facts as the stash’s semantic layer — selectively loaded context that should guide future work without bloating every prompt.
+
+## Purpose
+
+Use a fact for stable information that future agents should treat as true or normative: user preferences, project identity, team stack, architecture principles, naming conventions, tag vocabulary, or stash organization.
+
+## Authoring strategy
+
+- Write each fact as a standing declaration that can survive across sessions.
+- Keep it short, high-signal, and self-contained.
+- Choose the narrowest useful category: personal, team, project, convention, or meta.
+- Use `pinned: true` only for the small core that should be available constantly.
+- Leave most facts unpinned so they can be retrieved just-in-time.
+- Include scope and provenance when a fact is project-specific, inferred, or subject to change.
+- Separate facts from memories: memories preserve observations; facts state durable truth or durable policy.
+- Separate facts from knowledge: knowledge explains a topic; facts declare compact context.
+
+## Maintenance strategy
+
+- Revise or supersede facts when the durable truth changes.
+- Do not allow contradictory facts to remain equally active.
+- Promote repeated memories or lessons into facts only when they become stable context.
+- Keep convention and meta facts especially clear, because they steer future asset creation.

package/dist/assets/stash-skeleton/facts/conventions/assets/knowledge.md

@@ -0,0 +1,40 @@
+---
+category: convention
+description: Soft authoring conventions for knowledge assets as compiled, on-demand reference documents.
+when_to_use: Surfaced to authoring agents when they write or revise a knowledge asset.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Knowledge authoring conventions
+
+A knowledge asset is a compiled reference document meant to be read on demand. Treat it as the synthesized layer above raw material: not source files, not chat residue, but integrated, navigable understanding that saves future agents from rediscovering the same material.
+
+## Purpose
+
+Use a knowledge asset for durable reference material, synthesized explanations, design notes, comparisons, and project context that is broader than a single memory but less procedural than a skill.
+
+## Authoring strategy
+
+- Open with a plain top-level title that names the subject.
+- Add a concise orientation paragraph: what this document covers and when it should be read.
+- For a long reference, add a table of contents near the top so the full scope is visible even on a partial read.
+- Organize by stable concepts, decisions, entities, or questions — roughly one page per concept.
+- Cross-reference related assets instead of duplicating them, so a navigable graph forms over time.
+- Preserve provenance where it matters: cite source files, raw notes, session logs, or issues by path/ref.
+- Call out contradictions, uncertainty, stale claims, and open questions explicitly.
+- Prefer accurate synthesis over exhaustive dumping. Raw material belongs elsewhere; this file is the compiled layer.
+- Use tables or checklists when they make retrieval and comparison easier.
+
+## Maintenance strategy
+
+- Update the existing page when new information changes the same topic; append a dated note rather than silently rewriting when provenance matters.
+- Create a new page when the concept deserves its own durable entry.
+- Add links both ways when a new relationship matters.
+- Periodically scan for orphaned, stale, or overlapping knowledge docs and consolidate them.

package/dist/assets/stash-skeleton/facts/conventions/assets/lesson.md

@@ -0,0 +1,43 @@
+---
+category: convention
+description: Soft authoring conventions for lesson assets that capture compounding, hard-won judgment.
+when_to_use: Surfaced to authoring agents when they write or revise a lesson asset.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Lesson authoring conventions
+
+A lesson captures durable, hard-won judgment that should compound across future agent sessions. Treat it as distilled judgment about how to act: it should preserve the extracted meaning of what real use revealed, not merely recount an incident or summarize another asset.
+
+## Purpose
+
+Use a lesson to record:
+
+- when to reach for a pattern, asset, or decision;
+- what tends to go wrong without it;
+- what evidence, feedback, or repeated experience made the lesson worth keeping;
+- how a future agent should act differently because this lesson exists.
+
+## Authoring strategy
+
+- Lead with the trigger: the concrete situation where this lesson should be loaded.
+- Follow with the failure mode: what mistake, omission, or confusion this prevents.
+- End with the reusable judgment: the practical rule a future agent can apply.
+- Keep the scope narrow. A lesson should teach one durable behavior.
+- Prefer observed evidence over generic advice. Mention the kind of signal that produced the lesson, such as rejected proposals, repeated lint findings, user feedback, or session outcomes.
+- Do not restate the source asset. Lessons are compiled judgment, not copied documentation.
+- Write for a future agent mid-task: direct, practical, and easy to apply.
+
+## Maintenance strategy
+
+- Update an existing lesson when new feedback sharpens the same judgment.
+- Create a new lesson only when the trigger or failure mode is meaningfully different.
+- Deprecate or revise stale lessons instead of allowing contradictory guidance to accumulate.
+- When a lesson becomes broadly normative, consider promoting the stable rule into a `fact:conventions/...` asset.

package/dist/assets/stash-skeleton/facts/conventions/assets/memory.md

@@ -0,0 +1,38 @@
+---
+category: convention
+description: Soft authoring conventions for memory assets using durable-context and provenance discipline.
+when_to_use: Surfaced to authoring agents when they write or revise a memory asset.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Memory authoring conventions
+
+A memory is a short, durable note that should survive beyond the current session. Treat it as a small compiled fact or decision, not a transcript fragment.
+
+## Purpose
+
+Use a memory when a future agent would make a better decision by knowing a specific user preference, project decision, environmental fact, constraint, or observed outcome.
+
+## Authoring strategy
+
+- Record one durable fact, decision, or constraint per memory.
+- Write it so it stands alone without the original conversation.
+- Include enough context to prevent misapplication: subject, scope, and when it matters.
+- Prefer stable, reusable information over step-by-step session play-by-play.
+- Mark uncertainty or subjectivity clearly when the memory is not a settled fact.
+- Preserve source/provenance in frontmatter or body when the memory came from a session, log, user statement, or derived inference.
+- Avoid storing secrets, private tokens, or volatile temporary state as memory.
+
+## Maintenance strategy
+
+- Update or supersede memories when newer evidence changes the truth.
+- Consolidate repeated memories into a clearer fact or knowledge asset.
+- Convert broad, stable conventions into `fact` assets.
+- Archive memories that are no longer current rather than letting stale context keep influencing agents.

package/dist/assets/stash-skeleton/facts/conventions/assets/script.md

@@ -0,0 +1,43 @@
+---
+category: convention
+description: Soft authoring conventions for script assets using agent-safe CLI helper principles.
+when_to_use: Surfaced to authoring agents when they write or revise a script asset.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Script authoring conventions
+
+A script is an executable helper that an agent or human can run on demand. Treat it like a small, deterministic tool that reduces manual bookkeeping and makes repeatable operations safer.
+
+## Purpose
+
+Use a script when a task is mechanical, repeatable, and better handled by a deterministic program than by free-form agent edits.
+
+## Authoring strategy
+
+- Start with the appropriate interpreter line and a short usage comment.
+- State what the script does, expected inputs, outputs, side effects, and failure behavior.
+- Keep one script focused on one job.
+- Validate inputs before mutation.
+- Fail loudly and early on unsafe or ambiguous input.
+- Declare required dependencies and assumptions explicitly rather than assuming a tool is installed.
+- Justify any non-obvious constant (timeout, retry count, limit) in a comment so a future reader can adjust it safely.
+- Prefer idempotent behavior where practical.
+- Avoid hidden network calls, destructive defaults, or silent writes.
+- Never print secrets or sensitive values.
+- Write output that is easy for both humans and agents to parse.
+- Favor clear names, straightforward control flow, and comments at decision points.
+
+## Maintenance strategy
+
+- Add examples when agents or users repeatedly invoke the script incorrectly.
+- Keep dangerous actions behind explicit flags.
+- When a script becomes a core operation, add or update a workflow that explains when to run it.
+- If the script encodes a convention, also document that convention in a fact or knowledge asset.

package/dist/assets/stash-skeleton/facts/conventions/assets/skill.md

@@ -0,0 +1,40 @@
+---
+category: convention
+description: Soft authoring conventions for skill assets as reusable, just-in-time procedural rulebooks.
+when_to_use: Surfaced to authoring agents when they write or revise a skill asset.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Skill authoring conventions
+
+A skill is a reusable, self-contained capability stored as `skills/<name>/SKILL.md`. Treat it like a compact operating manual that an agent can load just-in-time, follow without rediscovering the process, and improve when repeated use exposes gaps.
+
+## Purpose
+
+Use a skill when the stash needs reusable procedural guidance for a recurring class of work. A good skill reduces repeated reasoning cost: future agents should not have to reconstruct the same method from raw context.
+
+## Authoring strategy
+
+- Make the dispatch signal clear. The description should let a dispatcher decide whether to load the skill without reading the whole body.
+- Open with the outcome the skill helps produce.
+- State when to use it, when not to use it, and what inputs the agent should gather before acting.
+- Structure the body as a rulebook: principles first, then procedure, then checks.
+- Use short sections and ordered steps where sequence matters.
+- Match the level of detail to how fragile the task is: open-ended work gets high-level heuristics and room to reason, while fragile or consistency-critical steps get exact, unambiguous instructions.
+- Keep the body lean and move bulky background into companion knowledge docs referenced one level deep, so the skill loads cheaply and stays scannable.
+- Include failure modes and verification steps. A skill should tell the agent how to know the work is complete.
+- Keep one skill focused on one capability. Split unrelated concerns into separate skills and cross-reference them.
+
+## Maintenance strategy
+
+- Update the skill when session logs, feedback, or rejected proposals reveal repeatable confusion.
+- Add companion knowledge docs when the skill needs background material that would bloat the main procedure.
+- Promote durable recurring corrections into the skill; leave one-off observations in memories or lessons.
+- Prefer small edits that preserve the skill’s operational shape over broad rewrites that erase tested guidance.

package/dist/assets/stash-skeleton/facts/conventions/assets/workflow.md

@@ -0,0 +1,43 @@
+---
+category: convention
+description: Soft authoring conventions for workflow assets using explicit operations, logging, and lintable steps.
+when_to_use: Surfaced to authoring agents when they write or revise a workflow asset.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Workflow authoring conventions
+
+A workflow describes an ordered process an agent or human can follow. Treat it as the operation layer of a maintained stash: clear steps, clear state, clear completion criteria, and enough bookkeeping to resume safely.
+
+## Purpose
+
+Use a workflow when the task requires multiple steps, branching decisions, repeated checks, or durable progress tracking.
+
+## Authoring strategy
+
+- Open with the outcome the workflow produces.
+- State prerequisites, required inputs, and tools before the steps.
+- Use ordered step sections when sequence matters.
+- For each step, specify:
+  - what to do;
+  - what evidence or input it depends on;
+  - what output it produces;
+  - how to know the step is done.
+- Make branch points explicit. Do not bury conditional behavior in prose.
+- Include validation, lint, or review steps near the end.
+- Include rollback or recovery notes when the workflow mutates files, state, repos, or external systems.
+- Keep steps atomic and resumable so an interrupted run can continue without guessing.
+
+## Maintenance strategy
+
+- Update the workflow when repeated execution reveals missing checks or unclear handoffs.
+- Add logging expectations when the workflow creates durable state.
+- Extract reusable sub-procedures into skills or scripts when the workflow grows too broad.
+- Record recurring mistakes as lessons, then fold stable corrections back into the workflow.