mdkg 0.0.3 → 0.0.4

package/README.md

@@ -1,242 +1,244 @@
-# mdkg — Markdown Knowledge Graph
+# mdkg
 
-mdkg is a **local-first CLI** that turns structured Markdown into a **searchable, linkable knowledge graph** for engineering work.
+mdkg is a local-first CLI for turning structured Markdown into deterministic project memory.
 
-It’s designed for:
-- humans who want lightweight project documentation + task tracking **in git**
-- AI coding agents/LLMs that need **deterministic context bundles** for code generation
+It is built for:
+- human builders who want project truth and task state in git
+- AI agents that need deterministic context instead of ad-hoc file reading
+- human + agent pairs who want one shared source of truth
 
-mdkg is intentionally boring and portable:
-- **Node.js 18+**
-- written in **TypeScript**
-- **zero runtime dependencies** (no sqlite, no external indexers)
-- **dev dependencies only**: TypeScript (build-time) and Node 18+ (runtime)
-- works with npm / pnpm / bun
+mdkg stays deliberately boring:
+- repo-native under `.mdkg/`
+- TypeScript + Node.js 18+
+- zero runtime dependencies
+- no sqlite, daemon, hosted index, or vector DB
 
----
+Current package version in this repo: `0.0.4`
+Publish status: cut prepared, not yet published
 
-## Core idea
+## The product shape
 
-You store project knowledge as Markdown nodes with strict frontmatter (a small, stable schema). mdkg:
+mdkg has one core job: make repo knowledge cheap to retrieve and safe to reuse.
 
-1) indexes those nodes into a local JSON cache (`.mdkg/index/global.json`)
-2) provides fast search/list/show tools
-3) generates deterministic **context packs** for agents (Markdown/JSON/TOON/XML exports)
+The primary loop is:
+1. initialize the repo
+2. create or select work
+3. inspect the current truth
+4. build a deterministic pack
+5. validate before closing the loop
 
-Everything stays in your repo. No servers. No surprises.
-
----
-
-## Repository structure
-
-mdkg lives in a hidden directory at the repo root:
-
-- `.mdkg/core/` — rules + “pinned” docs
-- `.mdkg/design/` — decisions + architecture
-- `.mdkg/work/` — epics/tasks/bugs/tests/checkpoints
-- `.mdkg/templates/` — document templates used by `mdkg new`
-- `.mdkg/index/` — generated cache (gitignored)
-
-mdkg is root-only: you run commands from the repository root and mdkg indexes all registered workspaces without “discovering” nested repos.
-
----
+If an agent is involved, the default handoff primitive is `mdkg pack <id>`.
+If a repo needs repeatable procedures, author them as first-class skills under `.mdkg/skills/`.
 
 ## Install
 
-Pre-release note: this project is being actively developed and dogfooded.
-
 Once published:
-- `npm i -g mdkg`
-- `pnpm add -g mdkg`
-- `bun add -g mdkg`
 
----
+```bash
+npm i -g mdkg
+# or
+pnpm add -g mdkg
+# or
+bun add -g mdkg
+```
 
 ## Quickstart
 
-1) Initialize mdkg in your repo:
+Initialize mdkg in a repo:
 
 ```bash
-mdkg init --llm --update-gitignore --update-npmignore
+mdkg init --llm
 ```
 
-This creates `.mdkg/` (rules, templates, work folders). Use the ignore-update flags to append recommended mdkg ignore entries.
+This is the generic OSS bootstrap path. It creates `.mdkg/` and updates `.gitignore` / `.npmignore` by default. Use `--no-update-ignores` to opt out.
 
-2) Index your repo (cache is default behavior):
+Optional agent-ready scaffold:
 
 ```bash
-mdkg index
+mdkg init --omni
 ```
 
-3) Create a task from a template:
+This adds strict-node `SOUL.md` / `HUMAN.md`, a skills scaffold, seeded events JSONL, and core pin updates.
+
+Create a task:
 
 ```bash
 mdkg new task "bootstrap cli" --status todo --priority 1 --tags cli,build
 ```
 
-4) Search and list:
+Inspect the current truth:
 
 ```bash
 mdkg search "pack"
-mdkg list --type task --status todo
 mdkg show task-1
+mdkg next
 ```
 
-5) Generate a deterministic context bundle for an agent:
+Build deterministic context:
 
 ```bash
-mdkg pack task-1 --format md --verbose
-mdkg pack task-1 --pack-profile concise --dry-run --stats
+mdkg pack task-1
+mdkg pack task-1 --profile concise --dry-run --stats
 ```
 
----
-
-## Why this exists
+Validate before handoff or commit:
 
-LLMs are great at writing code, but they need **high-quality, structured context**.
-
-mdkg makes that context:
-- easy to author
-- easy to query
-- easy to hand to an agent
-- reproducible across runs and contributors
-
-This is also intended to be a compatible building block for “life git”-style productivity systems (which may later add richer databases like SQLite/Postgres). mdkg stays minimal and local.
-
----
-
-## Concepts
+```bash
+mdkg validate
+```
 
-### Nodes
+Mutate a task-like node without manual markdown editing:
 
-A node is a Markdown file with strict YAML-like frontmatter fenced by `---`.
+```bash
+mdkg task start task-1 --run-id run_local_1
+mdkg task update task-1 --add-artifacts tests://unit.txt --add-tags release
+mdkg task done task-1 --checkpoint "release readiness milestone"
+```
 
-Each node must include:
-- `id` (unique per workspace; global uniqueness via qualified IDs)
-- `type` (rule, prd, edd, dec, prop, epic, feat, task, bug, checkpoint, test)
-- `title`
-- `created` / `updated` (`YYYY-MM-DD`)
+Enable and append baseline event memory:
 
-Work items also typically include:
-- `status` (backlog, blocked, todo, progress, review, done)
-- `priority` (0..9, where 0 is most urgent)
+```bash
+mdkg event enable
+mdkg event append --kind RUN_COMPLETED --status ok --refs task-1 --notes "manual closeout"
+```
 
-### Graph links
+Create a first-class skill:
 
-mdkg treats these frontmatter fields as explicit graph structure:
-- `epic`, `parent`
-- `relates: [...]`
-- `blocked_by: [...]`, `blocks: [...]`
-- `prev`, `next` (chain navigation)
+```bash
+mdkg skill new release-readiness "release readiness audit" --description "use when preparing a release"
+mdkg skill list
+mdkg skill show release-readiness
+mdkg skill validate release-readiness
+```
 
-### Searchable metadata
+## LLM-readable onboarding artifacts
 
-If you want something searchable, put it in frontmatter:
-- `links: [ref, ref]` (URLs or any searchable reference string)
-- `artifacts: [ref, ref]` (build outputs, PRs, commits, releases, tarballs, etc.)
-- `refs: [id, id]` (non-edge references)
-- `aliases: [text, text]`
+The root docs below are the canonical fast-start set for humans and agents:
+- [`llms.txt`](/Users/nicholasreames/Git/mdkg/llms.txt)
+- [`AGENT_PROMPT_SNIPPET.md`](/Users/nicholasreames/Git/mdkg/AGENT_PROMPT_SNIPPET.md)
+- [`PACK_EXAMPLES.md`](/Users/nicholasreames/Git/mdkg/PACK_EXAMPLES.md)
+- [`MANUAL_BEHAVIOR_AUDIT.md`](/Users/nicholasreames/Git/mdkg/MANUAL_BEHAVIOR_AUDIT.md)
+- [`CLI_COMMAND_MATRIX.md`](/Users/nicholasreames/Git/mdkg/CLI_COMMAND_MATRIX.md)
+- [`COVERAGE_HARDENING_MATRIX.md`](/Users/nicholasreames/Git/mdkg/COVERAGE_HARDENING_MATRIX.md)
 
----
+## Repository shape
 
-## CLI commands (v1)
+mdkg lives under a hidden root directory:
+- `.mdkg/core/` rules and pinned docs
+- `.mdkg/design/` product, design, and decision docs
+- `.mdkg/work/` tasks, bugs, tests, epics, checkpoints
+- `.mdkg/templates/` templates used by `mdkg new`
+- `.mdkg/skills/` Agent Skills packages
+- `.mdkg/index/` generated cache files
 
-### Project setup
+## Primary commands
 
+These are the commands new users and agents should learn first:
 - `mdkg init`
-  - create `.mdkg/` structure
-  - add ignore rules for caches
-
-### Indexing
+- `mdkg new`
+- `mdkg search`
+- `mdkg show`
+- `mdkg next`
+- `mdkg pack`
+- `mdkg skill`
+- `mdkg task`
+- `mdkg validate`
 
+Advanced / maintenance commands still exist, but they are not the first-run story:
+- `mdkg event`
+- `mdkg checkpoint`
 - `mdkg index`
-  - builds `.mdkg/index/global.json`
-  - cache is the default; mdkg will reindex automatically if stale
-
-### Query
-
-- `mdkg show <id-or-qid>`
-- `mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>] [--priority <n>]`
-- `mdkg search "<query>"`
-
-### Packs (agent context)
-
-- `mdkg pack <id> [--format md|json|toon|xml] [--verbose] [--depth <n>] [--edges <keys>]`
-- `mdkg pack <id> [--pack-profile standard|concise|headers] [--max-chars <n>] [--max-lines <n>] [--max-tokens <n>]`
-- `mdkg pack <id> [--stats] [--stats-out <path>] [--truncation-report <path>]`
-- `mdkg pack <id> [--dry-run]`
-- `mdkg pack --list-profiles`
-
-`--verbose` includes pinned core docs listed in `.mdkg/core/core.md`.
-`--pack-profile concise` uses summary-oriented body shaping and strips code blocks by default.
-If `--out` is omitted, packs are written to `.mdkg/pack/pack_<kind>_<id>_<timestamp>.<ext>`.
-
-`--max-tokens` uses a heuristic estimate: `~tokens = chars / 4`.
-
-### Quickstart (CLI only)
-
-```bash
-mdkg init --llm
-mdkg index
-mdkg new task "..." --status todo --priority 1
-mdkg list --status todo
-mdkg pack <id> --verbose
-mdkg pack <id> --pack-profile concise --dry-run --stats
-mdkg validate
-```
-
-### Workflow helpers
-
-- `mdkg next [<id>] [--ws <alias>]`
-  - follows `next` chain if present; otherwise picks highest priority work item
-
-- `mdkg checkpoint new "<title>"`
-  - creates a checkpoint node (a compression summary)
-
+- `mdkg guide`
+- `mdkg format`
 - `mdkg doctor`
-  - runs consumer diagnostics (node version, config, templates, index)
-- `mdkg doctor --json`
-  - emits machine-readable diagnostics for scripts/CI
+- `mdkg workspace`
 
-- `mdkg --version`
-  - prints installed CLI version
+## Skills
 
-### Quality gates
+mdkg supports Agent Skills as procedural memory.
 
-- `mdkg validate`
-  - strict frontmatter validation
-  - missing required fields, invalid enums, dangling edges, cycles, duplicates
-  - supports `--out <path>` and `--quiet` for CI workflows
+Canonical layout:
 
-- `mdkg format`
-  - conservative frontmatter normalizer (idempotent)
+```text
+.mdkg/skills/<slug>/SKILL.md
+```
 
----
+Current source behavior:
+- skills are indexed into `.mdkg/index/skills.json`
+- skills have a focused command family:
+  - `mdkg skill new <slug> "<name>" --description "..."`
+  - `mdkg skill list`
+  - `mdkg skill search "<query>"`
+  - `mdkg skill show <slug>`
+  - `mdkg skill validate [<slug>]`
+- machine-readable skill discovery is available through:
+  - `mdkg skill list --json`
+  - `mdkg skill search "<query>" --json`
+  - `mdkg skill show <slug> --json`
+- work items may reference `skills: [slug,...]`
+- packs may include skills with `--skills` and `--skills-depth`
+- mdkg indexes and discovers skills but does not execute skill scripts
+- `SKILL.md` is canonical
+- `SKILLS.md` is tolerated on read for compatibility, but validation warns and canonical docs still use `SKILL.md`
+- if both `SKILL.md` and `SKILLS.md` exist in one skill folder, validation fails
+- `mdkg skill new` scaffolds `SKILL.md`, `references/`, `assets/`, and `scripts/` only when requested with `--with-scripts`
+
+This repo now dogfoods three internal skills:
+- `author-mdkg-skill`
+- `select-work-and-ground-context`
+- `build-pack-and-execute-task`
+- `verify-close-and-checkpoint`
+
+## Current direction
+
+Current `0.0.4` release polish already includes:
+- `init --omni`
+- default ignore updates with `--no-update-ignores`
+- skills indexing and search/show/list support
+- optional `skills: [...]` on work items
+- pack-time skill inclusion
+- latest-checkpoint resolver + index hint
+- events JSONL validation
+
+Current `0.0.4` polish direction is:
+- keep the OSS story generic around `init --llm`
+- keep `pack <id>` at the center of the human/agent loop
+- make task mutation and event logging guided instead of purely manual
+- dogfood real skills inside the repo
+- make skill authoring first-class through `mdkg skill`
+- make `CLI_COMMAND_MATRIX.md` the single source of truth for the live CLI surface
+- run manual behavior audits before enforcing stronger coverage thresholds
+
+Design and decision records live in the internal graph under `.mdkg/design/`.
 
 ## Safety
 
-mdkg is designed to avoid accidental leaks:
-- cache files live under `.mdkg/index/` and must be gitignored
-- publishing should use a strict `package.json.files` whitelist
-- `.mdkg/` content should never ship to production builds
+mdkg is not a secret store.
 
----
+Use these defaults:
+- keep `.mdkg/index/` gitignored
+- keep `.mdkg/pack/` gitignored
+- keep `.mdkg/work/events/*.jsonl` gitignored unless you deliberately opt in
+- do not ship `.mdkg/` into production builds or published packages
+- if an external orchestrator is writing mdkg state, keep one durable writer per run and batch commits at end-of-run or checkpoint boundaries
+- do not commit on every tool call
 
 ## Contributing
 
-This repo dogfoods mdkg. The source of truth for behavior is:
-- `.mdkg/core/rule-*.md`
-- `.mdkg/core/guide.md`
-- `.mdkg/core/rule-2-context-pack-rules.md`
-
-Suggested workflow:
-1) create or update a task in `.mdkg/work/`
-2) run `mdkg validate`
-3) generate a pack for the task and use it as agent context
-4) run `npm run smoke:consumer` before publishing to verify tarball install + onboarding flow
+This repo dogfoods mdkg itself. The behavior source of truth is the combination of:
+- source under `src/`
+- tests under `tests/`
+- internal rules and design docs under `.mdkg/`
 
----
+Suggested local loop:
+1. create or select a work item
+2. inspect truth with `search`, `show`, or `next`
+3. build context with `pack <id>`
+4. mutate task state with `mdkg task ...` when durable state changes
+5. enable event logging if provenance should be captured in JSONL
+6. implement and test
+7. run `mdkg validate`
 
 ## License
 
-MIT (recommended). Add a `LICENSE` file to confirm.
+MIT