Article Pipeline

End-to-end pipeline for producing and publishing illustrated articles.

Paths

What	Path
Personal website	`~/dev/personal/joeyhipolito.dev/`
Article content	`~/dev/personal/joeyhipolito.dev/content/{log,newsletter}/`
Article images	`~/dev/personal/joeyhipolito.dev/public/{log,newsletter}/<slug>/`
Intaglio style bible	`${CLAUDE_SKILL_DIR}/intaglio-bible.md`
Flow generate script	`${CLAUDE_SKILL_DIR}/scripts/flow-generate.sh`
Mascot reference	`~/.contentkit/references/mascot.png`
ContentKit styles	`~/.contentkit/styles/intaglio/`
Engage queue	`~/.alluka/engage/queue/`

Content Types

Kind	Directory	Description
`log`	`content/log/`	Technical deep-dives, system architecture, builder narratives
`newsletter`	`content/newsletter/`	Commentary, opinion, industry analysis

Pipeline Steps

Step 1: Scout for trending topics

scout gather --since 24h
scout intel "ai-coding" --since 24h

Browse topics, find high-engagement threads. Pick a topic — or use an existing draft article.

Step 2: Research the topic

Before writing, deeply research the chosen topic:

Read the source thread/post (use agent-browser or WebFetch to get full content)
Find related threads, papers, or data (check scout intel for cross-references)
Identify the specific numbers, quotes, and evidence that make this worth writing about
Find the angle that connects to nanika/the author's own experience building AI agent systems

Step 3: Craft the title

The title comes first. The article is built to address it.

The title makes a provocative, slightly dishonest claim. The article then defends, qualifies, or dismantles that claim with evidence. The reader clicks because the title stings. They stay because the article is honest.

Title rules:

Make a bold claim that feels slightly wrong or uncomfortable
Short — under 8 words if possible
Use "you" or "your" to make it personal
State a conclusion, not a question (questions are weaker hooks)
The claim doesn't need to be literally true — but the article MUST address why it's true, partially true, or interestingly wrong
Study these examples from the author's LinkedIn (3,000-4,000 impressions each):
- "AI chose nukes. Every time." — article reveals the 95% number has problems but the zero de-escalation doesn't
- "Your CLAUDE.md Is Making Things Worse" — article shows when it's true and the 3 cases where it isn't
- "The Death of Code Review" — article explains why the economics are breaking, not that review is literally dead
- "Companies are only hiring vibe coders now." — article unpacks what the recruiter actually meant

Step 4: Write the article (MDX)

Write the full article at ~/dev/personal/joeyhipolito.dev/content/{log,newsletter}/<date>-<slug>.mdx

Read ${CLAUDE_SKILL_DIR}/voice.md for the full voice reference. Key rules for articles:

Voice:

Write like explaining something to a friend who codes. Not a conference talk, not a blog post.
Simple words. If you wouldn't say it out loud to a coworker, don't write it.
Be honest but fair. When something is overhyped, say so. Acknowledge what's good too.
When someone is wrong, don't say they're wrong. Say "I tried something similar and found that..."
No exclamation marks. No performed excitement. No hedging with stacked qualifiers.
Contractions always. Short sentences. One idea at a time.

Banned words: convergence, leverage, utilize, framework (when you mean "tool"), ecosystem, robust, scalable, groundbreaking, game-changer, paradigm, innovative, cutting-edge, transformative, arguably, it's worth noting, interestingly

Structure — title-first approach:

Open by confronting the title's claim within the first 2-3 paragraphs. The reader clicked because of the title — pay it off early.
Use a specific number, finding, or event as the opening evidence for or against the claim
1500-3000 words. 4-7 sections with H2 headings.
Each section should have concrete evidence: numbers, quotes, commit counts, error logs, specific tool names
Connect everything back to what the author has actually built and run with nanika
By the end, the reader should understand exactly how the title is true, partially true, or usefully wrong
End with an honest open question, not a conclusion that wraps things up neatly
Place <Figure> tags at section transitions (max 3-4 total, not after every heading)

Content types:

log — technical deep-dives, builder narratives, system architecture (written from experience building nanika)
newsletter — commentary, opinion, industry analysis (written from watching the industry while building)

Frontmatter:

---
id: <slug>
title: "Article Title"
date: "YYYY-MM-DD"
description: "Short subtitle (under 256 chars — Substack rejects longer)"
published: false
tags: ["ai", "agents", "topic"]
author: "Jose Marcelius Hipolito"
excerpt: "Reader-facing excerpt"
kind: log  # or newsletter
---

Step 5: Generate art prompts

Read the full article. For each image needed (1 cover + 1 hero + 0-3 inline), create a prompt directory:

/tmp/illustrate/<slug>/
├── 000-cover/
│   ├── prompt.md
│   └── mascot.png  (only if nanika appears)
├── 001-hero/
│   ├── prompt.md
│   └── mascot.png  (only if nanika appears)
└── 002-section-name/
    └── prompt.md

CRITICAL: Every prompt.md must start with **Illustration:** <folder-name> — this tag is how the download step maps generated images back to folders.

Prompt format

Read ${CLAUDE_SKILL_DIR}/intaglio-bible.md for the full style rules. Key points:

Intaglio engraving on cream paper #F2EAD7
One terracotta #DA7757 object per image — the focal point
Literal/editorial scenes, NOT metaphors
Cover image (000-cover): 1200×630, more expressive, focal point centered in safe 60% zone
Hero/inline: 950×500 landscape

When nanika appears, describe rendering explicitly:

Mask face is smooth bare cream paper framed by dense crosshatched black hair.
Circuit-board robe in fine geometric hatching. Headband with emotion faces
in delicate line work. White gloves are bare paper with faint contour lines.
Monochrome. Match reference image proportions — chibi with oversized head.

Do NOT just say "chibi" — describe how each feature translates to engraving.

Nanika is optional — use judgment based on article context. Default to no mascot.

Copy ~/.contentkit/references/mascot.png into any prompt folder where nanika appears.

Step 6: Generate images (Google Flow)

${CLAUDE_SKILL_DIR}/scripts/flow-generate.sh <slug> <log|newsletter> [--style intaglio]

This script:

Creates or reuses a Flow project
Dismisses any consent modals
For each prompt folder: attaches mascot reference (if present), pastes prompt, clicks Create
Waits for all images to generate
Downloads and places images in ~/dev/personal/joeyhipolito.dev/public/<type>/<slug>/

Requires: Chrome debug running on port 9222 (--remote-debugging-port=9222 --user-data-dir=~/.chrome-debug).

Step 7: Create manifest

Create ~/dev/personal/joeyhipolito.dev/public/<type>/<slug>/manifest.json:

{
  "article": "<full-path-to-mdx>",
  "created": "<ISO-8601>",
  "cover": "<full-path-to-cover.png>",
  "assets": [
    {
      "type": "illustration",
      "section": "",
      "description": "Hero alt text",
      "path": "<full-path-to-hero.png>"
    },
    {
      "type": "illustration",
      "section": "Section Heading",
      "description": "Inline alt text",
      "path": "<full-path-to-inline.png>"
    }
  ]
}

Step 8: Update Figure tags in MDX

Ensure each <Figure> in the article has the correct src path and descriptive alt text:

<Figure src="/<type>/<slug>/hero.png" alt="Descriptive alt text" />

Step 9: Cross-post to Substack

substack draft <article.mdx> \
  --manifest <manifest.json> \
  --public-dir ~/dev/personal/joeyhipolito.dev/public \
  --tags "tag1,tag2" \
  --audience everyone

Note: Description/subtitle must be under 256 characters or Substack returns HTTP 400.

Verify: substack drafts — should show the new draft.

Step 10 (optional): Cross-platform adapt

engage adapt --platforms linkedin,x,reddit <article.mdx>
engage review
engage approve <id>
engage post