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

package/CHANGELOG.md

@@ -6,6 +6,39 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- **Per-type SOFT authoring conventions are now user-editable stash facts.** A
+  third authoring-guidance layer joins the hard rules (#645) and general stash
+  standards (#642): a stash owner can author
+  `facts/conventions/assets/<type>.md` (e.g. `…/skill.md`, `…/command.md`) to
+  capture soft, type-specific guidance — voice, structure, length *preference*,
+  naming style. When an agent authors a `skill:x`, the body of
+  `fact:conventions/assets/skill` is injected (type-scoped — authoring
+  `command:y` pulls the `command` convention, never the `skill` one), labeled
+  as soft guidance and kept separate from the validator-enforced hard rules.
+  The basename must be a `getAssetTypes()`-validated asset type; facts are read
+  straight from disk (no index rebuild) and degrade to empty safely. When no
+  per-type fact exists, the built-in `TYPE_HINTS` fallback is unchanged (no
+  regression). These facts carry soft conventions only and can never weaken the
+  authoring contract the gate enforces (`authoringRulesForType` remains the sole
+  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
 
 ### Added

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/dist/core/standards/resolve-standards-context.js

@@ -17,8 +17,24 @@
  */
 import { extractWikiNameFromRef, INDEX_MD, LOG_MD, loadWikiSchema, SCHEMA_MD } from "../../wiki/wiki.js";
 import { resolveStashStandards } from "./resolve-stash-standards.js";
+import { resolveTypeConventions, typeConventionRef } from "./resolve-type-conventions.js";
 /** Wiki infra files that are not authored pages (relative to the wiki root). */
 const WIKI_INFRA_BASENAMES = new Set([SCHEMA_MD, INDEX_MD, LOG_MD]);
+/**
+ * Extract the asset type from a canonical ref (`[origin//]type:name`) without
+ * throwing. Returns `undefined` for refs that have no `type:` prefix. Kept local
+ * and lenient — the per-type resolver validates the result against
+ * `getAssetTypes()`, so a bogus prefix here simply yields no convention.
+ */
+function refType(ref) {
+    if (!ref)
+        return undefined;
+    const body = ref.includes("//") ? ref.slice(ref.indexOf("//") + 2) : ref;
+    const colon = body.indexOf(":");
+    if (colon <= 0)
+        return undefined;
+    return body.slice(0, colon).trim() || undefined;
+}
 /**
  * Resolve the standards context for a write target identified by its asset ref.
  *
@@ -30,8 +46,23 @@ const WIKI_INFRA_BASENAMES = new Set([SCHEMA_MD, INDEX_MD, LOG_MD]);
 export function resolveStandardsContext(ref, stashRoot) {
     const wikiName = ref ? extractWikiNameFromRef(ref) : undefined;
     if (!wikiName) {
-        // Non-wiki asset target → Feature B (stash authoring standards).
-        return resolveStashStandards(stashRoot);
+        // Non-wiki asset target → Feature B (general stash standards) plus the
+        // per-type SOFT conventions layer (#646), type-scoped to the write target.
+        const general = resolveStashStandards(stashRoot);
+        const type = refType(ref);
+        // A non-empty body here guarantees `type` is a `getAssetTypes()`-validated
+        // string (the resolver returns "" otherwise).
+        const typeConventions = type ? resolveTypeConventions(stashRoot, type) : "";
+        if (!typeConventions || !type)
+            return general;
+        // Soft, type-scoped guidance — clearly labeled and kept separate from the
+        // HARD (validator-enforced) rules that `authoringRulesForType` injects
+        // downstream. These facts are advice only; they never weaken the gate.
+        const softSection = [
+            `# ${typeConventionRef(type)} (soft per-type conventions — guidance, not enforced)`,
+            typeConventions,
+        ].join("\n");
+        return general ? `${general}\n\n${softSection}` : softSection;
     }
     // Wiki target. Extract the page path after `wiki:<name>/`.
     const prefix = `wiki:${wikiName}/`;

package/dist/core/standards/resolve-stash-standards.js

@@ -21,6 +21,13 @@ import { parseFrontmatter } from "../asset/frontmatter.js";
 const STANDARD_CATEGORIES = new Set(["convention", "meta"]);
 /** Directory (under the stash root) where `fact` assets live. */
 const FACTS_SUBDIR = "facts";
+/**
+ * Per-type SOFT convention facts (`facts/conventions/assets/<type>.md`, #646)
+ * are surfaced **type-scoped** through `resolveTypeConventions`, so they must
+ * NOT leak into this un-type-scoped general layer (authoring a `command` must
+ * not pull the `skill` convention). Excluded by relative path (POSIX form).
+ */
+const TYPE_CONVENTIONS_REL = "conventions/assets/";
 /**
  * Recursively collect `.md` files under `dir` in stable (sorted) enumeration
  * order. Returns absolute paths. Missing dir → `[]`.
@@ -59,6 +66,11 @@ export function resolveStashStandards(stashRoot) {
     const factsRoot = path.join(stashRoot, FACTS_SUBDIR);
     const sections = [];
     for (const absPath of collectMarkdownFiles(factsRoot)) {
+        // Per-type SOFT conventions are delivered type-scoped (#646); skip them
+        // here so they never leak un-type-scoped into every authoring flow.
+        const relPosix = path.relative(factsRoot, absPath).split(path.sep).join("/");
+        if (relPosix.startsWith(TYPE_CONVENTIONS_REL))
+            continue;
         let raw;
         try {
             raw = fs.readFileSync(absPath, "utf8");

package/dist/core/standards/resolve-type-conventions.js

@@ -0,0 +1,66 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Resolve **per-type SOFT authoring conventions** (#646) — the third and final
+ * authoring-guidance layer:
+ *
+ *   1. HARD rules (validator-rejecting, code-sourced) → `authoringRulesForType()`
+ *      (`src/core/authoring-rules.ts`, #645). Never editable; the gate enforces them.
+ *   2. General stash standards (cross-type naming/tag conventions) →
+ *      `resolveStashStandards()` `category: convention|meta` facts (#642).
+ *   3. **Per-type SOFT conventions** (voice, structure, length *preference* for
+ *      *this* asset type) → user-editable `facts/conventions/assets/<type>.md`
+ *      (THIS module). Augments the built-in `TYPE_HINTS` fallback for display.
+ *
+ * These facts are **soft only** — advice, not contract. They MUST NOT carry
+ * hard, validator-rejecting rules: a user editing or deleting one must never be
+ * able to weaken the authoring contract the gate enforces (#645 boundary).
+ *
+ * Selection is by a `getAssetTypes()`-validated basename: only
+ * `facts/conventions/assets/<known-type>.md` resolves. Read directly from disk
+ * (no index rebuild); any missing dir/file, unknown type, or read error degrades
+ * to `""` and never throws.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getAssetTypes } from "../asset/asset-spec.js";
+import { parseFrontmatter } from "../asset/frontmatter.js";
+/** Sub-path (under the stash root) for per-type SOFT convention facts. */
+export const TYPE_CONVENTIONS_SUBDIR = path.join("facts", "conventions", "assets");
+/** The `fact:` ref prefix for a per-type convention, e.g. `fact:conventions/assets/skill`. */
+export function typeConventionRef(type) {
+    return `fact:conventions/assets/${type}`;
+}
+/**
+ * Read the SOFT authoring-convention body for asset type `type`, if a stash
+ * owner has authored `facts/conventions/assets/<type>.md`.
+ *
+ * @returns the trimmed markdown body (frontmatter stripped), or `""` when the
+ *          type is unknown, the file is absent, or anything goes wrong.
+ */
+export function resolveTypeConventions(stashRoot, type) {
+    if (!stashRoot || !type)
+        return "";
+    // Basename MUST be a known asset type — never resolve an arbitrary file.
+    if (!getAssetTypes().includes(type))
+        return "";
+    const abs = path.join(stashRoot, TYPE_CONVENTIONS_SUBDIR, `${type}.md`);
+    let raw;
+    try {
+        raw = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return ""; // missing dir/file or read error → degrade to empty
+    }
+    let body = "";
+    try {
+        body = parseFrontmatter(raw).content;
+    }
+    catch {
+        // Malformed frontmatter: fall back to the whole file (parseFrontmatter
+        // normally returns whole content as body, but guard defensively).
+        body = raw;
+    }
+    return body.trim();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.37",
+  "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": [