# Author > Write a new doc in the right place with the right name. Use when asked to "write a doc", "where should this doc go", "add an ADR", "document this decision", "new spec", or "new feature plan". - Skill: `thedixitjain/author` (Agent Skill) - Install (CLI): `npx skillmds add thedixitjain/author` - Raw SKILL.md: https://api.skillmd.com/api/skills/thedixitjain/author/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: thedixitjain (https://skillmd.com/u/thedixitjain) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/thedixitjain/author --- # author Author docs the docflow way: **choose category → apply naming → fill template → cross-link.** Companion of [`router`](../router/SKILL.md) (read side) and [`changelog`](../changelog/SKILL.md) (history). Templates live in the plugin's `templates/` dir; `/docflow:init` drops them into a repo. > A doc's filename should tell a teammate **what** + **when** without opening it. If it can't, rename. ## Writing style (enforce on every doc) Direct, tech + business. No filler. - Tables and bullets over paragraphs. One claim per line. - Lead with the outcome/decision; cut "this document describes…", "in order to", "it is important to note". - Concrete: names, paths, numbers, commit hashes. No adjectives that carry no info. - Each section earns its place — if a placeholder stays empty, delete the section. - Max one short intro line per doc; the structure does the rest. --- ## 1 — Pick the category (what is this doc?) | The doc answers… | Category | Folder | |------------------|----------|--------| | WHAT a feature does (user-facing) | product spec | `product-spec/` | | HOW it's built (data flow, API contract, lifecycle) | technical spec | `specs/` | | WHY we chose an approach | decision (ADR) | `decisions/` | | HOW to do X / a convention / cheat sheet | reference | `references/` | | WHAT's planned / status / roadmap | plan | `plans/` (`features/`, `hygiene/`, `upcoming/`) | | Current quality / known bugs / audit | review | `reviews/` (`active/`, `archive/`, `bugs/`) | | WHAT shipped, by month | changelog | `changelog/` — see [`changelog`](../changelog/SKILL.md) | One doc, one category. If it spans two, it's two docs that **cross-link**. --- ## 2 — Apply the naming pattern | Folder | Pattern | Example | |--------|---------|---------| | `product-spec/` | `NN-topic.md` (stable, reading order) | `04-jobs.md` | | `specs/` | `(mmm-yy)-topic.md` (dated snapshot) | `(apr-26)-tab-system-workflow.md` | | `references/` | `topic.md` (stable) | `newtable-component.md` | | `decisions/` | `NNNN-title.md` (monotonic, never reused) | `0001-url-as-state.md` | | `plans/features/` | `(mmm-yy)-feature-name.md` | `(apr-26)-create-job-stepper.md` | | `plans/hygiene/` | `(mmm-yy)-topic.md` | `(apr-26)-codebase-cleanup.md` | | `plans/upcoming/` | rolling roadmap, no dates | `critical.md`, `now.md`, `next.md`, `later.md` | | `reviews/active/`,`archive/` | `(mmm-yy)-topic.md` | `(may-26)-tab-system.md` | | `changelog/` | `(mmm-yy).md` | `(may-26).md` | Rules: - **kebab-case** always — never `camelCase` or `snake_case`. - **`(mmm-yy)-` prefix** on dated docs: lowercase 3-letter month + 2-digit year — `jan feb mar apr may jun jul aug sep oct nov dec`. - **Stable numbers** (`NN-`, `NNNN-`) for ordered series that are *not* snapshots — product-spec reading order, ADRs. - **No redundant suffixes** — never `-feature.md`, `-spec.md`, `-doc.md`. Add a qualifier only when a sibling would otherwise collide (`tab-system-overview` + `tab-system-qa-guide`). - **Topic prefix groups siblings** so they sort together (`(apr-26)-tab-system-*`). --- ## 3 — Fill the template (or generate a draft from code) **Don't start specs/plans from blank** — generate a draft from the real repo, then verify: - Spec: `bash scripts/docflow-spec.sh ` → pre-fills files, exports (Architecture), types (Data), paths+verbs (API), hooks (Flow). You group + confirm + write Risks. - Plan: `bash scripts/docflow-plan.sh --days 30` → backlog candidates from TODO/FIXME + git churn. You triage into horizons. Both write drafts marked ``; curate before shipping. Then fill manually where heuristics can't reach: Each category has a skeleton in the plugin's `templates/`. Key shapes: **ADR** (`decisions/NNNN-title.md`): ```markdown # NNNN — Title > **Status:** proposed | accepted | superseded by [NNNN](...) | deprecated > **Date:** YYYY-MM-DD > **Deciders:** names/handles ## Context — what forced the decision? constraints, prior pain ## Decision — what we chose (one sentence, then detail) ## Consequences — good / bad / what gets harder ## Alternatives considered — each + why rejected ``` Write an ADR for: cross-cutting choices, non-obvious trade-offs, reversals (supersede the old one — never edit it). NOT for: version bumps, one-file refactors, taste. **Spec** (`specs/(mmm-yy)-topic.md`): header block (`Module:` / `Route:` / `Branch:`), then numbered sections — architecture, data model, API surface, state, edge cases. Plus a `Related:` block linking plan + review + ADRs. **Feature plan** (`plans/features/(mmm-yy)-name.md`): `Status` / `Owner` / `Surface` header, then `## What shipped` (table w/ commit refs) · `## In flight` · `## Queued`. **Review** (`reviews/...`): `Last updated` / `Scope` header, scorecard table, P0/P1/P2 findings. --- ## 4 — Cross-link (no orphan docs) Bidirectional. The chain that ties a feature together: ``` product-spec/NN-feature.md (WHAT) ↕ specs/(mmm-yy)-feature.md (HOW) ──► decisions/NNNN-*.md (WHY) ↕ plans/features/(mmm-yy)-feature.md (STATUS) ↕ reviews/active/(mmm-yy)-feature.md (QUALITY) ``` - Every spec ends with a `Related:` list (plan, review, ADRs). - Every ADR links the specs/product-specs it affects. - The docs-root `README.md` indexes everything — **add your new doc to it.** - **Filenames with parentheses must be wrapped in angle brackets in links**, or the renderer breaks: `[text]()` — not `[text](specs/(may-26)-file.md)`. --- ## 5 — After writing 1. **Regenerate the map**: `bash scripts/docflow-map.sh ` → updates `/INDEX.md` (the compact `path — purpose` tree every agent reads first). New doc needs a clear H1 — that becomes its one-liner. 2. Add the doc to the docs-root `README.md` index + the folder's own README if it has one. 3. Record the document change in `## Update Log` or the feature/changelog table. 4. Run `bash scripts/docflow-validate.sh --target ` and fix validation errors before reporting completion. 5. If a decision shipped or a plan item completed, reflect it in `changelog/` (see [`changelog`](../changelog/SKILL.md)). 6. On rename: update the file, `grep -rn "old-name\.md"` every cross-link, fix README entries, re-run the link check. ```bash # link integrity — empty output = all local links resolve bash scripts/check-links.sh ``` --- **Source:** [`hashgraph-online/awesome-codex-plugins`](https://github.com/hashgraph-online/awesome-codex-plugins) → `plugins/MedAdemBHA/docflow/skills/author/SKILL.md`