derive-md

name	derive-md
description	Use when creating, regenerating, linting, or managing machine-maintainable Markdown artifacts with derive-md. Triggers include derive-md, agents-md profile, AGENTS.md regeneration, SKILL.md regeneration, raw source to Markdown derivation, Markdown artifact profiles, or agentic Markdown rewrite launchers.

derive-md

derive-md is a standalone agentic Markdown artifact manager.

It makes each Markdown workflow a profile instead of hardcoding one-off document generators.

Core model

derive-md = profile manager + prompt/context builder + artifact index/sync bridge
agent     = repo-specific reasoning, user confirmation, editing, validation
sync      = optional profile registry/blob layer

Do not treat derive-md as a blind generator. It should prepare context and launch focused agent sessions.

Current CLI

derive-md profiles
derive-md agents --censor
derive-md agents --censor --dry-run
derive-md regen --profile agents-md
derive-md regen --profile agents-md --existing-target ignore|summary|full
derive-md regen --profile agents-md --no-markdown-docs
derive-md lint --profile agents-md AGENTS.md

derive-md agents --censor should be run from the target repo. It snapshots profile-protected files under ~/.derive-md/projects/.../snapshots/, launches the interactive agent workflow with the agents-md prompt, disables context-file autoloading where supported, and uses prompt-only bias control; read/edit/write tools remain available.

Default agents-md regeneration uses --existing-target ignore: the current target may be used for before/after comparison, but not as policy evidence. Use summary for a weak prior, full for conservative rewrites, and --no-markdown-docs when non-target Markdown docs should not influence the result.

Use --dry-run when testing from an agent session to avoid launching an interactive agent:

derive-md agents --censor --dry-run

Profiles

A profile defines a managed Markdown workflow: target files, prompt contract, validation, and safety rules.

Existing profile:

• agents-md — compact prioritized AGENTS.md policy files for coding agents.
• readme-md — public-facing repository README.md files.
• skill-md — focused Codex SKILL.md workflow files.

Planned profiles:

• source-derived-md — raw source data to semantic Markdown derivatives.

agents-md workflow

When asked to update AGENTS.md with derive-md:

1. Run from the target repo.
2. Prefer derive-md agents --censor for interactive user-driven updates.
3. Use derive-md agents --censor --dry-run to inspect the launch prompt and snapshot config without opening an interactive agent.
4. The launched agent must infer policy from repo evidence without reading existing AGENTS.md, CLAUDE.md, SKILL.md, or README.md content, then present a blind inferred policy target before editing.
5. The launched agent must not claim an exact before/after comparison or ask the user to paste protected files while censored.
6. The launched agent must not copy the bias-control instruction into the target policy; if future regeneration is relevant, tell agents to use derive-md agents --censor.
7. After editing, run derive-md lint --profile agents-md AGENTS.md.

skill-md workflow

When asked to update SKILL.md with derive-md:

1. Run from the target repo.
2. Use derive-md skill --censor path/to/skill-dir for interactive user-driven updates.
3. Use derive-md lint --profile skill-md path/to/skill-dir to check required frontmatter, trigger clarity, body size, and portability.
4. Keep the skill focused on one reusable workflow; prefer concise instructions over command catalogs or documentation prose.

Canonical AGENTS.md format

Target 5 rules by default and 5-7 as the ideal range. Warn at 8-9 rules, strongly warn at 10-12, and treat 13+ as invalid without an explicit future override.

Follow these repo rules in order. If rules conflict, the earlier rule wins.

1. Use Bun for all package, script, and workspace operations.
2. Do not create a root `.env`.
3. Never add env fallbacks, defaults, or `.optional()` to bypass missing config.

Rules:

• No headings.
• Exactly one short preamble.
• Exactly one ordered numbered list; target 5 rules by default and 5-7 as the ideal range.
• No sections, unordered lists, command catalogs, tables, or prose docs.
• Earlier rules are higher priority.
• Keep commands only when repo-specific, non-obvious, safety-relevant, or exceptions.
• Delete rule B if an agent that already read rule A would follow B without being told.

Development

Work in:

cd derive-md

Validate changes:

npm run check

Global CLI is linked with:

npm link