Blog Copywriting (Spec-Driven)

Rewrite or create content with strict adherence to blog constitution and brand voice guidelines.

Usage

/blog-copywrite "topic-name"

Example:

/blog-copywrite "nodejs-tracing"

Note: Provide the sanitized topic name (same as article filename).

Prerequisites

Optional Files:

• .spec/blog.spec.json - Blog constitution (highly recommended)
• articles/[topic].md - Existing article to rewrite (optional)
• .specify/seo/[topic]-seo-brief.md - SEO structure (optional)

If no constitution exists: Agent will use generic professional tone.

What This Command Does

Delegates to the copywriter subagent for spec-driven content creation:

• Constitution-First: Loads and applies .spec/blog.spec.json requirements
• Tone Precision: Matches exact tone (expert/pédagogique/convivial/corporate)
• Voice Compliance: Enforces voice_do and avoids voice_dont
• Review Rules: Ensures must_have items and avoids must_avoid
• Quality Focus: Spec-perfect copy over marketing optimization

Time: 20-40 minutes Output: articles/[topic].md (overwrites existing with backup)

Difference from /blog-marketing

Feature	/blog-marketing	/blog-copywrite
Focus	Conversion & CTAs	Spec compliance
Voice	Engaging, persuasive	Constitution-driven
When to use	New articles	Rewrite for brand consistency
Constitution	Optional influence	Mandatory requirement
CTAs	2-3 strategic	Only if in spec
Tone freedom	High	Zero (follows spec exactly)

Use /blog-copywrite when:

• Existing content violates brand voice
• Need perfect spec compliance
• Building content library with consistent voice
• Rewriting AI-generated content to match brand

Use /blog-marketing when:

• Need conversion-focused content
• Want CTAs and social proof
• Creating new promotional articles

Instructions

Create a new subagent conversation with the copywriter agent.

Provide the following prompt:

You are creating spec-driven copy for a blog article.

**Topic**: $ARGUMENTS

**Your task**: Write (or rewrite) content that PERFECTLY matches blog constitution requirements.

Follow your Three-Phase Process:

1. **Constitution Deep-Load** (5-10 min):
   - Load .spec/blog.spec.json (if exists, otherwise use generic tone)
   - Extract: blog.name, blog.context, blog.objective, blog.tone, blog.languages
   - Internalize brand_rules.voice_do (guidelines to follow)
   - Internalize brand_rules.voice_dont (anti-patterns to avoid)
   - Load workflow.review_rules (must_have, must_avoid)

2. **Spec-Driven Content Creation** (20-40 min):
   - Apply tone exactly as specified:
     * expert → Technical, authoritative, assumes domain knowledge
     * pédagogique → Educational, patient, step-by-step
     * convivial → Friendly, conversational, relatable
     * corporate → Professional, business-focused, ROI-oriented

   - Check if article exists (articles/$ARGUMENTS.md):
     * If YES: Load structure, preserve data, rewrite for spec compliance
     * If NO: Load SEO brief (.specify/seo/$ARGUMENTS-seo-brief.md) for structure
     * If neither: Create logical structure based on topic

   - Write content following:
     * Every voice_do guideline applied
     * Zero voice_dont violations
     * All must_have items included
     * No must_avoid patterns

   - Backup existing article if rewriting:
     ```bash
     if [ -f "articles/$ARGUMENTS.md" ]; then
       cp "articles/$ARGUMENTS.md" "articles/$ARGUMENTS.backup-$(date +%Y%m%d-%H%M%S).md"
     fi
     ```

3. **Spec Compliance Validation** (10-15 min):
   - Generate validation script: /tmp/validate-voice-$$.sh
   - Check voice_dont violations (jargon, passive voice, vague claims)
   - Verify voice_do presence (guidelines applied)
   - Validate must_have items (summary, citations, insights)
   - Check must_avoid patterns (keyword stuffing, unsourced claims)
   - Calculate tone metrics (sentence length, technical terms, etc.)

**Output Location**: Save final article to `articles/$ARGUMENTS.md`

**Important**:
- Constitution is LAW - no creative liberty that violates specs
- If constitution missing, warn user and use professional tone
- Always backup before overwriting existing content
- Include spec compliance notes in frontmatter

Begin copywriting now.

Expected Output

After completion, verify that articles/[topic].md exists and contains:

✅ Perfect Tone Match:

• Expert: Technical precision, industry terminology
• Pédagogique: Step-by-step, explained jargon, simple language
• Convivial: Conversational, personal pronouns, relatable
• Corporate: Professional, business value, ROI focus

✅ Voice Compliance:

• All voice_do guidelines applied throughout
• Zero voice_dont violations
• Consistent brand voice from intro to conclusion

✅ Review Rules Met:

• All must_have items present (summary, citations, insights)
• No must_avoid patterns (keyword stuffing, vague claims)
• Meets minimum quality thresholds

✅ Spec Metadata (in frontmatter):

---
tone: "pédagogique"
spec_version: "1.0.0"
constitution_applied: true
---

When to Use This Command

Use /blog-copywrite when you need to:

• ✅ Rewrite off-brand content: Fix articles that don't match voice
• ✅ Enforce consistency: Make all articles follow same spec
• ✅ Convert AI content: Transform generic AI output to branded copy
• ✅ Create spec-perfect drafts: New articles with zero voice violations
• ✅ Audit compliance: Rewrite to pass quality validation

For marketing-focused content: Use /blog-marketing instead.

Constitution Required?

With Constitution (.spec/blog.spec.json):

✅ Exact tone matching
✅ Voice guidelines enforced
✅ Review rules validated
✅ Brand-perfect output

Without Constitution:

⚠️  Generic professional tone
⚠️  No brand voice enforcement
⚠️  Basic quality only
⚠️  Recommend running /blog-setup first

Best practice: Always create constitution first:

/blog-setup

Tone Examples

Expert Tone

Distributed consensus algorithms fundamentally trade latency for
consistency guarantees. Raft's leader-based approach simplifies
implementation complexity compared to Paxos, achieving similar
safety properties while maintaining comprehensible state machine
replication semantics.

Pédagogique Tone

Think of consensus algorithms as voting systems for computers. When
multiple servers need to agree on something, they use a "leader" to
coordinate. Raft makes this simpler than older methods like Paxos,
while keeping your data safe and consistent.

Convivial Tone

Here's the thing about getting computers to agree: it's like
herding cats. Consensus algorithms are your herding dog. Raft is
the friendly retriever that gets the job done without drama,
unlike Paxos which is more like a border collie—effective but
complicated!

Corporate Tone

Organizations requiring distributed system reliability must
implement robust consensus mechanisms. Raft provides enterprise-
grade consistency with reduced operational complexity compared to
traditional Paxos implementations, optimizing both infrastructure
costs and engineering productivity.

Quality Validation

After copywriting, validate quality:

/blog-optimize "topic-name"

This will check:

• Spec compliance
• Frontmatter correctness
• Markdown quality
• SEO elements

Fix any issues and re-run /blog-copywrite if needed.

Backup and Recovery

Copywriter automatically backs up existing articles:

# List backups
ls articles/*.backup-*

# Restore from backup
cp articles/topic.backup-20250112-143022.md articles/topic.md

# Clean old backups (keep last 3)
ls -t articles/*.backup-* | tail -n +4 | xargs rm

Tips

1. Constitution first: Create .spec/blog.spec.json before copywriting
2. Be specific with voice: Clear voice_do / voice_dont = better output
3. Test tone: Try each tone to find your brand's fit
4. Iterate gradually: Start generic, refine constitution, re-copywrite
5. Validate after: Always run /blog-optimize to check compliance

Troubleshooting

"No constitution found"

# Create constitution
/blog-setup

# Or copy example
mkdir -p .spec
cp examples/blog.spec.example.json .spec/blog.spec.json

# Then run copywriting
/blog-copywrite "topic-name"

"Tone doesn't match"

# Check constitution tone setting
cat .spec/blog.spec.json | grep '"tone"'

# Update if needed, then re-run
/blog-copywrite "topic-name"

"Voice violations"

# Review voice_dont guidelines
cat .spec/blog.spec.json | grep -A5 '"voice_dont"'

# Update guidelines if too strict
# Then re-run copywriting

Workflow Integration

Full Workflow with Copywriting

# 1. Setup (one-time)
/blog-setup

# 2. Research
/blog-research "topic"

# 3. SEO Brief
/blog-seo "topic"

# 4. Spec-Driven Copy (instead of marketing)
/blog-copywrite "topic"

# 5. Validate Quality
/blog-optimize "topic"

# 6. Publish

Rewrite Existing Content

# Fix off-brand article
/blog-copywrite "existing-topic"

# Validate compliance
/blog-optimize "existing-topic"

# Compare before/after
diff articles/existing-topic.backup-*.md articles/existing-topic.md

---

Ready to create spec-perfect copy? Provide the topic name and execute this command.