Codex Instructions

Blog Post Workflow

When asked to write or rewrite a blog post, follow these steps in order. Do not skip any step.

  1. Launch two parallel sub-agents (before writing anything):

    Sub-Agent 1: Tag Inventory Agent Scan every post’s front matter in _posts/. Extract all unique tags and categories across the entire blog. Return this exact format and nothing else:

    TAGS: [comma-separated list of all unique tags, sorted alphabetically]
CATEGORIES: [comma-separated list of all unique categories, sorted alphabetically]

    Sub-Agent 2: Style Sampler Agent Given the new post’s topic and candidate tags/categories, find the 3 most recent posts in _posts/ whose tags or categories overlap. Read their front matter and first 30 lines only. Return this exact format and nothing else:

    MATCHING_POSTS: [filename list]
TAGS_IN_USE: [tags from matching posts relevant to this topic]
CATEGORIES_IN_USE: [categories from matching posts]
STYLE_NOTES: [2-3 bullet observations about voice, structure, or conventions for this topic area]

    Both agents must return only their structured output. No prose, no extra commentary.

  2. Use both outputs before writing:
    • Validate tag suggestions against the Tag Inventory. Prefer existing tags. Do not coin new tags if an existing one covers the concept.
    • Use the Style Sampler briefing to calibrate voice and confirm category conventions for this topic area.
  3. Read @docs/blog_writing_style.md and internalize all rules.
  4. Invoke the /dont-slop--humanise skill before writing or rewriting any prose.
  5. Write the post in Jekyll-compatible markdown with correct front matter (match the format of existing posts in _posts/).
  6. Output the full markdown content so the user can review it.
  7. Suggest a filename in the format {year}-{month}-{day}-{slugified-title}.md based on existing posts.
  8. Run the Pre-Publication Checklist below before declaring the post ready. Do not say the post is ready until every item passes.

Pre-Publication Checklist

Before declaring any post ready for publication, verify every item. State which items pass and flag any that fail.

Voice & Style

  • No em dashes anywhere. Search the entire post before confirming.
  • Australian English spelling throughout (organisation, authorisation, recognise, etc.).
  • No marketing speak, vendor buzzwords, or dramatic language (revolutionary, game-changing, deep dive, lingua franca).
  • No formulaic LLM openings (“If you’ve ever…”, “In this post, we’ll explore…”, “In today’s landscape…”).
  • No “Conclusion” heading. Post ends naturally.
  • Prose humanized via the /dont-slop--humanise skill.

Structure

  • Front matter is present and matches the format of existing posts.
  • Post length is appropriate for the type (quick tip: 300-500w, standard: 800-1200w, technical guide: 1500-2000w).
  • Subheadings are used logically, not excessively.
  • No unnecessary “Prerequisites” section for simple topics.

Content

  • Post includes at least one practical “learned this the hard way” or gotcha element.
  • Every section has actionable value.
  • Code examples use appropriate syntax highlighting and helpful inline comments.
  • Technical claims are accurate and specific (versions, tool names, error messages).

Jekyll

  • Front matter date, title, categories, and tags are present and correct.
  • Tags use kebab-case and are drawn from the existing tag vocabulary (confirmed via Tag Inventory sub-agent). Prefer existing tags over new ones.
  • Categories match existing conventions for this topic area (confirmed via Style Sampler sub-agent).
  • Suggested filename follows the {year}-{month}-{day}-{slugified-title}.md convention.

Writing Style

  • No em dashes. Ever. Use commas, parentheses, or rewrite the sentence instead.
  • No -- as a dash substitute. That is equally forbidden. When a sentence needs a dash, rewrite the sentence structure: use a comma, a colon, parentheses, or a full stop. Never substitute a character for an em dash.
  • Australian English spelling always (organisation, recognise, authorisation, etc.).
  • Always invoke the /dont-slop--humanise skill before writing or rewriting any prose.
  • Follow @docs/blog_writing_style.md strictly. It is the authoritative style reference.

Patterns to avoid

  • Negative parallelism. The two-sentence “not X. Y.” structure, or its inline variant “not X, but Y.” State the point directly instead. “Both founders came from the surveillance division” beats “They did not come from research. They came from surveillance.”
  • Trailing negation. Ending a section with “It does not do X.” Rewrite to state what the thing actually does or leaves unchanged.
  • Bare negatives as topic sentences. “It is not a legal firewall.” leads with what something is not. Lead with what is actually true instead.
  • “Worth noting / worth acknowledging.” Performative hedging. Just state the thing.
  • “The absence of X is not the same as Y.” Verbose double-negation. Rewrite to say directly what the absence tells you.

Content Integrity

  • No fabricated first-person content. When writing in the user’s voice, never invent personal anecdotes, tool usage claims, or “learned this the hard way” stories. If the user hasn’t provided a specific experience, use generic or hypothetical framing instead. Do not attribute experiences to the author that they did not share. This rule exists because past drafts invented things like “I’ve built checks for it in a domain scanning tool I maintain” and “a client’s fully locked down domain turned up in a phishing campaign” without any basis. Generic framing (“you’ll typically see…”, “a common scenario is…”) is the correct substitute, not a plausible-sounding first-person claim.
  • Ask before adding unrequested content. When reading the user’s code, tools, or external sources for context, distinguish between “this exists” and “the user wants to write about this.” Ask before adding new sections or claims based on external material.
  • Consistency sweep after removing content. After cutting a section or concept from a post, immediately scan front matter (excerpt, tags, title), all remaining prose, and the closing paragraph for stale references to the removed content. Fix them in the same edit.

Sub-Agent Instructions

  • When launching sub-agents to scan files on this project, always specify: “Use Glob and Read tools only. Do not use Bash, shell commands, or any scripting language.” This project runs on Windows and Python/shell commands will fail.
  • When adapting a draft, preserve the original formatting structure. Do not convert prose patterns (e.g. “First… Second… Third…”) into formatted alternatives (e.g. bold inline headers) that may violate house rules.

Mermaid Diagrams

  • Always add mermaid: true to the post’s front matter or the diagram will not render.
  • Use <br /> for line breaks inside node labels and messages, not \n.
  • The site’s SCSS already has a pre:has(> code.language-mermaid) rule that strips the dark code-block background so diagrams render on the page background. Do not remove it.

Choosing the right diagram type

  • Request/response or stepped process flows (auth handshakes, API call chains, anything with ping-pong between two or more actors): use sequenceDiagram. Participants sit in columns across the top, lifelines run vertically downward, and each message gets its own time-row so labels never overlap. Use autonumber to number the steps.
  • Topology, dependency, or branching flows (where the picture is “what connects to what” rather than “what happens next”): use graph TD or graph LR.

If you find yourself drawing the same actor in two places in a flowchart, or arrows curving back to the same node with labels colliding (e.g. A->|1| B and B->|2| A), that is the signal to switch to sequenceDiagram.

Flowchart styling (graph TD / graph LR)

  • Style every node explicitly. Unstyled nodes get Mermaid’s default white fill, which clashes with the dark code-block background before the CSS fix kicks in.
  • Use light fills with coloured strokes and explicit color:#212529 (dark text). The pattern from existing posts: fill:#d4edda,stroke:#28a745,color:#212529.

Sequence diagram styling (sequenceDiagram)

  • Inject the theme variables at the top of the diagram with an init block rather than per-node styling: 
    %%{init: {'theme':'default','themeVariables':{'actorBkg':'#cce5ff','actorBorder':'#004085','actorTextColor':'#212529','noteBkgColor':'#d4edda','noteBorderColor':'#28a745','noteTextColor':'#212529'}}}%%
  • Pick a noteBkgColor that matches the post’s framing: green (#d4edda / #28a745) for safe-path diagrams, red (#f8d7da / #dc3545) for danger-path diagrams, yellow (#fff3cd / #ffc107) for caution.
  • Use Note over A,B: ... to anchor key invariants alongside the relevant participants instead of creating a floating node like in flowcharts.
  • Keep actor and participant labels on a single line. Do not use <br /> inside actor X as ... or participant X as .... The site’s mermaid renderer sizes the actor box to the first line and clips the wrap, so “User on
    domain-joined PC” displays as just “User on”. If the label is unavoidably long, write it as one line (“User on domain-joined PC”) and let the box stretch. <br /> is still fine inside message arrows and Note over text.
  • Match the Note over span to the text length. The note box is only as wide as the gap between the participants you name (Note over X,Y), and longer text will overflow the box. If a note carries a sentence-length statement, span it across more participants (often Note over <first>,<last> for a full-width callout) rather than just the two it semantically attaches to. Alternatively break the text into shorter lines with <br /> so each line fits the narrower span.

Syntax Highlighting

  • Read @docs/syntax-highlighting.md before changing anything in assets/main.scss related to code blocks, or before adjusting Prism/Rouge behaviour. The site runs a hybrid Prism (client-side) plus Rouge (server-side, partly unavoidable) setup, and the Rouge token colours have to be overridden because Minima’s defaults are unreadable on the dark background.

Jekyll File Safety

  • When creating any new file in the project root that is not site content (e.g. AGENTS.md, config files), immediately add it to the exclude: list in _config.yml so Jekyll does not process it as a page.