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

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.