akm-cli 0.9.0-beta.5 → 0.9.0-beta.51

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.