crashtestdev/.amplifier/AGENTS.md

Crash Test Dev -- Agent Instructions

Standing Rules

Voice Linting Is Mandatory Before Publishing

Every piece of written content (blog posts, articles, lessons, patterns) MUST pass through the voice-check pipeline before it can be published. No exceptions.

Before creating or modifying any content in src/content/posts/:

1. Draft the content
2. Run mechanical lint: ./scripts/lint-voice.sh <file>
   • Must have 0 FAILURES to proceed
   • Warnings are acceptable but should be acknowledged
3. Run LLM judge: Delegate to self with model_role: "critique" using the voice-check prompt at .amplifier/skills/voice-check/SKILL.md
   • Evaluates 8 dimensions: em-dash addiction, conviction posture, evidence instinct, narrative engine match, structural parallelism, opening quality, ending quality, personality presence
   • Must reach PUBLISH or REVISE verdict (not REWRITE)
4. Fix all failures before committing
5. Re-run both checks after fixes to confirm

If the mechanical lint or LLM judge is skipped, the content is not published. This applies even if the user says "just publish it." Run the checks, report the results, and let the user decide whether to fix issues or publish anyway with full awareness of what's wrong.

What the Checks Catch

Mechanical lint (scripts/lint-voice.sh):

• Em-dash density (>5 per post = FAIL, Claude fingerprint)
• AI trigger words (delve, tapestry, nuanced, landscape, etc.)
• Hedging phrases ("it's worth noting", "one might argue")
• Unnecessary negative contrast ("doesn't just X. They Y" -- Claude crutch)
• Filler transitions ("in conclusion", "that being said")
• Resolution closers ("the key takeaway", "at the end of the day")
• Missing receipts (0 links + 0 code + 0 URLs in 500+ words = WARN)
• Sentence length uniformity (>70% same length = WARN)

LLM judge (voice-check skill):

• Voice match against .amplifier/VOICE.md profile
• Narrative engine (essay mode = AI default, enemy-narrative = Ken's default)
• Structural parallelism (too-clean bullet lists, tricolon patterns)
• Opening quality (problem/hook vs generic framing)
• Ending quality (restating intro = anti-pattern)
• Personality presence (humor, asides, self-awareness)

Voice Profile Reference

Ken's voice profile lives at .amplifier/VOICE.md. Key traits:

• Conviction: High, earned. States conclusions, doesn't hedge.
• Evidence: Receipt-shower. Links, code, data. Non-negotiable.
• Humor: Playful escalation + dry observation, sparse.
• Sentence rhythm: Short/long alternation, not uniform.
• Narrative: Enemy-narrative diagnostic is the default blog engine.
• Endings: End when done. Never restate the intro.

Em-Dash Budget

Ken's real writing uses 0-2 em-dashes per 1000 words. Claude defaults to 10-15 per 1000. The budget for this blog:

• 0-2 per post: Clean
• 3-5 per post: Acceptable, review each one
• 6+: FAIL. Kill at least half. Replace with periods, colons, or restructure.

When you find yourself typing an em-dash, stop and ask: would a period work here? It almost always does.

Project Context

• Site: Crash Test Dev (Astro blog at blog.ampbox.io / kenotron.github.io/crashtestdev)
• Author: Ken Chau (kenotron on GitHub, @kenneth_chau on Twitter)
• Content types: Posts (war stories), Patterns (reference), Lessons (progressive)
• Design system: DESIGN.md at project root (Google DESIGN.md spec-compliant)
• Aesthetic: "Workbench, not gallery" -- warm, grounded, un-digital
• Voice profile: .amplifier/VOICE.md
• Design specs: .design/AESTHETIC-GUIDE.md, .design/specs/

Content Pipeline

Idea / source material
  |
  v
Draft post (src/content/posts/slug.md)
  |
  v
Mechanical lint: ./scripts/lint-voice.sh <file>
  |
  v
LLM judge: voice-check (8 dimensions)
  |
  v
Fix failures, re-check
  |
  v
Rebuild preview: rebuild /tmp/blog-dist, serve on :4321
  |
  v
Visual check at blog.ampbox.io
  |
  v
Commit + push