akm-cli 0.9.0-beta.38 → 0.9.0-beta.39

package/CHANGELOG.md

@@ -25,6 +25,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   source of validator-rejecting rules). The general convention/meta resolver now
   excludes `facts/conventions/assets/*` so per-type guidance never leaks
   un-type-scoped into other authoring flows. (#646)
+- **`akm init` now seeds default per-type SOFT convention templates.** Starter
+  `facts/conventions/assets/<type>.md` templates ship in the stash skeleton for
+  the authored types (`lesson, skill, command, agent, knowledge, memory,
+  workflow, script, fact`; `wiki`/`env`/`secret` excluded) so a stash owner has
+  an editable starting point. Each expands the matching built-in `TYPE_HINTS`
+  one-liner into soft starter guidance, carries `category: convention`
+  frontmatter, and states in-body that it is advice, not enforced — it carries
+  **no** validator-rejecting rules, so editing or deleting one cannot weaken the
+  gate (#645). The stash-skeleton copy is now recursive (preserving nested
+  subpaths), and `akm init` seeds **unconditionally** rather than only on first
+  create: re-running it on an existing stash backfills any missing skeleton,
+  convention, or `.meta/index.md` files. Seeding stays absent-only and never
+  overwrites a user-edited file. (#646)
 
 ## [0.9.0-beta.36] — 2026-06-22
 

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

@@ -0,0 +1,22 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for agent assets — edit to taste.
+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; the validator-rejecting HARD rules live in
+  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
+  or deleting this file cannot weaken the gate.
+-->
+
+# Agent authoring conventions
+
+An agent is markdown whose frontmatter describes a reusable role.
+
+- Frontmatter typically carries `name`, `description`, and optionally `tools` and
+  `model`. Write the `description` so a dispatcher knows exactly when to delegate.
+- The body is the system prompt: establish the role, its scope, and its boundaries.
+- Be explicit about what the agent should and should not do, and what it returns.
+- Prefer a focused single-responsibility persona over a broad do-everything agent.

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

@@ -0,0 +1,22 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for command assets — edit to taste.
+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; the validator-rejecting HARD rules live in
+  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
+  or deleting this file cannot weaken the gate.
+-->
+
+# Command authoring conventions
+
+A command is a markdown prompt template the user invokes by name.
+
+- Optional frontmatter carries `name` and `description`; the body *is* the prompt.
+- Write the body as the instruction you want the model to follow when invoked.
+- State the task, the expected inputs, and the shape of the desired output up front.
+- Keep it tight and unambiguous — a command is run repeatedly, so vagueness compounds.
+- Use clear placeholders for any arguments the caller will supply.

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

@@ -0,0 +1,24 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for fact assets — edit to taste.
+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; the validator-rejecting HARD rules live in
+  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
+  or deleting this file cannot weaken the gate.
+-->
+
+# Fact authoring conventions
+
+A fact is durable stash-level context — personal, team, or project details,
+coding conventions, or stash-meta.
+
+- Frontmatter should include a `description` and a `category`
+  (personal | team | project | convention | meta).
+- Set `pinned: true` only for the small always-injected core; most facts stay unpinned.
+- Keep each fact short, high-signal, and self-contained — it is durable context,
+  not an episodic note.
+- Write it as a standing declaration that stays true across sessions.

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

@@ -0,0 +1,22 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for knowledge assets — edit to taste.
+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; the validator-rejecting HARD rules live in
+  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
+  or deleting this file cannot weaken the gate.
+-->
+
+# Knowledge authoring conventions
+
+A knowledge asset is a reference document meant to be read on demand.
+
+- Open with a top-level `# Title` that names the subject plainly.
+- Organise into concise, well-headed sections so a reader can jump to what they need.
+- Favour accuracy and clarity over completeness; link or cross-reference rather than
+  duplicating other assets.
+- Voice: explanatory and neutral, written to be re-read months later.

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

@@ -0,0 +1,25 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for lesson assets — edit to taste.
+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; the validator-rejecting HARD rules live in
+  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
+  or deleting this file cannot weaken the gate. Tune the guidance below to match
+  how your stash likes lessons written.
+-->
+
+# Lesson authoring conventions
+
+A lesson captures durable, hard-won judgement about *when* to reach for something
+and *what goes wrong without it* — it is not a restatement of the source asset.
+
+- Lead with the trigger: when should a reader reach for this lesson?
+- Then the failure mode: what breaks, or what gets missed, without it?
+- Then the insight: what did real use reveal that the asset itself does not say?
+- Keep it to one to three short, concrete paragraphs. Prefer specifics over
+  general advice; a lesson earns its keep by being actionable in a real moment.
+- Voice: direct and practical, written for a future agent mid-task.

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

@@ -0,0 +1,21 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for memory assets — edit to taste.
+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; the validator-rejecting HARD rules live in
+  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
+  or deleting this file cannot weaken the gate.
+-->
+
+# Memory authoring conventions
+
+A memory is a short factual note the user wants persisted across sessions.
+
+- Frontmatter usually includes a `description` that states the fact in one line.
+- Keep the body brief and self-contained — one durable fact or decision per memory.
+- Write it so it still reads clearly with no surrounding conversation for context.
+- Prefer durable, reusable facts over episodic play-by-play of a single session.

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

@@ -0,0 +1,21 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for script assets — edit to taste.
+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; the validator-rejecting HARD rules live in
+  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
+  or deleting this file cannot weaken the gate.
+-->
+
+# Script authoring conventions
+
+A script is an executable text file stored as-is and run on demand.
+
+- Start with a shebang appropriate to the interpreter (e.g. `#!/usr/bin/env bash`).
+- Follow it with a short usage comment: what the script does and how to invoke it.
+- Keep the script focused on one job; fail loudly and early on bad input.
+- Prefer readable, well-commented logic over cleverness — these get re-run by others.

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

@@ -0,0 +1,23 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for skill assets — edit to taste.
+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; the validator-rejecting HARD rules live in
+  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
+  or deleting this file cannot weaken the gate.
+-->
+
+# Skill authoring conventions
+
+A skill is a reusable, self-contained capability stored as `skills/<name>/SKILL.md`.
+
+- Frontmatter usually carries `name`, `description`, and `when_to_use`. Write the
+  `description` so a dispatcher can decide *from it alone* whether to load the skill.
+- Open the body with the goal in an imperative voice ("Generate…", "Review…").
+- Structure as: purpose, when to use, then the procedure or guidance as ordered
+  steps or short sections. Favour scannable headings over long prose.
+- Keep it focused on one capability; split unrelated concerns into separate skills.

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

@@ -0,0 +1,22 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for workflow assets — edit to taste.
+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; the validator-rejecting HARD rules live in
+  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
+  or deleting this file cannot weaken the gate.
+-->
+
+# Workflow authoring conventions
+
+A workflow describes a multi-step process an agent or human follows in order.
+
+- Open with a top-level `# <Title>` naming the workflow's outcome.
+- Lay out the steps as ordered `## Step N` sections, each with a clear action.
+- For each step, state what to do, what it depends on, and how to know it is done.
+- Keep steps atomic and resumable — a reader should be able to stop and pick up midway.
+- Note any branch points or preconditions explicitly rather than burying them in prose.

package/dist/commands/sources/init.js

@@ -75,10 +75,13 @@ export async function akmInit(options) {
     }
     // Ensure the default stash is a local git repo (no remote required)
     ensureGitRepo(stashDir);
-    if (created) {
-        copyStashSkeleton(stashDir);
-        scaffoldStashMeta(stashDir);
-    }
+    // Run seeding UNCONDITIONALLY (not just when the stash was newly created) so
+    // re-running `akm init` on an existing stash backfills any missing skeleton
+    // files — the README, the per-type SOFT convention templates under
+    // facts/conventions/assets/, and the `.meta/index.md` orientation doc. Both
+    // helpers are absent-only: they never overwrite a file a user has edited.
+    copyStashSkeleton(stashDir);
+    scaffoldStashMeta(stashDir);
     // Persist stashDir in config.json
     const configPath = getConfigPath();
     const existing = loadUserConfig();

package/dist/commands/sources/stash-skeleton.js

@@ -6,27 +6,42 @@ import path from "node:path";
 import { getDirname } from "../../runtime.js";
 const SKELETON_DIR = path.join(getDirname(import.meta.url), "../../assets/stash-skeleton");
 /**
- * Copy the default stash skeleton into a newly created stash directory.
+ * Copy the default stash skeleton into a stash directory.
  *
- * Each file in src/assets/stash-skeleton/ is written to the stash root only
- * if the destination does not already exist — existing files are never
- * overwritten. Non-fatal: if the skeleton directory is missing or a copy
- * fails the caller continues normally.
+ * The skeleton tree under src/assets/stash-skeleton/ is mirrored **recursively**
+ * into the stash root, preserving relative subpaths (e.g.
+ * `facts/conventions/assets/skill.md` lands at the matching stash subpath).
+ * Each file is written only if the destination does not already exist — existing
+ * (possibly user-edited) files are never overwritten. Intermediate directories
+ * are created as needed.
+ *
+ * Idempotent and absent-only: running it again on an existing stash backfills
+ * any skeleton files that are missing without clobbering present ones. Non-fatal:
+ * if the skeleton directory is missing or a copy fails the caller continues.
  */
 export function copyStashSkeleton(stashDir) {
+    copySkeletonDir(SKELETON_DIR, stashDir);
+}
+/** Recursively mirror `srcDir` into `destDir`, writing files only when absent. */
+function copySkeletonDir(srcDir, destDir) {
     let entries;
     try {
-        entries = fs.readdirSync(SKELETON_DIR);
+        entries = fs.readdirSync(srcDir, { withFileTypes: true });
     }
     catch {
         return;
     }
     for (const entry of entries) {
-        const src = path.join(SKELETON_DIR, entry);
-        const dest = path.join(stashDir, entry);
+        const src = path.join(srcDir, entry.name);
+        const dest = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            copySkeletonDir(src, dest);
+            continue;
+        }
         if (fs.existsSync(dest))
             continue;
         try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
             fs.copyFileSync(src, dest);
         }
         catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.38",
+  "version": "0.9.0-beta.39",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [