Docmd dev

docmd — Agent Skill (Developer)

Use this skill when the user wants to modify the docmd framework itself, not a site that consumes it. This skill is loaded by npx docmd-skills dev <dir> and adds docmd-dev/ alongside an existing docmd-skills/ install.

When to use this skill

Use it when any one of these signals is true:

1. The user's current working directory is a clone of the docmd monorepo. The local clone directory is named just docmd/ (the GitHub path is docmd-io/docmd/). Telltale markers: pnpm-lock.yaml, packages/core/src/, packages/ui/src/, packages/api/src/, packages/plugins/<name>/, packages/engines/. To clone it: git clone https://github.com/docmd-io/docmd.git docmd && cd docmd.
2. The user explicitly says they want to "write a plugin", "write a template", "extend the engine", "modify the core", "add a hook", or similar.
3. The user is editing files inside packages/core/src/, packages/api/src/, packages/ui/src/, packages/plugins/*/src/, or packages/engines/*/ of the docmd monorepo.

If the user wants framework help but no docmd/ clone exists in the working directory, ask before doing anything: would they like you to clone the monorepo (git clone https://github.com/docmd-io/docmd.git docmd) or refresh an existing one (git -C docmd pull)? Do not start editing framework source without an up-to-date local clone.

Do not use it for: site-level configuration or operations (use docmd-skills), or for page-prose quality (use docmd-writer).

Loading rules

• Only load this skill when the user is actively working inside the docmd monorepo or asks explicitly about framework internals.
• When in doubt, default to docmd-skills (user). Switching to this skill implies the user is comfortable running pnpm commands against the monorepo.

Reference index

Each row is a reference file. The CLI column shows which install subcommand adds this file.

Reference	CLI install subcommand	Use it for
references/api-dev.md	docmd-skills dev	Public Node API for framework authors: EngineLoader, URL utilities, createActionDispatcher, TemplateSlot, hook/action contracts
references/plugin-development.md	docmd-skills dev	Authoring a docmd plugin: package shape, manifest, apply() lifecycle, template capability, hooks, testing
references/template-development.md	docmd-skills dev	Authoring a docmd theme/template: 12 template slots, asset pipeline, manifest.json, template plugins
references/engines.md	docmd-skills dev	JS vs Rust build engines, swapping engines, engine-specific config, performance trade-offs
references/security-and-regression-checklist.md	docmd-skills dev	docmd-specific security and quality gate: container parser invariants, plugin HTML-injection contract, public API honesty, i18n/versioning silent-failure rules, deploy/Docker hardening, migration correctness, CLI honesty, loud fallbacks. Load before any framework change ships. Builds on ai-dev's nodejs-cautions.md and security-must-checks.md.

Workflows

1. Cloning or refreshing the monorepo

No clone yet — clone and install:

git clone https://github.com/docmd-io/docmd.git docmd
cd docmd
pnpm install

Existing clone — refresh and re-install dependencies if needed:

git -C docmd pull
pnpm install

To check whether a clone is behind before deciding, run git -C docmd status (look for "Your branch is behind") or git -C docmd log -1 --oneline and compare to https://github.com/docmd-io/docmd/commits/main.

The local clone directory is docmd/ (not docmd-io/docmd/). Inside it you will find the canonical package layout referenced throughout this skill.

2. Writing a plugin

1. Read references/plugin-development.md end-to-end before scaffolding.
2. Pick the closest existing plugin under packages/plugins/<name>/ and copy its shape.
3. Cross-check references/api-dev.md for the Plugin type, hook names, and the template capability introduced in 0.8.7.
4. Add tests under the plugin's own tests/; the monorepo's pnpm prep runs the universal failsafe.

3. Writing a template

1. Read references/template-development.md for the 12 template slots and the asset pipeline.
2. Match the manifest shape used by an existing template (packages/templates/summer/ is the reference).
3. Validate against references/api-dev.md for the TemplateSlot union (no header slot — there are 12).

4. Engine work

1. references/engines.md first — confirms which engine you're targeting and its config keys.
2. For Node-level changes to the engine loader, references/api-dev.md § "Engine Loader API".

5. Hard checks before any framework change ships

docmd is Node.js and TypeScript only, so the generic Node rules always apply. Run this gate before declaring a framework change done:

1. Generic Node triage from ai-dev: references/nodejs-cautions.md §1.1 grep checklist, the Appendix 5-minute review, and Part 12 (contract honesty and silent failures).
2. ai-dev references/security-must-checks.md Rules 1 to 7, with docmd's common-miss spots in mind (plugins, MCP tools, container blocks, deploy templates).
3. references/security-and-regression-checklist.md — run every section that touches the area you changed. This is the docmd-only layer and the direct output of the v0.8.x battle test (battle-test-reports/unified-issues.md).
4. pnpm prep for anything non-trivial.
5. One regression test per bug class fixed, named after the report ID where possible.

If any MUST in those references is unresolved, the change is not done.

Cross-skill navigation

• docmd-skills — for site-level work; load it as the default first.
• docmd-writer — load it when the task drifts into prose quality inside template demos or example docs.