Ship the scriptorium plugin for Diátaxis-grounded documentation work

[ckrough]

Add scriptorium, a fifth plugin to this marketplace, carrying one skill that fires when an agent is about to generate or move documentation. It routes the document to one of four modes using the Diátaxis compass, writes it under that mode's constraints, and validates its form against CommonMark 0.31.2.

Agents generate and relocate documentation constantly without a theory of what kind of document they are writing. The result is the failure Diátaxis names as "at the root of many difficulties that afflict documentation": mode contamination. A how-to guide swells with explanation, a tutorial offers options and alternatives, reference material carries opinion. Each document is individually plausible and collectively unusable.

Source standards

• Diátaxis governs content, architecture, and mode discipline: what kind of document is this, and where does it go.
• CommonMark 0.31.2 governs form: does this markdown parse the way the author intended.

Design constraints from the source frameworks

Three findings from the specs rule out implementations a naive reading would produce:

1. Never scaffold empty mode directories. Diátaxis is explicit: "It certainly does not mean that you should create empty structures for tutorials/howto guides/reference/explanation with nothing in them. Don't do that. It's horrible." Expressed as a precondition rather than a prohibition: create a directory only in the same action that writes a document into it.
2. Diátaxis is a guide, not a plan. It "discourages planning and top-down workflows, preferring instead small, responsive iterations." The unit of work is one document and one next action.
3. Diátaxis cannot verify accuracy. It "cannot address functional quality" and is concerned only with deep quality. The skill checks mode purity, placement, and form, never correctness.

A fourth constraint comes from CommonMark: version 0.31.2 defines no table syntax at all. Pipe tables are a GitHub Flavored Markdown extension.

Shape

scriptorium/
├── .claude-plugin/plugin.json
├── README.md
├── docs/decisions/never-scaffold-mode-trees.md
└── skills/docs/
    ├── SKILL.md
    ├── references/{tutorial,how-to,reference,explanation,commonmark}.md
    ├── scripts/check_markdown.py
    └── evals/evals.json

Tasks

• Scaffold the scriptorium plugin and register it in the marketplace #16 Scaffold the plugin and register it in the marketplace
• Verify Diátaxis and CommonMark licensing and add attribution #17 Verify Diátaxis and CommonMark licensing and add attribution
• Author the docs SKILL.md and its five mode references #18 Author the docs SKILL.md and its five mode references
• Build the CommonMark authoring linter check_markdown.py #19 Build the CommonMark authoring linter
• Write the scriptorium eval suite and fixtures #20 Write the eval suite and fixtures
• Optimize the docs skill trigger description #21 Optimize the trigger description
• Record the never-scaffold ADR and verify repo gates #22 Record the never-scaffold ADR and verify repo gates
• Specify file naming, frontmatter, and pre-emission checks #27 Specify file naming, frontmatter, and pre-emission checks

Dependency graph

#16 scaffold ──┬─> #18 skill+refs ──┬─> #20 evals ──> #21 description
#17 licensing ─┘        │           │
                        │           ├─> #22 ADR + gates
                        │           │
                        │           └─> #27 naming + frontmatter
                        │
#16 ───────────> #19 linter ────────┘

#17 is deliberately upstream of #18: its outcome decides verbatim reproduction
versus paraphrase, and discovering that constraint after the prose is drafted
means rewriting it. #18 and #19 run in parallel. #20 is the join point.
No cycles.

#27 carries the document's identity and header: file naming, the frontmatter
schema, the emission self-check, and the escalation conditions. It follows #18
because those rules attach to the write path #18 builds. Its rules come from a
pre-epic authoring contract that predates this epic and was never in version
control.

Success Criteria

• /scriptorium:docs resolves and triggers on generate-and-move phrasings without firing on ADRs, commit messages, changelogs, or READMEs
• Both repo gates stay green: bash .daedalus/gates/structure.sh and claude plugin validate .
• The linter produces zero findings on a fixture whose fenced code blocks contain #!/usr/bin/env bash, #include, and tab-indented Makefile rules
• Every file the plugin ships passes its own linter at error severity
• An eval proves the skill leaves no empty directories when asked to "set up a docs folder using Diátaxis"
• An eval proves the skill declines to reorganize an ADR into Diátaxis modes
• Third-party licensing for Diátaxis and CommonMark verified and attributed before any verbatim reproduction