publish-to-blog
Skill8 starsChanged 11 days agoApache-2.0View on GitHub
Publish a finished blog post from this repo to the pipermorgan.ai website
- Commits and pushes
In this repository39 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .cursor/rules/architecture-patterns.mdcCursor rule
- .cursor/rules/completion-discipline.mdCursor rule
- .cursor/rules/github-tracking.mdcCursor rule
- .cursor/rules/programmer-briefing.mdcCursor rule
- .cursor/rules/verification-first.mdcCursor rule
- ab-a-isolationSkill
- assign-sprint-safelySkill
- audit-cascadeSkill
- brief-coding-agentSkill
- check-mailboxSkill
- cleanup-dev-activeSkill
- close-issue-properlySkill
- cohort-attention-rollupSkill
- compost-reviewSkill
- continue-narrativeSkill
- create-omnibusSkill
- create-session-logSkill
- cut-releaseSkill
- delete-module-safelySkill
- deliver-mailSkill
- discovered-work-captureSkill
- doc-sync-sweepSkill
- draft-blog-postSkill
- draft-weekly-shipSkill
- duty-cycle-tickSkill
- narrative-verificationSkill
- piper-draft-issueSkill
- piper-draft-specSkill
- piper-sprint-planSkill
- piper-stakeholder-updateSkill
- piper-synthesize-feedbackSkill
- propose-featureSkill
- query-github-boardSkill
- template-auditSkill
- trust-checkSkill
- update-calendarSkill
- update-current-stateSkill
- update-piperSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 8 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 81
Only after the dry-run output looks clean do you run the real publish.
- Distinctive: line 87
Use this skill when:
- Very specific: line 100
Before invoking publish-post.js (dry-run or real), verify the two expected files actually exist at the paths the frontmatter and CLI flags …
- Distinctive: line 108
If the draft path or image path doesn't resolve, stop and check with PM before proceeding.
- Distinctive: line 143
Do not assume the newer mtime is the better one — read the diff.
- Very specific: line 173
If xian has moved a post off its slot on purpose, his word in the row's notes is the answer.
- Very specific: line 192
If both exist, PM's working copy ({slug}.md) is canonical — edits + publish go to that file.
- Very specific: line 193
If only draft-{slug}.md exists, PM hasn't started an edit pass yet — that's the canonical source until PM creates a working copy.
- Very specific: line 194
If only {slug}.md exists, that's canonical.
- Distinctive: line 238
Run this before opening the draft, before reading the calendar row, before anything.
- Very specific: line 246
Before opening the draft, look up its row in docs/internal/planning/comms/editorial-calendar.csv:
- Distinctive: line 280
When a finding contradicts the template, the template wins.
- Very specific: line 342
Look up the next post in the editorial calendar for the footer teaser.
- Distinctive: line 357
Run this as one Python script to minimize round-trips:
- Distinctive: line 489
Verify the post appears with correct slug, category, thumbnail, and content.
- Distinctive: line 517
After the skill writes, verify with the canonical validator (Python csv parser.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
publish-to-blog
Publish a finished markdown blog post to the pipermorgan.ai website repository.
Mechanical pipeline encoded as a script (v0.10)
The mechanical first half of this skill — parse draft, extract metadata, generate hashId, convert markdown → HTML, prep image, append CSV row, write blog-content.json entry, run sync + fetch — is now a single Node CLI:
piper-morgan-website/scripts/publish-post.jsPrefer the script for any new publish. Invoke it from either the website repo CWD (matches the v0.9 cd pattern) or from this repo with the cross-repo path. Two examples:
# Blog-first (insight or building):
node ../piper-morgan-website/scripts/publish-post.js \
--draft docs/public/comms/drafts/{filename}.md \
--image docs/public/comms/drafts/{image}.png \
--slug {slug} \
--category {building|insight} \
--work-date {YYYY-MM-DD} \
--cluster {era-slug}
# Ship:
node ../piper-morgan-website/scripts/publish-post.js \
--draft docs/public/comms/drafts/{filename}.md \
--slug {slug} \
--category ship \
--work-date {YYYY-MM-DD} \
--cluster {era-slug}The script stops before commit/push so PM can review the diff. Use --report=json for a machine-readable exit report (agent invocation); --dry-run to preview HTML conversion + intended mutations without writing.
--work-date is mandatory — never let it default (v0.17)
Always pass --work-date explicitly. The script defaults workDate to today when the flag is omitted (args['work-date'] || todayIso()), which silently writes the publish date into the website CSV's workDate column — a false value in a source-of-truth file. This is invisible in the dry-run (it reports the CSV append without showing the workDate) and invisible in the rendered post (the dateline comes from the draft body, not the CSV), so it slips through unless caught here.
The correct workDate is the source-work-period — the dates the post is about, not when it was drafted or published (per feedback_calendar_workdate_is_source_work_period). Get it from, in priority order:
- The draft's dateline (
*April 8, 2026*→2026-04-08; for a range*Apr 23–24, 2026*use the start date2026-04-23). - The product editorial-calendar
workDatefield for this post (Comms-stewarded canonical).
Confirm the two agree before publishing; if they diverge, surface it (the dateline and the calendar workDate should describe the same work period).
The 2026-06-02 incident: Bring Your Own Chat (and a retroactive audit found 5 other recent posts — when-your-ai-makes-things-up, stacked-silent-failures, two-migrations-in-one-day, the-misfiled-voice-guide, from-protocol-to-infrastructure) all published with workDate == pubDate because --work-date was omitted. All corrected; this discipline + the dry-run check below prevent recurrence.
--cluster is now optional — derived from --work-date, fails loud if it can't (v0.26, 2026-09-29)
Unlike --work-date, omitting --cluster is now safe. publish-post.js derives it from
--work-date against episodes.ts's ERAS ranges when the flag isn't passed, and errors instead
of writing an empty value if workDate falls outside every era. This superseded a prior
"assigned during periodic manual review" docstring note that predated Comms's 09-06 work proving
the mapping is 100% mechanical — two posts (09-26, 09-27) had shipped with a silently-empty
cluster under the old default before the fix, backfilled by Web (e2baf72, #1905). You can
still pass --cluster {era-slug} explicitly to override, but you no longer need to look it up
from a sibling post's row by hand.
Always dry-run first (mandatory, v0.13)
Every publish invocation MUST be preceded by a --dry-run invocation with otherwise-identical flags. Read the preview HTML against the source draft. Look for:
- Missing or empty frontmatter values (image/alt/caption) — the CLI passes them through as empty strings without warning
- Markdown features that don't render as expected (numbered lists become
<p>+<br />not<ol>/<li>; inline block-level HTML gets wrapped in<p>; etc. — see "Known CLI conversion gaps" if surfaced) - HashId, slug, category alignment with calendar
- Image source path resolving correctly + WebP target path matching slug
workDateis the source-work-period, NOT today/pubDate — the dry-run reportswould append CSV rowwithout showing workDate, so confirm separately: did you pass--work-date? Does it match the draft dateline? After the real publish,grep {slug} ../piper-morgan-website/data/blog-metadata.csvand verify theworkDatecolumn ≠ pubDate (unless the work genuinely happened on publish day). See the--work-datemandatory section above.
Only after the dry-run output looks clean do you run the real publish. The dry-run is fast (~5 sec) and catches the failure modes that mutate-then-fix would cost more than cp -r to recover.
The manual procedure below is preserved as the canonical reference for what the script does — read it when debugging script output or when an edge case forces a one-off manual publish. The higher-judgment steps (voice-pass, syndication, footer-teaser selection, cross-post, calendar updates, drafts archival) remain skill-owned and follow the script invocation.
When to Use
Use this skill when:
- PM says a draft is ready to publish to the blog
- A piece in the editorial calendar has status
readyorqueuedwith today's pubDate - PM asks to "push to the blog" or "publish this post"
Prerequisites
- The draft markdown file must exist in
docs/public/comms/drafts/ - The image must be in the same directory (PM provides)
- Image metadata should be in the draft's comment block (see below) or provided conversationally
Pre-flight: verify files exist (mandatory, v0.15)
Before invoking publish-post.js (dry-run or real), verify the two expected files actually exist at the paths the frontmatter and CLI flags will resolve to:
# Parse frontmatter image filename, then verify both files exist
IMAGE_NAME=$(grep -m1 '^image:' docs/public/comms/drafts/{filename}.md | sed "s/image:[[:space:]]*//;s/[\"']//g")
ls -la docs/public/comms/drafts/{filename}.md docs/public/comms/drafts/$IMAGE_NAMEIf the draft path or image path doesn't resolve, stop and check with PM before proceeding. Common situations:
- Image still in
~/Downloads/: PM created the image but hasn't moved it to drafts/ yet. Ask PM to move it (or move it on PM's behalf with confirmation). May 17 incident: From Protocol to Infrastructure publish caught this on the pre-flight; would have failed at image-prep step otherwise. - Frontmatter has placeholder image name (e.g.,
image: 'ai-.png') but actual image has a real name: PM hasn't finished filling in metadata. Ask PM to finalize the frontmatter before publish. - Wrong filename in frontmatter: PM filled in something like
image: 'ai-garden.jpg'but the file is actuallyai-garden.png. Surface the mismatch.
Dry-run alone does NOT catch this — the script reports "[dry-run] would prep image: /path/to/X" without verifying the path exists. The pre-flight ls is what guarantees the file is in place.
⚠️ Existence is not correctness — OPEN the image and compare it to the frontmatter alt (added 2026-10-03). A file can exist, resolve, and be the wrong picture. Described Is Not Running published 10-03 with the 10-01 post's tailor-shop art under a new filename, while its alt/caption described a fountain; the ls passed, the dry-run passed, and nothing looked at the pixels. Read the image file (the Read tool displays it), confirm it depicts what alt says, and compare its md5 against the previous few posts' source images in drafts/published/ to catch a re-uploaded duplicate. If alt and image disagree, stop and ask PM before publishing. (Layer: m-43 — file-presence verifies the path, not the content.)
Pre-flight 2: DIFF THE TWO DRAFT COPIES (mandatory, v0.21 — 2026-07-31)
A draft frequently exists in two places: dev/active/{slug}.md (working copy, where PM and Comms
often edit) and docs/public/comms/drafts/{slug}.md (the copy draftPath points at, and the one you
publish from). They diverge silently.
SLUG={slug}
if [ -f "dev/active/$SLUG.md" ] && [ -f "docs/public/comms/drafts/$SLUG.md" ]; then
diff "dev/active/$SLUG.md" "docs/public/comms/drafts/$SLUG.md" \
&& echo "✓ copies identical" \
|| echo "⛔ DIVERGED — reconcile BEFORE publishing; the drafts/ copy is what ships"
fiWhy this is mandatory rather than advisory: on 2026-07-30, commit e91cb5466 added the Almost Beta
image block to the dev/active/ copy only. The drafts/ copy — the one draftPath resolves to and
the one publish-post.js reads — never received it. A publish would have silently dropped the image
and reported success. Comms caught it by diffing; nothing in the pipeline would have.
⚠️ This is chronic, not a one-off. Weekly Ship #052's draftPath also pointed at a file that wasn't
where the row said, and a 2026-07-12 pass repaired 22 stale paths without fixing the cause. Treat two
copies as expected and reconcile every time.
If they differ: the docs/public/comms/drafts/ copy is what publishes, so it must be the superset.
Do not assume the newer mtime is the better one — read the diff. The 07-30 case was an addition
present only in the copy that does not ship.
Pre-flight 3: the category must match the pubDate's weekday (mandatory, v0.27 — 2026-11-07)
The calendar's theme is the --category, and the calendar can be wrong. "At Long Last, Beta" was
filed as a building row for Saturday 11-07, Comms' memos said building, and it published as building.
Weekends are insights (xian caught it). Step 0's "confirm the category" read the row, and the row was the
error. So check the row against the slot table before passing --category:
python3 - "{exact calendar title}" <<'EOF'
import csv, datetime, runpy, sys
slots = runpy.run_path("scripts/validate-editorial-calendar.py", run_name="slots")["SLOT_BY_WEEKDAY"]
rows = [r for r in csv.DictReader(open("docs/internal/planning/comms/editorial-calendar.csv")) if r["title"] == sys.argv[1]]
if len(rows) != 1:
sys.exit(f"STOP: {len(rows)} calendar rows titled {sys.argv[1]!r}")
r = rows[0]
d = datetime.date.fromisoformat(r["pubDate"])
want = slots.get(d.weekday())
print(f"{r['pubDate']} {d:%a}: row says {r['theme']}, slot says {want or 'no post'}")
sys.exit(0 if r["theme"] == want else "STOP: ask Comms before --category")
EOF- The table is
SLOT_BY_WEEKDAYinscripts/validate-editorial-calendar.py, so there's one copy. The readable form, with syndication targets, is "Publishing Slots and Syndication" indocs/briefing/BRIEFING-ESSENTIAL-DOCS.md. Sat and Sun are insight, Tue and Thu building, Wed ship, and Mon and Fri have no post. - On a STOP, ask Comms, and don't publish first. A memo's category is a claim to check, not a source.
If xian has moved a post off its slot on purpose, his word in the row's
notesis the answer. Say so in your log and pass the row's category.
Future CLI enhancement candidate (flagged to web in the May 17 feature-corpus memo): a --check mode that runs all pre-mutation validation (image exists, frontmatter populated, slug not already used) without doing anything else.
Filename Convention (which draft is the source of truth?)
Two filename patterns coexist in docs/public/comms/drafts/:
{slug}.md— PM's working copy (the file PM edits in their editor; the canonical source for publish)draft-{slug}.mdordraft-{slug}-vN.mdordraft-{topic}.md— Comms's earlier draft(s) (sometimes superseded by PM's working copy; sometimes the only file if PM hasn't started an edit pass)
Before editing or invoking the script, surface both so you know which is canonical:
ls docs/public/comms/drafts/ | grep -i "{slug-or-topic-keyword}"Rules of thumb:
- If both exist, PM's working copy (
{slug}.md) is canonical — edits + publish go to that file. Confirm with PM if ambiguous (e.g., thedraft-prefix file has substantive content PM might still be merging). - If only
draft-{slug}.mdexists, PM hasn't started an edit pass yet — that's the canonical source until PM creates a working copy. - If only
{slug}.mdexists, that's canonical.
May 17 incident as the failure-mode evidence: applied proofread edits to draft-protocol-to-infrastructure-insight.md while PM was editing from-protocol-to-infrastructure.md. The edits never reached PM's working copy directly; PM transferred recommendations by hand. Surfaced both files at session start would have caught this.
Draft Metadata Convention
Preferred (YAML frontmatter) — visible in Markdown editors, survives Medium paste:
---
image: filename.png
alt: Description of the image for screen readers
caption: Caption text
---
# Post TitleLegacy (HTML comments) — still supported for backward compatibility:
# Post Title
<!-- image: filename.png -->
<!-- alt: Description of the image for screen readers -->
<!-- caption: "Caption text in quotes" -->The skill accepts either format. YAML frontmatter takes precedence if both are present. If neither is present, ask PM for image filename, alt text, and caption.
The skill MUST strip both frontmatter blocks and comment lines when converting to HTML.
Comms draft template: docs/internal/planning/comms/blog-post-template.md
Proofread Discipline (read these first — every time)
Pre-Step: Sync worktree to origin/main (mandatory — before any file reads)
PM commonly edits drafts via the GitHub Web UI or another session. Those commits land on origin/main but not in your local worktree until you merge. Reading a stale local copy produces false audit failures (e.g., empty frontmatter that PM already filled in) with no error — the file just reads wrong.
git fetch origin main -q && git merge origin/main -q --no-editRun this before opening the draft, before reading the calendar row, before anything. Takes ~2 seconds and prevents the entire class of "stale draft" false alarms.
The 2026-07-18 incident: PM added frontmatter and revised the draft via the Web UI; Comms caught and fixed an encoding error in the caption. Docs read the pre-edit local copy, reported three frontmatter FAIL findings, and had to be corrected by PM before proceeding. One merge would have caught it immediately.
⚠️ This sync is not a one-time gate — re-run it any time PM says something mid-pipeline that implies a file changed, not just at the start. 2026-09-19 near-miss: mid-publish, after the proofread pass and after generating the hashId, PM mentioned in conversation ("I changed the title... I've made an editorial pass on tomorrow's post too") that both today's and tomorrow's drafts had been edited further. The pipeline had already been running on an earlier sync. Re-fetching at that point surfaced a real state change: the calendar's own status field had moved from drafted to ready-for-docs with a fresh Comms note, and tomorrow's post title had changed in a way that (by luck) already matched the footer tease in today's draft. Had the mid-pipeline mention been treated as FYI-only and not acted on, the publish would likely still have succeeded on stale-but-consistent data this time — but the near-miss is the pattern, not this specific outcome: any PM remark implying an edit, anywhere between the initial sync and the final commit, is a re-sync trigger, not just a note to file away. Same discipline as feedback_sync_applies_to_every_file_read generalized to a multi-step pipeline: the risk isn't only reading a stale file, it's continuing to act on a sync that was correct when taken but has since aged past a signal that it's stale.
Step 0: Check the editorial calendar first
Before opening the draft, look up its row in docs/internal/planning/comms/editorial-calendar.csv:
grep -i "{title-keyword}" docs/internal/planning/comms/editorial-calendar.csvConfirm:
- pubDate — when is this scheduled? Is it today, or is there scheduling slack?
- status —
queued(ready to schedule),ready(approved to publish), or other? - workDate / endWorkDate — the source-work-period; must match the post's dateline
- category —
building,insight, orship(needed for publish-post.js--categoryflag). It must match the pubDate's weekday: run Pre-flight 3. - draft path — confirm it matches the file you're about to read
Surface any mismatches before doing anything else. The calendar is the ground truth for scheduling and dateline semantics; the draft is the artifact. A dateline disagreement caught here costs nothing. Caught at publish time, it means a re-push.
Then open the draft and the canonical references below.
Canonical references (open before reading the draft)
Open these three, not memory:
docs/internal/planning/comms/editorial-calendar.csvrow for this post (Step 0 above)docs/internal/planning/comms/blog-post-template.md— structure, dateline format, heading conventions, footer pattern, frontmatter rules, "what Comms confirms before delivering" checklistdocs/internal/planning/comms/xian-voice-tone-guide.md— voice/tone, sentence-structure preferences, transparency patterns, editorial moves applied at voice-passdocs/internal/planning/comms/blog-style-guide.md— house terminology decisions that deliberately override conventional wisdom (e.g. "minimum valuable product," not "viable") — check this AND the glossary before "fixing" any spelled-out term that looks wrong
Read these first, not memory. Memory pins capture specific lessons (no semicolons / no superlatives / parenthetical-gloss on first use / comma splices as PM voice / etc.) but the template + voice guide are the source of truth. Working from memory alone is the failure mode that lets template drift slip past unnoticed.
⚠️ A term that looks like a typo may be a documented deliberate choice — check before "fixing." 2026-09-12: "corrected" "minimum-valuable-product" to "minimum-viable-product" during proofread, reasoning from the conventional term rather than checking blog-style-guide.md/the glossary first — published live before catching it via the file's own git history (PM had just reasserted the deliberate spelling via the admin UI, after this session's initial sync). The lesson generalizes beyond this one term: a stale sync plus an unverified "correction" is how a deliberate choice gets silently reverted. Re-sync immediately before any edit that changes wording, not just at session start, and check the style guide before overriding anything that reads as unconventional.
Editorial calendar field semantics matter at proofread time too: per template line 133, "Dateline matches the actual work period covered." The calendar's workDate / endWorkDate fields capture the source-work-period (dates of the work being written about), not the drafting window. If a row's workDate looks like it's the drafting window, surface the drift rather than treat it as source of truth.
May 17 evidence: dateline-semantics drift was missed on From Protocol to Infrastructure because the proofread pass was anchored on memory pins rather than the template. PM caught it: "Are you using the template or blog writing guidelines as a source of truth or format when proofreading?" Honest answer was no. The discipline fix is to make the template + voice guide the first thing opened on every proofread pass — not relying on memory to surface every applicable rule.
When a finding contradicts the template, the template wins. When the template seems wrong or stale, surface it as a template-drift flag for PM rather than silently following the memory version.
Cross-reference: feedback_blog_template_and_voice_guide_canonical_for_proofreads memory pin captures the broader discipline.
Redundancy + noteworthiness pass (added 2026-06-03 per PM, after Ship #045)
Two checks on every proofread pass, especially for longer pieces (Ships, dense narratives):
- Review for redundancy → consolidate or choose one telling. If the same event/story/numbers appear in two places (e.g., a Ship's opening hook AND its learning-pattern example re-narrating the same clash story with the same counts), don't keep both — let one carry it and have the other reference it. Repetition reads as padding and inflates length. (Ship #045: the opening and the learning-pattern example both told the shared-main-clash story verbatim; trimmed the example to lean on the opening.)
- Cut for noteworthiness — we don't report everything we did. Flag whole items (bullets, paragraphs) that are process-internal rather than result-shaped: a reader cares about what got done and what it means, not every internal status-level/refinement/reconciliation. This is a process-oriented project and some of that ethos is load-bearing in public — but there's a limit to any reader's attention. Propose whole-item cuts to PM (not sentence-shortening, not noun-dropping). Strongest cut candidates: new-internal-status-levels, granular sub-refinements, internal process self-references.
How to apply: propose the trims to PM as a ranked list of whole items with grep-able snippets; let PM decide which to cut. Don't unilaterally drop content from a Ship.
Procedure
Step 1: Read Draft and Extract Metadata
# Parse the draft file
# 1. YAML frontmatter (if present) → image / alt / caption
# - File starts with line "---"
# - Ends at next "---" line
# - Parse keys: image, alt, caption
# 2. H1 line → title
# 3. <!-- image: ... --> / <!-- alt: ... --> / <!-- caption: ... -->
# → fallback if no frontmatter (strip outer quotes from caption)
# 4. Everything else (after stripping frontmatter, title, comments)
# → body content for HTML conversionFrontmatter parsing snippet (preferred format):
import re
def parse_draft(path):
with open(path) as f:
text = f.read()
meta = {}
body_text = text
# Detect YAML frontmatter (file starts with "---" on line 1)
m = re.match(r'^---\n(.*?)\n---\n', text, re.DOTALL)
if m:
yaml_block = m.group(1)
for line in yaml_block.splitlines():
if ':' in line:
k, _, v = line.partition(':')
meta[k.strip()] = v.strip().strip('"').strip("'")
body_text = text[m.end():]
# Fallback to HTML comments if frontmatter absent or missing fields
for key in ('image', 'alt', 'caption'):
if key not in meta or not meta[key]:
cm = re.search(rf'<!--\s*{key}:\s*(.+?)\s*-->', body_text)
if cm:
meta[key] = cm.group(1).strip().strip('"').strip("'")
return meta, body_textLook up the next post in the editorial calendar for the footer teaser.
Determine category from the editorial calendar (building, insight, or ship), after Pre-flight 3 has confirmed it matches the weekday.
Step 2: Generate hashId
Blog-first posts (not yet on Medium):
python3 -c "import uuid; print(uuid.uuid4().hex[:12])"hashId MUST be valid hex (0-9, a-f only) — the content lookup regex requires this.
Backlog posts (already on Medium): Extract hashId from the Medium URL's last segment.
Step 3: Full Pipeline (Single Script)
Run this as one Python script to minimize round-trips:
import csv, json, re, os, subprocess
# Inputs
DRAFT_PATH = "docs/public/comms/drafts/{filename}.md"
WEBSITE_REPO = "../piper-morgan-website"
HASH_ID = "{generated_hex}"
SLUG = "{slug}"
# 1. Read draft, extract metadata, strip H1 + metadata comments only
# 2. Convert markdown → HTML (preserve non-metadata comments; see HTML Conversion Rules)
# 3. Prepare image: sips -Z 1200, cwebp -q 80 → website/public/assets/blog-images/
# (Ships reuse existing piper-ship.webp — skip this step)
# 4. Add to website blog-metadata.csv (13 columns)
# 5. Add entry to website blog-content.json (see blog-content.json Schema below)
# 6. Run sync + fetch pipeline
# 7. Verify post appears in medium-posts.jsonblog-content.json Schema (REQUIRED shape)
src/data/blog-content.json is a JSON object (dict) keyed by hashId. Every value MUST be a dict, not a bare HTML string:
{
"a6f224685f5a": {
"title": "Sibling Intelligence",
"content": "<p><em>March 19–21, 2026</em></p>\n<p>...</p>"
},
"2e3dad52ecc1": {
"title": "Weekly Ship #038: The Floor Comes Alive",
"content": "<p><em>April 3–9, 2026</em></p>\n<p>...</p>"
}
}Required fields: title, content. Optional field: subtitle (seen on some older posts; leave out if empty).
This schema applies to all categories — narrative (building), insight (insight), and ship (ship). There is no per-category shape difference, despite what older notes may imply.
Do not store values as bare strings. The site's BlogPostContent renderer appears to accept both shapes as of 2026-04, but mixing schemas in the same file is a latent bug: any downstream tooling (bespoke editors, migration scripts, search) will have to branch on typeof value. Canonicalize on the dict shape.
Python write snippet (append-or-overwrite one entry):
with open(json_path) as f:
content = json.load(f)
content[HASH_ID] = {
"title": TITLE,
"content": HTML,
}
with open(json_path, "w") as f:
json.dump(content, f, indent=2, ensure_ascii=False)HTML Conversion Rules
Strip from output:
- YAML frontmatter block (if present — starts with
---on line 1, ends at next---) - H1 title line (the FIRST
# Titleonly — see heading note below) - Only the metadata comment lines at the top of the file (
<!-- image: ... -->,<!-- alt: ... -->,<!-- caption: ... -->,<!-- no caption -->) — these are consumed during metadata extraction and should not reach the output
Preserve all other HTML comments through to the output HTML. Inline directive comments (e.g., <!-- image: 'inline.webp' --> placed mid-article for a future inline-image feature) are invisible in rendered pages and retain a hook for retroactive upgrades. Comments are harmless by design; stripping them destroys authorial intent we may want to process later.
Heading convention (updated 2026-04-18): Drafts use # for top-level section headings and ## for subsections. These convert to distinct HTML heading levels in the output (<h1> and <h2>), which matters because LinkedIn otherwise collapses multiple ## levels into the same size, forcing PM to manually fix the hierarchy after paste.
Conversion rules:
- Strip ONLY the first
# Title(the title at line 1 after frontmatter) — title is rendered separately by the blog template - Convert subsequent
# Sectionlines to<h1>Section</h1> - Convert
## Subsectionto<h2>Subsection</h2> - Convert
### Sub-subsectionto<h3>Sub-subsection</h3>
# In conversion loop, track whether title H1 has been stripped:
title_stripped = False
for line in body_lines:
if line.startswith('# ') and not title_stripped:
title_stripped = True
continue # skip the title line
if line.startswith('### '):
emit(f'<h3>{line[4:]}</h3>')
elif line.startswith('## '):
emit(f'<h2>{line[3:]}</h2>')
elif line.startswith('# '): # subsequent H1 = top-level section
emit(f'<h1>{line[2:]}</h1>')Note on the H1-in-body decision: Using <h1> for post sections produces multiple H1s on the rendered blog page (the site template also renders the title as H1). This is a deliberate trade-off: LinkedIn syndication strips the site template, so body-level H1s become the visible top-level heading there. The blog page still renders legibly because CSS controls visual hierarchy. If SEO impact becomes a concern, revisit this decision.
Convert:
---→<hr>- Paragraphs with inline:
**bold**,*italic*,[links](url) _italic standalone lines_→<p><em>...</em></p>*italic standalone lines*→<p><em>...</em></p>- Em dashes:
--→— - Unordered lists:
- item→<ul><li>item</li></ul> - Blockquotes:
> text→<blockquote><p>text</p></blockquote>— used for verbatim quoted content (e.g., the CIO audit's opening in Audit and Talk; HOST's superlative claim in Same Failure). Consecutive>lines join with a single space inside one<p>inside one<blockquote>. - Markdown tables:
| col | col |rows followed by| --- | --- |separator →<table><thead><tr><th>...</th></tr></thead><tbody><tr><td>...</td></tr></tbody></table>. Used in Ship posts for metrics blocks (Ship #042). PM converts to bullet list on LinkedIn cross-post; canonical keeps the table. - Multi-line paragraph blocks (consecutive non-blank lines without blank-line separator) → join with
<br />inside one<p>. Used for "labeled list" content where each line should display on its own visual line but they semantically belong as one block (e.g., the position-notation breakdown in Inchworm Position:(3) ALPHA foundation / (3.1) Initial alpha testing - v0.8.0 / ...). Single-line paragraphs stay as one<p>.
Image Preparation
Preferred (when cwebp is available):
sips -Z 1200 "{source_image}" >/dev/null 2>&1
cwebp -q 80 "{source_image}" -o "{website_repo}/public/assets/blog-images/{slug}.webp"Established fallback (Pillow / Python — when cwebp is unavailable): on machines without cwebp (e.g., systems lacking the webp Homebrew package), substitute Pillow's WEBP encoder. Verified across 4 publish cycles (Inchworm 2026-05-11, Ship #042 2026-05-13, Audit and Talk 2026-05-12, Same Failure 2026-05-14). Pillow ships in the project's Python environment (pip3 list | grep -i pillow confirms).
from PIL import Image
img = Image.open("{source_image}")
img.thumbnail((1200, 1200), Image.LANCZOS) # max dimension 1200; preserves aspect
img.save("{website_repo}/public/assets/blog-images/{slug}.webp", "WEBP", quality=80)Output equivalence: Pillow WEBP at quality=80 produces files in the same size range as cwebp -q 80 (observed: 83KB - 297KB depending on source complexity). No production-side difference detected.
Ship posts skip image prep entirely — they reuse the existing piper-ship.webp in production. The CSV row sets imageSlug=piper-ship.webp and no new conversion is needed.
Step 4: Sync and Fetch
cd {website_repo}
node scripts/sync-csv-to-json.js
node scripts/fetch-blog-posts.jsVerify the post appears with correct slug, category, thumbnail, and content.
Step 5: Build and Push Website
cd {website_repo}
npm run build # This also re-runs fetch — ensure CSV data persists
git add data/blog-metadata.csv src/data/blog-content.json src/data/medium-posts.json public/assets/blog-images/{imageSlug}
git commit -m "Add blog post: {title}"
git push origin mainCRITICAL: npm run build regenerates medium-posts.json from RSS + CSV. Manual edits to that file do NOT persist. All post data must flow through blog-metadata.csv.
Post-publish edit-pass mirror (when PM makes edits during cross-post to Medium/LinkedIn and provides the scrape or directly modifies the canonical draft): keep the same hashId, re-run only the HTML conversion step, and update blog-content.json in place. Re-run npm run build to refresh medium-posts.json if the title/featuredImage changed (usually neither does). Commit message: Update blog post: {title} — {short edit summary}. Verified across Inchworm (May 11) + Ship #042 (May 13) edit-pass mirror cycles.
Step 6: Update Editorial Calendar
Always invoke the /update-calendar skill — never hand-edit editorial-calendar.csv. The skill knows the 18-field column structure + CSV-escape rules (commas in altText, double-quotes in caption, etc.). Hand-editing has produced field-count drift + unescaped-comma bugs (May 17 incident). This rule applies to all calendar edits — publish-time (this step), syndication-URL follow-on (after Step 8), workDate corrections, status changes, anything.
Invoke /update-calendar with:
- status →
published(blog-live; changes todistributedat Step 8 after cross-posting) - pubDate → today
- canonicalSite →
distributed(pipeline dedup signal — set now even though status stayspublisheduntil cross-post) - blogURL →
https://pipermorgan.ai/blog/{slug}/ - blogPath →
/blog/{slug} - altText, caption from draft metadata
After the skill writes, verify with the canonical validator (Python csv parser; NOT awk-comma-split, which mis-counts on quoted fields):
python3 scripts/validate-editorial-calendar.pyExpected output: ✓ editorial-calendar.csv: N data rows + 1 header, all 18 fields, clean and exit code 0. Any failure prints the offending row(s) with field count + title preview, exits non-zero.
The validator checks every row in one pass; if you only want to verify a specific row, the inline equivalent is:
python3 -c "
import csv
with open('docs/internal/planning/comms/editorial-calendar.csv') as f:
for i, row in enumerate(csv.reader(f), 1):
if i == TARGET_ROW_NUM: print(f'Field count: {len(row)}'); break
"Expected: 18 fields. If the row reports anything else, an escape went wrong and the skill needs a follow-up pass.
Step 7: Commit Product Repo
Apply the commit-discipline opening per feedback_clear_index_before_staging_on_shared_main.md (the product repo is shared main; pre-existing index residue from other agents is a real failure mode):
git reset HEAD # clear any pre-existing index residue from other agents
git add docs/internal/planning/comms/editorial-calendar.csv
git diff --cached --name-only # READ EVERY LINE of output before commit
git branch --show-current # verify branch (separate one-shot)
git commit -m "editorial calendar: {title} published"
git push origin HEAD:main(The website repo at Step 5 doesn't typically have multi-agent activity; the index-residue discipline applies primarily to product-repo commits.)
Step 8: PM Syndicates
PM does manually:
- Medium: Paste content, set canonical URL to
https://pipermorgan.ai/blog/{slug}/(trailing slash!) - PM provides Medium URL → Docs updates calendar via
/update-calendar: set mediumURL, liPubDate/linkedinURL if applicable, and status →distributed(signals blog + cross-posted; PM-ratified 2026-07-19)
Step 9: Drafts Folder Cleanup (Final Step)
ONLY after verifying:
- ✅ Post is live at
https://pipermorgan.ai/blog/{slug}/— verify by content, never by status code.pipermorgan.aireturns HTTP 200 for every/blog/<slug>/, including slugs that have never existed (soft 404 — the server answers 200 and serves a shell page). Acurlstatus check or a naive absence-check ("grep for the leaked bracket, count 0") passes identically for a live post and a slug nobody has ever typed — Comms found this 2026-08-04 after their own all-clear on The Airport Corrections turned out to have been unfalsifiable by the method used, right only by luck of pointing at a real page. Fetch the live URL and grep for a distinctive phrase from the post's own body — assert presence first, then check for whatever you're hoping is absent. Post pages are server-rendered (the prose is in the raw response), so this works; the blog index is client-rendered and returns a shell, a different problem. - ✅ Editorial calendar updated with at least one syndication URL (mediumURL or linkedinURL)
- ✅ Calendar status is
published(ordistributedif already cross-posted)
Then archive the draft and source image to keep docs/public/comms/drafts/ lean:
# 1. Move final draft to published/
mv docs/public/comms/drafts/{filename}.md docs/public/comms/drafts/published/
# 2. Move any superseded/intermediate versions to superseded/
# (look for draft-{slug}-v1.md, draft-{slug}-v2.md, {slug}-draft.md, etc.)
for f in docs/public/comms/drafts/draft-{slug}*.md docs/public/comms/drafts/{slug}-draft*.md; do
[ -f "$f" ] && mv "$f" docs/public/comms/drafts/superseded/
done
# 3. Move source image to images-archive/ (the webp is now in production)
mv docs/public/comms/drafts/{image}.png docs/public/comms/drafts/images-archive/
# (also try .jpg, .jpeg if .png doesn't exist)
# 4. Commit
git add docs/public/comms/drafts/
git commit -m "docs: archive {title} draft + image (published)"
git push origin HEAD:mainWhy this is the final step: Cleanup before verification risks losing the source if the publish fails. Cleanup after syndication confirms the post is live and the local source is no longer the canonical version.
For ships: Same procedure but published/ and superseded/ apply equally — the ship draft and any working versions get archived after the LinkedIn post is confirmed live.
Ship Posts
For category: ship posts, the workflow is the same except:
- URL prefix is
/shipping-news/{slug}(not/blog/{slug}) - Image is always
piper-ship.webp(no per-post image needed) - Ships may publish without blog-content.json entry (shows LinkedIn link fallback)
- LinkedIn is the syndication target (not Medium)
Website CSV Format (13 columns)
slug,hashId,title,chatDate,imageSlug,imageAlt,imageCaption,workDate,pubDate,category,cluster,featured,notesDo NOT confuse with the editorial calendar (18 columns). Different schemas.
Known Issues (as of v0.5)
- Captions: BlogPostContent doesn't render captions from post metadata for blog-first posts. Captions are stored in the CSV but not displayed. Tracked as a website display bug.
- Image sizing: Featured images may crop poorly depending on aspect ratio. Known design issue.
- Large file hook: Images over 500KB may be rejected by pre-commit. Always compress with
sips -Z 1200before committing.
Anti-Patterns to Avoid
| Don't Do This | Why | Do This Instead |
| Publish to Medium first | Blog should be canonical | Blog first, then syndicate |
| Use non-hex hashId | Regex extraction fails silently | Always use uuid.uuid4().hex[:12] |
| Edit medium-posts.json manually | Gets wiped by npm run build | Add data via blog-metadata.csv |
Use echo >> to append CSV rows | May corrupt CSV | Use Python csv writer |
| Skip field count verification | Silent column misalignment | Verify 18 fields (editorial) or 13 (website) |
| Forget trailing slash on canonical URL | Mismatch with site config | trailingSlash: true in next.config |
Quality Checklist
After publishing:
- Blog post accessible at
https://pipermorgan.ai/blog/{slug}/— content check, not status code (see Step 9's gate above; a status check passes unconditionally on this site's soft-404 behavior) - Featured image loads correctly
- Blog index shows post with thumbnail
- Editorial calendar updated (this repo) with syndication URL(s)
- Website repo committed and pushed
- GitHub Pages deploy completed
- Draft moved to
drafts/published/ - Source image moved to
drafts/images-archive/ - Any superseded drafts moved to
drafts/superseded/
Changelog gap, noted 2026-07-31: frontmatter read version: 0.20 while the notes below stop at v0.16 — versions 0.17-0.20 were bumped without entries. Not backfilled here; I don't know what they changed and inventing it would be worse than the gap.
v0.27 — Pre-flight 3: the category is checked against the pubDate's weekday (Docs' ask, 2026-11-07, cc Exec). "At Long Last, Beta" published as building on a Saturday because the row said building, and nothing compared the row to the slot table. The check reads SLOT_BY_WEEKDAY from Docs' validator rather than keeping a second table. Tested on five cases: the real 11-07 row (insight, pass); the same row reverted to building (STOP, rc 1); a missing title (STOP); and live Tue, Thu and Wed rows (pass).
v0.26 — --cluster is now optional, derived from --work-date against ERAS, and fails loud
rather than silently empty when it can't be derived (Web, e2baf72, #1905). Two posts (09-26,
09-27) had shipped with an empty cluster value because publish-post.js's prior default was a
silent '' — the same footgun shape as the --work-date default v0.17 fixed. Web backfilled both
rows and superseded a stale docstring note ("assigned during periodic manual review") that predated
Comms's 09-06 work proving the era mapping is purely mechanical. New subsection added right after
the --work-date mandatory section, documenting the flag is now safely omittable (unlike
--work-date) but can still be passed explicitly to override.
v0.25 — Pre-Step sync gains a mid-pipeline re-trigger. The sync rule previously read as a one-time gate ("run this before opening the draft"). 2026-09-19 near-miss on Assume It Was You: mid-publish, after the proofread pass and hashId generation, PM mentioned conversationally that both today's and tomorrow's drafts had been edited further since the initial sync. Re-fetching surfaced a real state change (calendar status drafted → ready-for-docs, tomorrow's title changed) that the pipeline was about to proceed without. Added an explicit note: any PM remark implying an edit, anywhere in the pipeline, re-triggers the sync — not just the start. (Frontmatter version bumped 0.24 → 0.25; no changelog entry exists for 0.24, consistent with the gap already noted below for 0.17-0.20.)
v0.23 — Confirmed: a publish resolves a pre-existing cached 404 on its own URL. Web's soft-404 fix
(03b77d9d, 2026-08-04) corrected unknown-slug behavior to a real 404 — but that 404 is itself cached
(x-vercel-cache: HIT), so a slug that 404'd before it was published stays a cached 404 until
something invalidates it. Comms flagged this as an open question the day the fix shipped: does
publishing a post invalidate the cache on its own URL, or does the pre-publish 404 persist and require
manual invalidation? Confirmed on "The List That Lies" (published 2026-08-04) and re-verified
2026-08-05: the v0.22 content-check passed clean at publish time and the URL still returns 200 with
correct content a day later. A publish is a rebuild, and the rebuild invalidates the stale 404 — no
manual cache-bust step needed. Nothing to change in the procedure; this closes the open question Comms
named rather than adding a new step.
v0.22 — Live-verification method specified: content check, not status code. Step 9's gate and the
Quality Checklist both said "post is live" / "accessible" with no method named — silently satisfiable by
a curl status check, which on pipermorgan.ai cannot fail: the site returns HTTP 200 for every
/blog/<slug>/, including slugs nobody has ever typed (soft 404, server answers 200 with a shell page).
Comms found this 2026-08-04 from inside their own Monday all-clear on The Airport Corrections — a
grep-for-0-occurrences absence-check that would have returned the identical clean result against an
unpublished or nonexistent slug, right only by luck of pointing at a real page. Fix: assert presence
first (grep a distinctive phrase from the post's own body against the live URL), then check for whatever
you hope is absent. Post pages are server-rendered so this works; the blog index is client-rendered and
returns a shell — a separate, unrelated limitation, not fixed here.
v0.21 — Two-copy diff made mandatory (Pre-flight 2). A draft commonly exists in both dev/active/{slug}.md and docs/public/comms/drafts/{slug}.md, and only the second one publishes. They diverge silently. On 2026-07-30 commit e91cb5466 added the Almost Beta image block to the dev/active/ copy ONLY; a publish would have dropped the image and reported success. Comms caught it by diffing — nothing in the pipeline would have. Chronic rather than one-off: Ship #052's draftPath also pointed at a file that wasn't there, and a 2026-07-12 pass repaired 22 stale paths without fixing the cause. Snippet behaviorally tested across four cases (identical / diverged / single copy / neither), including the real 07-30 shape where the addition sits in the copy that does NOT ship. Explicit guidance not to prefer the newer mtime — read the diff.
v0.16 — CSV validator extension. Step 6 verification updated to invoke scripts/validate-editorial-calendar.py as the canonical post-write check. The standalone validator parses the whole file via Python csv module, reports field-count drift + header mismatch with exit code 1, prints a clean-pass summary on exit 0. Inline single-row snippet preserved as alternative for targeted checks. Rationale: May 17 hand-edit incident introduced unescaped comma in altText (field count drifted to 19; should be 18); a wrapped standalone validator is easier to invoke + harder to skip than the inline python3 -c form. Future: pre-commit hook integration is a candidate enhancement (script is hook-ready — exit codes + stderr surface).
v0.15 — Pre-flight file-existence check codified. New "Pre-flight: verify files exist" subsection under Prerequisites. Before invoking publish-post.js (dry-run or real), verify both draft and image files resolve at their expected paths via ls. Catches "image still in ~/Downloads/" + "placeholder image name in frontmatter" + "wrong filename" before the script errors at image-prep step. Dry-run alone does not catch this — script reports "would prep image" without verifying existence. May 17 From Protocol to Infrastructure incident: image was in ~/Downloads/ when PM said "ready to publish"; pre-flight caught it cheaply. Future CLI enhancement candidate flagged in the May 17 feature-corpus memo: --check mode for full pre-mutation validation.
v0.14 — Template-first proofread discipline codified. New "Proofread Discipline (read these first — every time)" section between Draft Metadata Convention and Procedure. Names blog-post-template.md + xian-voice-tone-guide.md as the canonical references that should be opened on every proofread pass, not consulted from memory. Editorial-calendar workDate/endWorkDate field semantics also surfaced here (source-work-period, not drafting window — per template line 133). May 17 evidence: dateline-semantics drift on From Protocol to Infrastructure missed because proofread was anchored on memory pins; PM caught and asked the direct question that surfaced the gap. Cross-references the feedback_blog_template_and_voice_guide_canonical_for_proofreads memory pin.
v0.13 — Dry-run mandatory. New "Always dry-run first" subsection in the CLI invocation block: every real publish MUST be preceded by --dry-run with otherwise-identical flags. The dry-run preview catches failure modes the CLI doesn't warn on — empty frontmatter values passed through silently, Markdown features rendering unexpectedly (numbered lists → <p> + <br /> instead of <ol>/<li>; inline block-level HTML wrapped in <p>), slug/category mismatches, image path resolution. Rationale: May 17 dry-run on From Protocol to Infrastructure caught the numbered-list rendering gap before mutation; a non-dry-run path would have published with broken list markup and required edit-pass cleanup. The dry-run is ~5 sec and catches the failure modes that mutate-then-fix costs disproportionately more to recover from.
v0.12 — Filename convention codified. New "Filename Convention" section between Prerequisites and Draft Metadata Convention. Two filename patterns coexist in docs/public/comms/drafts/: {slug}.md is PM's working copy (canonical for publish); draft-{slug}.md is Comms's earlier draft (sometimes superseded, sometimes the only file). Codified the discipline: ls docs/public/comms/drafts/ | grep {keyword} before editing/publishing, to surface both and confirm which is canonical. May 17 incident cited as failure-mode evidence — proofread edits applied to draft-* while PM was working in the {slug}.md working copy; recommendations transferred by hand. Rule prevents wrong-file edits going forward.
v0.11 — Calendar discipline. Step 6 strengthened: /update-calendar skill is now mandatory for every editorial-calendar edit — never hand-edit editorial-calendar.csv. Rationale: hand-editing the calendar on 2026-05-17 (From Protocol to Infrastructure publish) produced unescaped-comma + field-count drift (19 fields when 18 expected; CSV parser caught + fix landed). The /update-calendar skill knows the 18-field column structure + escape rules + which field is which. Hand-editing has no upside and a clear failure mode. Added post-write verification snippet using Python's csv module (NOT awk-comma-split, which mis-counts on quoted fields). Rule applies to all calendar edits: publish-time, syndication follow-on, workDate corrections, status changes.
v0.10 — Script extraction. The mechanical first half of the skill (parse draft, extract metadata, generate hashId, convert markdown → HTML, prep image, append CSV row, write blog-content.json entry, sync + fetch) is now encoded as piper-morgan-website/scripts/publish-post.js. Added the script-invocation block at the top of the skill; preserved the full manual procedure below as the canonical reference for what the script does. Higher-judgment steps (voice-pass, syndication, footer-teaser selection, cross-post, calendar updates, drafts archival) remain skill-owned and unchanged. Rationale: encoding the mechanical pipeline as a single executable narrows the drift surface between docs and reality, reduces orchestration cost per publish, and gives agents a stable CLI surface (--report=json, --dry-run, kebab-case flags) for future automation integration. Validation: script's markdown converter reproduces the canonical inchworm-position blog-first content byte-for-byte. Web Designer commit 0179571a0 introduces the script.
v0.8 — Two changes: (1) Explicit blog-content.json schema. Every value MUST be a dict {"title": "...", "content": "<html>"} — not a bare HTML string. This applies to all categories (narrative, insight, ship); there is no per-category shape difference. Added a schema section and Python write snippet after Step 3's pipeline sketch. Rationale: in v0.7 the skill said only "add HTML to blog-content.json" with no shape spec, which led to an inconsistency on 2026-04-21 (Four Roles, Ninety Minutes was written as a bare string). The site renderer accepts both shapes, but mixing schemas is a latent bug for any downstream tooling. (2) Stop stripping non-metadata HTML comments. Previously, the conversion rule stripped every <!-- ... --> line from the body. Now the skill strips only the top-of-file metadata comments (image/alt/caption/no caption) that were consumed during metadata extraction, and preserves all other comments through to the output HTML. Comments are invisible in rendered pages but retain authorial hooks for future retroactive upgrades (inline-image support, canonical-reference annotations, etc.). Rationale: destroying authorial intent is needlessly lossy when the cost of preservation is zero.
v0.7 — Two changes: (1) YAML frontmatter added as preferred draft metadata format, HTML comments still supported for backward compatibility. Frontmatter is visible in Markdown editors while HTML comments are hidden. Skill accepts either format; frontmatter takes precedence if both present. Added frontmatter parsing snippet to Step 1 and extended strip-from-output to include the frontmatter block. (2) Heading convention updated: # section headings now convert to <h1> (previously <h2>), while ## subsections remain <h2>. This preserves the heading hierarchy when posts are syndicated to LinkedIn, which was previously collapsing both to the same visual size. Added Comms blog post template at docs/internal/planning/comms/blog-post-template.md.
v0.6 — Added Step 9 (drafts folder cleanup as final step after syndication confirmed). Cleanup includes: move final draft to published/, superseded versions to superseded/, source image to images-archive/. Rationale: cleanup before verification risks losing source if publish fails. Also documented heading convention: drafts use # for section headers (not ##) because LinkedIn renders ## as small. Conversion must strip only the FIRST H1 (title) and promote subsequent # and ## to <h2>.
v0.5 — Added draft metadata convention (comment block for image/alt/caption). Documented hashId must be valid hex. Noted npm run build regenerates medium-posts.json (critical). Added ship post workflow. Added trailing slash requirement for canonical URLs. Removed remote execution mode (unused). Streamlined procedure.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

