--- name: agentic-dev-docs description: "Turns a rough engineering input (PR description, feature note, config snippet, changelog, or Slack dump) into a publication-ready Mintlify MDX developer doc that is correct for BOTH human readers and coding agents. Emits the MDX page, its llms.txt index entry, and a Verification-Gate QA report. Calibrated to Upsun / Platform.sh developer docs conventions; generalizes to any Mintlify-based docs set. Apply whenever the task is 'document this feature/behavior/API as a real dev-docs page.'" version: "0.1.0" license: "Apache-2.0" author: "Bret Kerr / ACRA Insight LLC — contextjamming.com" --- # agentic-dev-docs Stage-3 of the MoEA arsenal: where Stage 1–2 turn research into prose, this turns engineering reality into **executable documentation** — docs that are simultaneously a guide for humans and a constrained, machine-parseable specification for agents. The operating thesis (see contextjamming.com/RobotAudience): in an agentic development lifecycle, a doc is not a tutorial. It is the *executable spec* the verifier checks the generator against. This skill writes docs to that standard. --- ## When to apply - "Document this feature / endpoint / config behavior as a docs page." - "Write the Upsun-style page for X." - "Turn this PR / changelog / engineer's notes into a published doc." - Any time the deliverable is a developer documentation page in a Mintlify docs set. Do **not** use for marketing copy, blog dispatches (use `semantic-triple-transformation`), or HTML artifacts (use `responsive-html` / `cj-artifact-dashboard`). --- ## Inputs accepted Any one or more of: a rough draft, a PR description, an engineer's bullet notes, a config/YAML snippet, a CLI transcript, an API schema, a changelog entry, a support-ticket resolution. Low-fidelity is fine — the skill's job is to raise it to publication grade without inventing facts. ## Output contract Always emit, in this order: 1. **The MDX page** — a complete Mintlify `.mdx` file with frontmatter, ready to drop into the docs repo. 2. **The `llms.txt` entry** — the single index line (path + one-sentence summary) to register the page in the machine-readable manifest. 3. **The Verification-Gate report** — the QA checklist below, run and answered, with any unverifiable claims flagged for the human gate. Never emit the page without the QA report. The report is the point. --- ## Output format: Mintlify MDX ### Frontmatter (required) ```mdx --- title: "" description: "" --- ``` ### Page skeleton (immediately under frontmatter) ```mdx > ## Documentation Index > Fetch the complete documentation index at: https://developer.upsun.com/llms.txt > Use this file to discover all available pages before exploring further. ``` > Reproduce the `llms.txt` callout block verbatim — it is the Upsun convention that tells an ingesting agent where the manifest is. Do not paraphrase or omit it. ### Mintlify components — use, don't reinvent | Component | Use for | | :--- | :--- | | `…` | A pointer to a prerequisite or sibling guide | | `…` | A non-obvious shortcut or best practice | | `…` | A destructive / irreversible / silent-failure behavior. **Mandatory** wherever an agent could confidently produce valid-but-wrong output | | `…` | Any procedure with ordered actions | | `…` | Per-client / per-language variants (e.g. Cursor vs Claude Code vs JetBrains) | | `…` | The same operation in multiple languages/shells | | `` / `` | "Related content" navigation at the foot of the page | | `` | Wrap screenshots/diagrams with a caption | ### Page archetypes — pick one, follow its shape **A. Concept** ("What is X?") — problem → plain-language definition → an analogy (Upsun house move: e.g. "MCP is the USB-C of LLM integration") → a roles/parts breakdown → "Additional resources." **B. Procedure / Tutorial** — one-line goal → `` with numbered `### 1. / 2. / 3.` → a `` client/stack selector if relevant → a "you should now see…" success check → "Related content." **C. Reference** — terse intro → a capability matrix table (`Capability | Description | Use case`) → exact config/headers in fenced blocks → invariants as `` blocks → "Summary table" of links. Every page ends with a `## Related content` `` and renders a "Was this page helpful?" affordance (Mintlify provides it; just don't fight it). --- ## Voice & style (Upsun-calibrated) - Second person, present tense, active voice. "You configure the client," not "the client is configured." - Precise over breezy, but not stiff. One analogy per concept page is welcome; two is noise. - Bold lead-ins on list items that carry a definition: `**MCP Server**: the external service that exposes an MCP interface.` - Name the real thing. `mcp.upsun.com/mcp`, `.upsun/config.yaml`, `enable-write` — never a vague placeholder where the real token exists. - Link generously and with relative paths for internal docs (`/docs/get-started/ai/using-the-mcp`), absolute for external. - Short paragraphs. An agent chunks on headings and sentences; long prose blocks lower retrieval precision. --- ## Agent-consumability requirements (the dual-audience rule) A page passes only if an agent ingesting it via `llms.txt` could act correctly without the surrounding site. That means: 1. **Canonical headings.** Descriptive, stable, task-oriented (`## Enable write operations`, not `## More`). Headings are the agent's index. 2. **Self-contained sections.** Each `##` section should make sense pulled out of context. Restate the object ("the MCP server") rather than relying on "it" across sections. 3. **Invariants are explicit, not implied.** If an agent could generate syntactically valid output that silently breaks state, say so in a `` with the exact failure. This is the single highest-value thing the skill produces. 4. **No undocumented config keys.** Every key/header/flag shown must be a real, current one (see invariant library + verification). 5. **One canonical source per fact.** Link the authoritative page; don't restate volatile details (pricing, limits) inline where a link will stay current. --- ## Upsun invariant library (verify before relying) These are real, load-bearing Upsun behaviors an agent will get wrong by default. Document them with ``. **Each must be re-checked against the live docs / `llms.txt` at author time — never assume my snapshot is current.** - **`.upsun/config.yaml` has exactly three top-level keys:** `applications`, `services`, `routes`. - **Config patching is top-level *replace*, not deep merge.** A patch that declares `applications.web-app.hooks` will wipe `source`, `type`, and `relationships` on that app — with no CLI warning. (This is the canonical agent footgun.) - **The MCP server defaults to read-only.** Write operations require the header `{"enable-write": "true"}` in the client config; endpoint is `mcp.upsun.com/mcp`; transport is Streamable HTTP. - **Every pushed branch becomes a byte-level ephemeral environment.** Cheap to spin up; ideal as an agent's verification sandbox (Flex pricing bills per compute-second). If the input asks you to document a behavior not in this library and not confirmable in the live docs, **do not invent it** — flag it in the QA report as "unverified; needs SME confirmation." --- ## The Verification Gate (run before emitting — this is the deliverable's spine) Answer each explicitly in the QA report. Any ✗ blocks publication. - [ ] **Frontmatter complete** — title + description present; description ≤160 chars and problem-led. - [ ] **llms.txt callout present** — verbatim, with correct manifest URL. - [ ] **Archetype consistent** — page follows exactly one of Concept / Procedure / Reference shapes. - [ ] **No invented config** — every key, header, flag, endpoint, and path is real and current (cite the source doc for each non-trivial one). - [ ] **Invariants warned** — every place an agent could emit valid-but-wrong output carries a ``. - [ ] **Agent-extractable** — each `##` section is self-contained; headings are canonical and task-oriented. - [ ] **Links resolve** — internal relative paths valid against the docs tree; external links present and not obviously dead. - [ ] **Destructive ops gated** — any irreversible action (delete, overwrite, write-enable) is explicitly called out, never buried. - [ ] **Human gate noted** — anything unverifiable is surfaced for the human reviewer, not silently smoothed over. The skill is the *generator*. The gate is the *verifier*. The human signing off is the *editorial membrane*. No section ships on the generator's confidence alone. --- ## Worked micro-example **Input (rough engineer note):** > "ppl keep nuking their config when they add a build hook in a patch file — yaml merge isn't a merge, it replaces the whole top-level key. document this" **Output (excerpt):** ```mdx --- title: "How config patching merges (and what it overwrites)" description: "Upsun config patches replace top-level keys instead of deep-merging — learn what that overwrites before you split your config." --- Understand exactly what a patch file replaces in `.upsun/config.yaml` so a partial change doesn't silently wipe your runtime. > ## Documentation Index > Fetch the complete documentation index at: https://developer.upsun.com/llms.txt > Use this file to discover all available pages before exploring further. Upsun parses three top-level keys in `.upsun/config.yaml`: `applications`, `services`, and `routes`. When you apply a patch, Upsun performs a **top-level replace on these keys — not a deep merge.** If a patch declares `applications.web-app.hooks`, it replaces the entire `web-app` block. Any `source`, `type`, or `relationships` you set in the base file are deleted — with no CLI warning. Agents that assume JSON/YAML deep-merge will silently strip your runtime. To add a build hook safely, edit the existing `web-app` block in place rather than patching a partial copy: ```yaml applications: web-app: source: { root: "public" } type: "nodejs:18" relationships: { database: "postgres:db" } hooks: { build: "npm run build" } ``` ``` QA report for this page would confirm: invariant warned ✓, no invented keys ✓ (three top-level keys + the named app keys are real), archetype = Reference ✓, destructive behavior gated ✓. --- ## Notes for the orchestrator - Pairs with `responsive-html` only if a standalone HTML preview is requested; the native output is MDX for the docs repo. - Pairs with `deploy-and-purge` as the final step *after* the human gate passes. - In an autonomous run, the Verification Gate is what makes "out of the loop" safe: a failed gate routes back to generation with the specific ✗ as the corrective signal (Critic-Reflexion), and only a clean gate proceeds to deploy.