mdkg 0.0.3 → 0.0.5

package/dist/graph/node.js

@@ -4,7 +4,7 @@ exports.ALLOWED_TYPES = exports.DEC_TYPES = exports.WORK_TYPES = void 0;
 exports.parseNode = parseNode;
 const frontmatter_1 = require("./frontmatter");
 const edges_1 = require("./edges");
-const ID_RE = /^[a-z]+-[0-9]+$/;
+const id_1 = require("../util/id");
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const DEC_ID_RE = /^dec-[0-9]+$/;
 exports.WORK_TYPES = new Set(["epic", "feat", "task", "bug", "checkpoint", "test"]);
@@ -23,6 +23,7 @@ exports.ALLOWED_TYPES = new Set([
     "test",
 ]);
 const DEC_STATUS = new Set(["proposed", "accepted", "rejected", "superseded"]);
+const SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function formatError(filePath, message) {
     return new Error(`${filePath}: ${message}`);
 }
@@ -74,11 +75,11 @@ function requireLowercaseList(values, key, filePath) {
     });
 }
 function isValidId(value) {
-    return ID_RE.test(value) || value === "rule-guide";
+    return (0, id_1.isCanonicalId)(value);
 }
 function requireIdFormat(value, key, filePath) {
     if (!isValidId(value)) {
-        throw formatError(filePath, `${key} must match <prefix>-<number>`);
+        throw formatError(filePath, `${key} must match <prefix>-<number> or reserved id`);
     }
     return value;
 }
@@ -104,11 +105,20 @@ function normalizeIdList(values, key, filePath) {
             throw formatError(filePath, `${key} entries must be lowercase`);
         }
         if (!isValidId(value)) {
-            throw formatError(filePath, `${key} entries must match <prefix>-<number>`);
+            throw formatError(filePath, `${key} entries must match <prefix>-<number> or reserved id`);
         }
         return value;
     });
 }
+function normalizeSkillList(values, filePath) {
+    return values.map((value, index) => {
+        const normalized = value.toLowerCase();
+        if (!SKILL_SLUG_RE.test(normalized)) {
+            throw formatError(filePath, `skills[${index}] must be kebab-case`);
+        }
+        return normalized;
+    });
+}
 function requireTemplateSchema(type, templateSchemas, filePath) {
     const schema = templateSchemas[type];
     if (!schema) {
@@ -192,6 +202,11 @@ function parseNode(content, filePath, options) {
     const artifacts = optionalList(frontmatter, "artifacts", filePath);
     const refs = normalizeIdList(optionalList(frontmatter, "refs", filePath), "refs", filePath);
     const aliases = requireLowercaseList(optionalList(frontmatter, "aliases", filePath), "aliases", filePath);
+    const skillsRaw = optionalList(frontmatter, "skills", filePath);
+    const skills = normalizeSkillList(skillsRaw, filePath);
+    if (skills.length > 0 && !exports.WORK_TYPES.has(type)) {
+        throw formatError(filePath, "skills is only allowed for work items");
+    }
     normalizeIdList(optionalList(frontmatter, "scope", filePath), "scope", filePath);
     const supersedesValue = optionalString(frontmatter, "supersedes", filePath);
     if (supersedesValue !== undefined) {
@@ -218,6 +233,7 @@ function parseNode(content, filePath, options) {
         artifacts,
         refs,
         aliases,
+        skills,
         edges,
         body,
         frontmatter,

package/dist/graph/skills_index_cache.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeSkillsIndex = writeSkillsIndex;
+exports.loadSkillsIndex = loadSkillsIndex;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const paths_1 = require("../core/paths");
+const skills_indexer_1 = require("./skills_indexer");
+function mtimeMs(filePath) {
+    return fs_1.default.statSync(filePath).mtimeMs;
+}
+function listFilesAndDirectories(dir) {
+    if (!fs_1.default.existsSync(dir)) {
+        return [];
+    }
+    const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    const items = [dir];
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            items.push(...listFilesAndDirectories(fullPath));
+            continue;
+        }
+        if (entry.isFile()) {
+            items.push(fullPath);
+        }
+    }
+    return items;
+}
+function isSkillsIndexStale(root, config) {
+    const indexPath = (0, skills_indexer_1.resolveSkillsIndexPath)(root);
+    if (!fs_1.default.existsSync(indexPath)) {
+        return true;
+    }
+    const indexMtime = mtimeMs(indexPath);
+    const cfgPath = (0, paths_1.configPath)(root);
+    if (fs_1.default.existsSync(cfgPath) && mtimeMs(cfgPath) > indexMtime) {
+        return true;
+    }
+    const skillsRoot = (0, skills_indexer_1.resolveSkillsRoot)(root, config);
+    for (const item of listFilesAndDirectories(skillsRoot)) {
+        if (mtimeMs(item) > indexMtime) {
+            return true;
+        }
+    }
+    return false;
+}
+function readSkillsIndex(indexPath) {
+    try {
+        const raw = fs_1.default.readFileSync(indexPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "unknown error";
+        throw new Error(`failed to read skills index: ${message}`);
+    }
+}
+function writeSkillsIndex(indexPath, index) {
+    const sortedSkills = {};
+    for (const slug of Object.keys(index.skills).sort()) {
+        sortedSkills[slug] = index.skills[slug];
+    }
+    const sortedIndex = {
+        ...index,
+        skills: sortedSkills,
+    };
+    fs_1.default.mkdirSync(path_1.default.dirname(indexPath), { recursive: true });
+    fs_1.default.writeFileSync(indexPath, JSON.stringify(sortedIndex, null, 2), "utf8");
+}
+function loadSkillsIndex(options) {
+    const useCache = options.useCache ?? true;
+    const allowReindex = options.allowReindex ?? options.config.index.auto_reindex;
+    const indexPath = (0, skills_indexer_1.resolveSkillsIndexPath)(options.root);
+    if (!useCache) {
+        const index = (0, skills_indexer_1.buildSkillsIndex)(options.root, options.config);
+        return { index, rebuilt: true, stale: false };
+    }
+    const stale = isSkillsIndexStale(options.root, options.config);
+    if (fs_1.default.existsSync(indexPath) && !stale) {
+        return { index: readSkillsIndex(indexPath), rebuilt: false, stale: false };
+    }
+    if (allowReindex) {
+        const index = (0, skills_indexer_1.buildSkillsIndex)(options.root, options.config);
+        writeSkillsIndex(indexPath, index);
+        return { index, rebuilt: true, stale };
+    }
+    if (fs_1.default.existsSync(indexPath)) {
+        return { index: readSkillsIndex(indexPath), rebuilt: false, stale: true };
+    }
+    throw new Error("skills index missing and auto-reindex is disabled");
+}

package/dist/graph/skills_indexer.js

@@ -0,0 +1,160 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_SLUG_RE = exports.SKILLS_INDEX_RELATIVE_PATH = void 0;
+exports.resolveSkillsRoot = resolveSkillsRoot;
+exports.resolveSkillsIndexPath = resolveSkillsIndexPath;
+exports.buildSkillIndexEntry = buildSkillIndexEntry;
+exports.buildSkillsIndex = buildSkillsIndex;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const frontmatter_1 = require("./frontmatter");
+exports.SKILLS_INDEX_RELATIVE_PATH = ".mdkg/index/skills.json";
+exports.SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function listSkillMarkdownFiles(dir) {
+    if (!fs_1.default.existsSync(dir)) {
+        return [];
+    }
+    const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const slug = entry.name.toLowerCase();
+        const skillDir = path_1.default.join(dir, entry.name);
+        const canonicalPath = path_1.default.join(skillDir, "SKILL.md");
+        const compatPath = path_1.default.join(skillDir, "SKILLS.md");
+        if (fs_1.default.existsSync(canonicalPath) && fs_1.default.existsSync(compatPath)) {
+            throw new Error(`${skillDir}: both SKILL.md and SKILLS.md exist`);
+        }
+        if (fs_1.default.existsSync(canonicalPath)) {
+            files.push({ slug, filePath: canonicalPath });
+            continue;
+        }
+        if (fs_1.default.existsSync(compatPath)) {
+            files.push({ slug, filePath: compatPath });
+        }
+    }
+    files.sort((a, b) => a.slug.localeCompare(b.slug));
+    return files;
+}
+function requireString(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${filePath}: ${key} is required and must be a non-empty string`);
+    }
+    return value;
+}
+function optionalString(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${filePath}: ${key} must be a non-empty string when set`);
+    }
+    return value;
+}
+function optionalList(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${filePath}: ${key} must be a list`);
+    }
+    return value;
+}
+function toLowercaseList(values) {
+    return values.map((value) => value.toLowerCase());
+}
+function extractOchatr(frontmatter) {
+    const keys = Object.keys(frontmatter)
+        .filter((key) => key.startsWith("ochatr_"))
+        .sort();
+    const extracted = {};
+    for (const key of keys) {
+        extracted[key] = frontmatter[key];
+    }
+    return extracted;
+}
+function hasDirectory(dirPath) {
+    if (!fs_1.default.existsSync(dirPath)) {
+        return false;
+    }
+    return fs_1.default.statSync(dirPath).isDirectory();
+}
+function rootWorkspaceMdkgPath(root, config) {
+    const rootWs = config.workspaces.root;
+    if (rootWs && rootWs.enabled) {
+        return path_1.default.resolve(root, rootWs.path, rootWs.mdkg_dir);
+    }
+    return path_1.default.resolve(root, ".mdkg");
+}
+function resolveSkillsRoot(root, config) {
+    return path_1.default.join(rootWorkspaceMdkgPath(root, config), "skills");
+}
+function resolveSkillsIndexPath(root) {
+    return path_1.default.resolve(root, exports.SKILLS_INDEX_RELATIVE_PATH);
+}
+function buildSkillIndexEntry(root, slug, filePath) {
+    if (!exports.SKILL_SLUG_RE.test(slug)) {
+        throw new Error(`${filePath}: skill slug must be kebab-case`);
+    }
+    const content = fs_1.default.readFileSync(filePath, "utf8");
+    const { frontmatter } = (0, frontmatter_1.parseFrontmatter)(content, filePath);
+    const name = requireString(frontmatter, "name", filePath);
+    const description = requireString(frontmatter, "description", filePath);
+    const version = optionalString(frontmatter, "version", filePath);
+    const tags = toLowercaseList(optionalList(frontmatter, "tags", filePath));
+    const authors = toLowercaseList(optionalList(frontmatter, "authors", filePath));
+    const links = optionalList(frontmatter, "links", filePath);
+    const skillDir = path_1.default.dirname(filePath);
+    return {
+        slug,
+        id: `skill:${slug}`,
+        qid: `root:skill:${slug}`,
+        ws: "root",
+        type: "skill",
+        name,
+        description,
+        tags,
+        version,
+        authors,
+        links,
+        path: path_1.default.relative(root, filePath),
+        has_scripts: hasDirectory(path_1.default.join(skillDir, "scripts")),
+        has_references: hasDirectory(path_1.default.join(skillDir, "references")),
+        ochatr: extractOchatr(frontmatter),
+    };
+}
+function buildSkillsIndex(root, config) {
+    const skillsRoot = resolveSkillsRoot(root, config);
+    const files = listSkillMarkdownFiles(skillsRoot);
+    const skills = {};
+    for (const file of files) {
+        const { slug, filePath } = file;
+        if (skills[slug]) {
+            throw new Error(`${filePath}: duplicate skill slug ${slug}`);
+        }
+        skills[slug] = buildSkillIndexEntry(root, slug, filePath);
+    }
+    const sortedSkills = {};
+    for (const slug of Object.keys(skills).sort()) {
+        sortedSkills[slug] = skills[slug];
+    }
+    return {
+        meta: {
+            tool: config.tool,
+            schema_version: config.schema_version,
+            generated_at: new Date().toISOString(),
+            root,
+            skills_root: path_1.default.relative(root, skillsRoot),
+            skill_count: Object.keys(sortedSkills).length,
+        },
+        skills: sortedSkills,
+    };
+}

package/dist/init/AGENTS.md

@@ -1,43 +1,8 @@
-# Agent Guidelines
+# AGENTS
 
-This repo uses mdkg for tasks, decisions, and context packs.
+Read `AGENT_START.md` first.
 
-## Quickstart
-
-- `mdkg init --llm`
-- `mdkg index`
-- `mdkg new task "..." --status todo --priority 1`
-- `mdkg list --status todo`
-- `mdkg pack <id> --verbose`
-- `mdkg validate`
-
-## Core commands
-
-- `mdkg init` (scaffold .mdkg and optional agent docs)
-- `mdkg guide` (print the repo guide)
-- `mdkg new <type> "<title>"` (create nodes)
-- `mdkg list` / `mdkg show` / `mdkg search`
-- `mdkg pack` (context bundles)
-- `mdkg next` (priority/chain)
-- `mdkg validate` / `mdkg format`
-
-## Getting context
-
-- Run `mdkg list --status todo` to find work items.
-- Before coding, run `mdkg pack <task-id> --verbose`.
-- Read linked rules and decisions in the pack.
-
-## Editing rules
-
-- Keep frontmatter valid and lowercase.
-- Update `updated: YYYY-MM-DD` when you make changes.
-- Use `links:` and `artifacts:` for anything you want searchable.
-
-## Validation
-
-- Run `mdkg validate` after edits.
-- Run `mdkg format` if frontmatter drifts.
-
-## Project-specific notes
-
-Add repo-specific build/test commands and conventions here.
+Codex/OpenAI conventions for this repo:
+- use `AGENT_START.md` as the startup contract
+- use `.agents/skills/` for product-facing mirrored skills when present
+- use `mdkg skill ...` as the canonical skill command family

package/dist/init/AGENT_START.md

@@ -0,0 +1,46 @@
+# AGENT_START
+
+This repository uses mdkg for deterministic project memory.
+
+Read these files in order:
+1. `.mdkg/core/SOUL.md` if it exists
+2. `.mdkg/core/HUMAN.md` if it exists
+3. `.mdkg/README.md`
+4. `CLI_COMMAND_MATRIX.md`
+
+Trust order:
+- source code
+- mdkg rules, design docs, decisions, and work nodes
+- SOUL/HUMAN collaboration anchors
+- relevant skills
+- chat history
+
+If the active task is known:
+- `mdkg pack <id>`
+- `mdkg task start <id>` when durable work begins
+- `mdkg task update <id> ...` as evidence accumulates
+- `mdkg task done <id>` when work is complete
+- `mdkg validate`
+
+If no task is known:
+- `mdkg search "..."`
+- `mdkg show <id>`
+- `mdkg next`
+- then use `mdkg pack <id>`
+
+Skill discovery:
+- `mdkg skill list --tags stage:plan --json`
+- `mdkg skill list --tags stage:execute --json`
+- `mdkg skill list --tags stage:review --json`
+- `mdkg skill show select-work-and-ground-context`
+
+Conventions:
+- `AGENTS.md` is the Codex/OpenAI-oriented wrapper doc.
+- `CLAUDE.md` is the Claude-oriented wrapper doc.
+- `.agents/skills/` and `.claude/skills/` mirror canonical skills from `.mdkg/skills/` when agent bootstrap is enabled.
+- mdkg does not execute skill scripts; runtimes decide when and whether to do that.
+- Prefer packs over ad-hoc file lists.
+- Prefer task/event commands over hand-editing routine work-state changes.
+- Use `mdkg task done <id> --checkpoint "<title>"` for milestone compression, not every routine task completion.
+- Prefer checkpoints for feat/epic closeout summaries; parent status edits remain manual in 0.0.5.
+- If events are disabled, `mdkg task start` and `mdkg task done` will remind you how to enable JSONL provenance.

package/dist/init/CLAUDE.md

@@ -1,37 +1,8 @@
-# Claude Instructions
+# CLAUDE
 
-This project uses mdkg to manage tasks and context.
+Read `AGENT_START.md` first.
 
-## Quickstart
-
-- `mdkg init --llm`
-- `mdkg index`
-- `mdkg new task "..." --status todo --priority 1`
-- `mdkg list --status todo`
-- `mdkg pack <id> --verbose`
-- `mdkg validate`
-
-## Core commands
-
-- `mdkg init` (scaffold .mdkg and optional agent docs)
-- `mdkg guide` (print the repo guide)
-- `mdkg new <type> "<title>"` (create nodes)
-- `mdkg list` / `mdkg show` / `mdkg search`
-- `mdkg pack` (context bundles)
-- `mdkg next` (priority/chain)
-- `mdkg validate` / `mdkg format`
-
-## Before making changes
-
-- Run `mdkg pack <task-id> --verbose`.
-- Follow linked rules and decisions.
-
-## After making changes
-
-- Update frontmatter fields and `updated: YYYY-MM-DD`.
-- Run `mdkg validate` and fix any errors.
-- If frontmatter is inconsistent, run `mdkg format`.
-
-## Repo-specific notes
-
-Add build, test, and release instructions here.
+Claude conventions for this repo:
+- use `AGENT_START.md` as the startup contract
+- use `.claude/skills/` for product-facing mirrored skills when present
+- use `mdkg skill ...` as the canonical skill command family

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -0,0 +1,29 @@
+# CLI Command Matrix
+
+This file is the canonical command reference for mdkg in this repository.
+
+Verify live help with:
+- `mdkg --help`
+- `mdkg help <command>`
+
+Primary commands:
+- `mdkg init`
+- `mdkg new`
+- `mdkg show`
+- `mdkg list`
+- `mdkg search`
+- `mdkg pack`
+- `mdkg skill`
+- `mdkg task`
+- `mdkg validate`
+
+Agent bootstrap:
+- `mdkg init --llm`
+- `mdkg init --agent`
+- `mdkg init --llm --agent`
+
+Skill discovery:
+- `mdkg skill list --tags stage:plan --json`
+- `mdkg skill search "<query>" --json`
+- `mdkg skill show <slug> --json`
+- `mdkg skill sync`

package/dist/init/README.md

@@ -14,13 +14,15 @@ This repository is initialized for mdkg.
 ## First Commands
 
 ```bash
-mdkg index
-mdkg new task "..." --status todo --priority 1
-mdkg list --status todo
-mdkg pack <id> --verbose
+mdkg init --llm --agent
+mdkg search "..."
+mdkg show <id>
+mdkg pack <id>
 mdkg validate
 ```
 
+Read `AGENT_START.md` first when this repo includes it.
+
 ## Pack Profiles
 
 - `--pack-profile standard`: full body (current default behavior)

package/dist/init/core/HUMAN.md

@@ -0,0 +1,36 @@
+---
+id: rule-human
+type: rule
+title: human working profile and collaboration preferences
+tags: [human, collaboration, preferences]
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: [human]
+created: 2026-03-10
+updated: 2026-03-10
+---
+
+# Purpose
+
+Capture stable collaboration preferences and boundaries so agents can work with less ambiguity.
+
+# Scope
+
+Applies to planning, implementation, and review interactions in this repository.
+
+# Requirements
+
+- Keep top goals, boundaries, and style preferences current.
+- Include ask-before-doing constraints for risky or high-impact actions.
+- Record preferred environment assumptions and validation commands.
+
+# Notes
+
+Suggested prompts:
+- What are your top 3 goals in this repo right now?
+- What should never happen without confirmation?
+- What coding/review style should the agent prefer?
+- What OS/runtime/test commands should be assumed?