Article Writer

Article Writer

Create technical articles with companion projects and multi-language support.

Quick Start

1. Determine author (from task or default author in database) 2. Create folder structure (including code/ folder) 3. Load author profile from database 4. Load settings (including article_limits.max_words) 5. Follow phases: Initialize → Plan → Research → Draft → Companion Project → Integrate → Review → Condense → Translate → Finalize

Workflow Overview

Plan → Research → Draft (initial) → Create Companion Project → Update Draft → Review → Condense → Translate → Finalize
                         ↑                              ↓               ↓
                         └──────── Iterate ─────────────┘               │
                                                                        ↓
                                                            (if over max_words)

Folder Structure

content/articles/YYYY_MM_DD_slug/
├── 00_context/              # author_profile.json
├── 01_planning/             # classification.md, outline.md
├── 02_research/
│   ├── sources.json         # All researched sources
│   └── research_notes.md
├── 03_drafts/
│   ├── draft_v1.{lang}.md   # Initial draft
│   └── draft_v2.{lang}.md   # After companion project integration
├── 04_review/               # checklists
├── 05_assets/images/
├── code/                    # COMPANION PROJECT
│   ├── README.md            # How to run the companion project
│   ├── src/                 # Companion project source code/files
│   └── tests/               # Tests (if applicable)
├── {slug}.{primary_lang}.md # Primary article
└── {slug}.{other_lang}.md   # Translations

Phases

Phase 0: Initialize

• Get author, generate slug, create folder
• Create code/ directory for companion project
• Copy author profile to 00_context/
• Load `article_limits.max_words` from settings

Phase 1: Plan

• Classify article type
• Create outline
• Plan companion project type and scope
• CHECKPOINT: Get approval

Phase 2: Research (Web Search)

• Search official documentation
• Find recent news (< 1 year for technical)
• Record all sources

Phase 3: Draft (Initial)

• Write initial draft in primary language
• Mark places where example code will go: <!-- EXAMPLE: description -->
• Save as 03_drafts/draft_v1.{lang}.md

Applying Author Voice

Use ALL author profile data when writing:

1. Manual Profile Data

• tone.formality: 1=very casual, 10=very formal
• tone.opinionated: 1=always hedge, 10=strong opinions
• phrases.signature: Use naturally (don't overdo)
• phrases.avoid: Never use these
• vocabulary.use_freely: Assume reader knows these
• vocabulary.always_explain: Explain on first use

2. Voice Analysis Data (if present in voice_analysis)

• sentence_structure.avg_length: Target this sentence length
• sentence_structure.variety: Match style (short/moderate/long)
• communication_style: Reflect top traits in tone
• characteristic_expressions: Sprinkle these naturally
• sentence_starters: Use these patterns
• signature_vocabulary: Prefer these words

Example:

For author with:

{
  "tone": { "formality": 4, "opinionated": 7 },
  "voice_analysis": {
    "sentence_structure": { "avg_length": 14, "variety": "moderate" },
    "communication_style": [{ "trait": "enthusiasm", "percentage": 32 }],
    "characteristic_expressions": ["na prática", "o ponto é"],
    "sentence_starters": ["Então", "O interessante é"]
  }
}

Write with:

• Conversational but confident tone
• Medium sentences (~14 words)
• Enthusiastic energy
• Occasional "na prática" and "o ponto é"
• Some sentences starting with "Então" or "O interessante é"

Phase 4: Create Companion Project ⭐

Use Skill(companion-project-creator) for this phase

CRITICAL: Companion projects must be COMPLETE, RUNNABLE, and VERIFIED.

A Laravel companion project is a FULL Laravel installation. A Node companion project is a FULL Node project.

The companion project is NOT complete until you have actually run and tested it.

Step 1: Load Companion Project Defaults from Settings

Load settings from database first:

# View defaults for the companion project type
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings code

Or read JSON and extract:

// Settings are loaded from the database via show.ts or article-stats.ts
const codeDefaults = settings.companion_project_defaults.code;
// codeDefaults.scaffold_command
// codeDefaults.verification.install_command
// codeDefaults.verification.run_command
// codeDefaults.verification.test_command

Step 2: Merge with Article Overrides

If article task has companion_project field, those values override settings defaults.

Step 3: Execute Scaffold Command

# From settings.companion_project_defaults.code.scaffold_command
composer create-project laravel/laravel code --prefer-dist

Step 4: Add Article-Specific Code

Add your custom code on top of the scaffolded project:

• Models, Controllers, Routes
• Migrations, Seeders
• Tests

Never create partial projects with just a few files.

Step 5: VERIFY (Mandatory) ⚠️

You MUST actually run these commands and confirm they succeed:

cd code

# 1. Install dependencies - MUST SUCCEED
composer install
# ✓ Check: No errors, vendor/ directory exists

# 2. Setup - MUST SUCCEED
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate
# ✓ Check: No errors

# 3. Run application - MUST START
php artisan serve &
# ✓ Check: "Server running on http://127.0.0.1:8000"
# Stop the server after confirming

# 4. Run tests - ALL MUST PASS
php artisan test
# ✓ Check: "Tests: X passed" with 0 failures

If ANY step fails: 1. Read the error message 2. Fix the code 3. Re-run verification from step 1 4. Repeat until ALL steps pass

DO NOT proceed to Phase 5 until verification passes.

Companion Project Types

Verification Checklist

Before proceeding to Phase 5:

• [ ] Scaffold command executed successfully
• [ ] All article-specific code added
• [ ] install_command succeeded (vendor/node_modules exists)
• [ ] run_command starts application without errors
• [ ] test_command runs with 0 failures
• [ ] README.md explains setup and usage

For Code Companion Projects (Laravel)

code/
├── README.md              # Setup and run instructions
├── app/
│   └── ...                # Minimal app code
├── database/
│   ├── migrations/
│   └── seeders/
├── tests/
│   └── Feature/           # Pest tests for main features
├── composer.json
└── .env.example           # SQLite by default

Standards for Laravel companion projects:

• Use SQLite (no external DB needed)
• Use Pest for tests
• Include at least 2-3 tests for main features
• Add comments referencing article: // See article section: "Rate Limiting Basics"
• Keep dependencies minimal
• Include setup script if complex

For Document Companion Projects

code/
├── README.md              # What the documents demonstrate
├── templates/
│   └── ...                # Reusable templates
└── examples/
    └── ...                # Filled-in examples

Phase 5: Integrate Companion Project into Draft

• Replace <!-- EXAMPLE: --> markers with actual code snippets
• Add file references: "See code/app/Models/Post.php"
• Add run instructions in appropriate sections
• Save as 03_drafts/draft_v2.{lang}.md

Phase 6: Review (Comprehensive)

Review the article as a whole:

1. Explanation Flow

• Does the narrative flow logically?
• Are concepts introduced before being used?
• Does the companion project appear at the right time?

2. Companion Project Integration

• Do code snippets match the full companion project?
• Are file paths correct?
• Can readers follow along?

3. Voice Compliance

• Matches author's formality level?
• Uses signature phrases appropriately?
• Avoids forbidden phrases?
• Opinions expressed match author's positions?
• If voice_analysis present:
• Sentence length matches avg_length?
• Communication style traits reflected?
• Characteristic expressions used (not overused)?

4. Technical Accuracy

• Code snippets are correct?
• Companion project actually runs?
• Tests pass?

5. Completeness

• All outline points covered?
• Sources properly cited?
• Companion project fully demonstrates topic?

CHECKPOINT: Confirm article + companion project are ready

Phase 6b: Condense (Word Limit Enforcement) ⚠️

This phase is MANDATORY if article exceeds `max_words` from settings.

Step 1: Check Word Count

# Count words in article (excluding frontmatter and code blocks)
# Frontmatter: lines between first --- and second ---
# Code blocks: lines between ``` markers

# Simple word count of prose content only:
sed '/^---$/,/^---$/d; /^```/,/^```$/d' draft_v2.{lang}.md | wc -w

Step 2: Load Word Limit from Settings

# Read max_words from settings
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings
# Or read JSON directly:
# bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings

Step 3: Condense if Over Limit

If word count > max_words:

1. Identify Condensation Targets (in order of priority):

• Redundant explanations of the same concept
• Overly verbose transitions
• Repeated caveats or disclaimers
• Extended tangents not central to the topic
• Excessive examples when fewer would suffice

2. Condensation Techniques (preserve quality):

• Combine related paragraphs
• Replace lengthy explanations with concise summaries
• Convert verbose lists to compact bullet points
• Remove filler words and phrases
• Tighten sentence structure

3. CRITICAL: Preserve Author Voice

• Keep signature phrases and expressions
• Maintain the same tone (formality level)
• Preserve the author's opinion style
• Keep characteristic sentence structures
• Retain enthusiasm/energy level from voice profile

4. DO NOT Remove:

• Code examples or snippets (these don't count toward word limit)
• Critical technical explanations
• Prerequisites or setup instructions
• Safety warnings or important notes
• References to the companion project

Step 4: Verify Condensed Version

After condensing:

• [ ] Word count is now ≤ max_words
• [ ] Article still reads naturally (not choppy)
• [ ] All key points are preserved
• [ ] Technical accuracy maintained
• [ ] Author voice is consistent throughout
• [ ] Flow and narrative structure intact

Step 5: Save Condensed Draft

# Save as draft_v3 (condensed version)
# 03_drafts/draft_v3.{lang}.md

If unable to condense below max_words without quality loss:

• Document the reason in the task
• Note the final word count achieved
• Flag for human review

CHECKPOINT: Article is within word limit while maintaining quality

Phase 7: Translate

• Create versions for other languages
• Keep code snippets unchanged
• Translate comments in code if needed

Phase 8: Finalize

• Write final article with frontmatter
• Update database with:
• output_files
• sources_used
• companion_project info
• Verify companion project README is complete

When to Skip Companion Projects

Only skip if a companion project makes absolutely no sense:

• Pure opinion pieces with no actionable content
• News/announcement summaries
• Historical retrospectives
• Philosophical discussions

If skipping, document in task:

{
  "companion_project": {
    "skipped": true,
    "skip_reason": "Opinion piece with no actionable code or templates"
  }
}

Companion Project README Template

# Companion Project: [Topic]

Demonstrates [what this companion project shows] from the article "[Article Title]".

## Requirements

- PHP 8.2+
- Composer
- (any other requirements)

## Setup

\`\`\`bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
\`\`\`

## Run Tests

\`\`\`bash
php artisan test
\`\`\`

## Key Files

| File | Description |
|------|-------------|
| `app/Models/Post.php` | Demonstrates eager loading |
| `tests/Feature/QueryTest.php` | Tests N+1 detection |

## Article Reference

This companion project accompanies the article:
- **Title**: [Article Title]
- **Section**: See "Implementing Eager Loading" section

Companion Project Comments Style

<?php
// ===========================================
// ARTICLE: Rate Limiting in Laravel 11
// SECTION: Creating Custom Rate Limiters
// ===========================================

namespace App\Providers;

use Illuminate\Support\Facades\RateLimiter;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Custom rate limiter for API endpoints
        // See article section: "Dynamic Rate Limits"
        RateLimiter::for('api', function (Request $request) {
            return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
        });
    }
}

Recording Companion Project in Task

{
  "companion_project": {
    "type": "code",
    "path": "code/",
    "description": "Minimal Laravel app demonstrating rate limiting",
    "technologies": ["Laravel 11", "SQLite", "Pest 3"],
    "has_tests": true,
    "files": [
      "app/Providers/AppServiceProvider.php",
      "routes/api.php",
      "tests/Feature/RateLimitTest.php"
    ],
    "run_instructions": "composer install && php artisan test"
  }
}

References

• references/article-types.md
• references/companion-project-templates.md
• references/checklists.md
• references/frontmatter.md
• references/research-templates.md

{OPTION_A} vs {OPTION_B}: {CONTEXT}

{HOOK - Set up the decision the reader is facing}

{DISCLOSURE - State any biases or preferences upfront}

Quick Comparison

Evaluation Criteria

{Explain what criteria you're using and why these matter}

{OPTION_A}

Overview

{Brief introduction to the option}

Strengths

• {STRENGTH_1}: {Explanation}
• {STRENGTH_2}: {Explanation}

Weaknesses

• {WEAKNESS_1}: {Explanation}
• {WEAKNESS_2}: {Explanation}

Code Example

// Typical usage of Option A

{OPTION_B}

Overview

{Brief introduction to the option}

Strengths

• {STRENGTH_1}: {Explanation}
• {STRENGTH_2}: {Explanation}

Weaknesses

• {WEAKNESS_1}: {Explanation}
• {WEAKNESS_2}: {Explanation}

Code Example

// Typical usage of Option B

Head-to-Head: {CRITERION_1}

{Detailed comparison on this specific criterion}

Winner: {OPTION} - {Brief justification}

Head-to-Head: {CRITERION_2}

{Detailed comparison on this specific criterion}

Winner: {OPTION} - {Brief justification}

Head-to-Head: {CRITERION_3}

{Detailed comparison on this specific criterion}

Winner: {OPTION} - {Brief justification}

Recommendations

Choose {OPTION_A} if:

• {SCENARIO_1}
• {SCENARIO_2}
• {SCENARIO_3}

Choose {OPTION_B} if:

• {SCENARIO_1}
• {SCENARIO_2}
• {SCENARIO_3}

My Pick

{Your recommendation with context about when it applies}

Conclusion

{Summary of the comparison and final thoughts}

{Acknowledge that the "best" choice depends on specific needs}

{TITLE}

{HOOK - Pose a question or present a surprising fact that draws readers in}

{CONTEXT - Why this topic matters, what problem it solves, or why understanding it improves your work}

The Core Concept

{High-level explanation of the concept in simple terms}

Why It Matters

{Practical implications - how this affects real-world development}

How It Works

{Build the mental model progressively}

The Foundation

{Start with the basics that everything else builds on}

// Illustrative code example

Under the Hood

{Go deeper into the mechanics}

{Diagram or visualization if helpful}

The Details That Matter

{Important nuances, edge cases, or commonly misunderstood aspects}

Practical Applications

Use Case 1: {SCENARIO}

{How to apply this concept in a real situation}

// Practical example

Use Case 2: {SCENARIO}

{Another application}

Common Misconceptions

"{MISCONCEPTION_1}"

{Correction and explanation}

"{MISCONCEPTION_2}"

{Correction and explanation}

Performance Considerations

{If relevant - how this impacts performance, when to use/avoid}

Related Concepts

{Brief connections to related topics, with links if available}

• {RELATED_1}: {How it connects}
• {RELATED_2}: {How it connects}

Summary

{Recap the key mental model in 2-3 sentences}

The key insights from this deep-dive:

1. {INSIGHT_1} 2. {INSIGHT_2} 3. {INSIGHT_3}

Further Reading

• {RESOURCE_1}
• {RESOURCE_2}

{TITLE}

{HOOK - 1-2 sentences that immediately show value and hook the reader}

In this tutorial, you'll learn how to {MAIN_OUTCOME}. By the end, you'll be able to {SPECIFIC_CAPABILITY}.

Prerequisites

Before starting, make sure you have:

• {PREREQUISITE_1}
• {PREREQUISITE_2}
• {PREREQUISITE_3}

What We're Building

{Brief description of the end result, possibly with screenshot or code preview}

Step 1: {FIRST_STEP_TITLE}

{Explanation of what we're doing and why}

// {CODE_EXAMPLE}

{Explain what this code does}

Step 2: {SECOND_STEP_TITLE}

{Continue the pattern...}

Step 3: {THIRD_STEP_TITLE}

{Continue...}

Testing It Out

Let's verify everything works:

# {TEST_COMMAND}

You should see:

{EXPECTED_OUTPUT}

Troubleshooting

{COMMON_ISSUE_1}

{Solution}

{COMMON_ISSUE_2}

{Solution}

Next Steps

Now that you've {ACCOMPLISHED_GOAL}, you might want to:

• {NEXT_STEP_1}
• {NEXT_STEP_2}
• {NEXT_STEP_3}

Summary

In this tutorial, you learned how to {RECAP_MAIN_POINTS}. The key takeaways are:

1. {TAKEAWAY_1} 2. {TAKEAWAY_2} 3. {TAKEAWAY_3}

{CLOSING_CTA}

Article Types Reference

Tutorial

Reader goal: Accomplish a specific task Structure: 1. Prerequisites and setup 2. Step-by-step instructions with code 3. Verification/testing 4. Troubleshooting common issues

Tips:

• Lead with working code
• Show expected output at each step
• Include copy-paste ready snippets

Deep-Dive

Reader goal: Understand how/why something works Structure: 1. The concept and why it matters 2. Mental model / how it works 3. Under the hood details 4. Practical applications

Tips:

• Build understanding progressively
• Use diagrams and analogies
• Connect to familiar concepts

Problem/Solution

Reader goal: Fix an error or solve a problem Structure: 1. THE SOLUTION (immediately) 2. Why it works 3. Alternative approaches 4. Prevention tips

Tips:

• Put solution in first 100 words
• Include exact error messages for SEO
• Show before/after

Opinion/Strategy

Reader goal: Gain perspective on a decision Structure: 1. Clear position statement 2. Context and experience 3. Supporting evidence 4. Counterarguments addressed 5. Conclusion/recommendation

Tips:

• Establish credibility upfront
• Acknowledge tradeoffs
• Be direct about biases

Comparison

Reader goal: Make a decision between options Structure: 1. Criteria for comparison 2. Summary table 3. Detailed analysis per criterion 4. Recommendations by use case

Tips:

• Declare biases upfront
• Use consistent evaluation criteria
• Provide clear recommendations

Quick Tip

Reader goal: Learn one thing fast Structure: 1. The tip (2-3 sentences) 2. Code example 3. Why it works (brief)

Tips:

• Under 500 words
• One actionable takeaway
• Perfect for series

Review Checklists

Accuracy Checklist

# Accuracy Review

## Code
- [ ] All code blocks tested and working
- [ ] Output comments match actual output
- [ ] Versions specified and current
- [ ] No deprecated methods used
- [ ] Error handling included where appropriate

## Facts
- [ ] All claims have source attribution
- [ ] Statistics are current (< 2 years old)
- [ ] Version numbers verified
- [ ] Links are working
- [ ] No outdated information

## Technical Correctness
- [ ] Terminology used correctly
- [ ] No oversimplifications that mislead
- [ ] Edge cases mentioned
- [ ] Security implications noted if relevant

Readability Checklist

# Readability Review

## Structure
- [ ] Hook within first 150 words
- [ ] Clear H2 sections (scannable)
- [ ] Logical flow between sections
- [ ] Conclusion summarizes key points

## Paragraphs
- [ ] No paragraph exceeds 4 sentences
- [ ] One idea per paragraph
- [ ] Transition sentences between topics

## Language
- [ ] Technical terms explained on first use
- [ ] Consistent terminology throughout
- [ ] Active voice preferred
- [ ] No jargon without explanation

## Visual
- [ ] Code blocks properly formatted
- [ ] Lists used for 3+ items
- [ ] Tables for comparisons
- [ ] Images have alt text

Voice Checklist

# Voice Review

## Tone Match (Manual Profile)
- [ ] Formality level matches profile (1-10 scale)
- [ ] Opinion strength matches profile
- [ ] Consistent throughout article

## Vocabulary (Manual Profile)
- [ ] Uses "allowed" terms freely
- [ ] Explains terms marked "always explain"
- [ ] Avoids forbidden phrases

## Style (Manual Profile)
- [ ] Signature phrases used naturally
- [ ] No anti-pattern phrases
- [ ] Opinions stated confidently (if opinionated profile)
- [ ] Appropriate hedging (if neutral profile)

## Voice Analysis Data (if present)
- [ ] Sentence length matches avg_length (~X words)
- [ ] Sentence variety matches style (short/moderate/long)
- [ ] Top communication traits reflected in tone
- [ ] Characteristic expressions used (but not overused)
- [ ] Sentence starters used naturally
- [ ] Signature vocabulary words included
- [ ] Question frequency matches question_ratio

SEO Checklist

# SEO Review

## Title
- [ ] Under 60 characters
- [ ] Primary keyword included
- [ ] Compelling/clickable

## Meta Description
- [ ] 150-160 characters
- [ ] Includes primary keyword
- [ ] Clear value proposition

## Content
- [ ] Primary keyword in first paragraph
- [ ] Primary keyword in at least one H2
- [ ] Natural keyword density (not stuffed)
- [ ] Internal links to related content
- [ ] External links to authoritative sources

## Technical
- [ ] Proper heading hierarchy (H1 → H2 → H3)
- [ ] Alt text on all images
- [ ] URL slug is clean and keyword-rich

Example Checklist

# Example Review

## Completeness (CRITICAL)
- [ ] Example is a FULL project (not snippets)
- [ ] For code: Created via scaffold command (composer create-project, etc.)
- [ ] Example runs without errors
- [ ] README.md explains setup and usage completely
- [ ] All dependencies listed in package file

## Verification (REQUIRED)
- [ ] Fresh clone test: Can be cloned and installed fresh
- [ ] Dependencies install without errors (composer install / npm install)
- [ ] Application starts (php artisan serve / npm start)
- [ ] Can be accessed in browser at documented URL
- [ ] All tests pass (php artisan test / npm test)
- [ ] Marked as verified=true in the article record

## Quality
- [ ] Well-commented (references article sections)
- [ ] Follows coding standards
- [ ] Uses SQLite for database (no external DB needed)
- [ ] Tests cover main concepts (Pest for PHP)
- [ ] Only article-specific code added to scaffolded project

## Integration
- [ ] Code snippets in article match example files exactly
- [ ] File paths in article are correct
- [ ] Run instructions are accurate and complete
- [ ] Example demonstrates all key concepts from article

## Documentation
- [ ] README has complete setup instructions
- [ ] README lists all requirements
- [ ] Key files are documented with their purpose
- [ ] Article sections referenced in code comments
- [ ] Example purpose is clear

Final Review

# Final Review

| Category | Status | Notes |
|----------|--------|-------|
| Accuracy | [ ] | |
| Readability | [ ] | |
| Voice | [ ] | |
| Example | [ ] | |
| SEO | [ ] | |

## Flow Review
- [ ] Narrative flows logically
- [ ] Concepts introduced before use
- [ ] Example appears at the right time
- [ ] Transitions are smooth

## Example Integration
- [ ] Code snippets match example files
- [ ] Example tests pass
- [ ] Run instructions work
- [ ] Example is referenced throughout article

## Pre-Publication
- [ ] Spell check completed
- [ ] Grammar check completed
- [ ] Read aloud for flow
- [ ] Mobile preview checked
- [ ] All images optimized

## Ready for Publication
- [ ] All checklists passed
- [ ] Example runs correctly
- [ ] Author reviewed final draft
- [ ] Scheduled/published

Companion Project Templates

See `skills/companion-project-creator/SKILL.md` for complete instructions on creating companion projects.

Core Principle

Companion projects must be COMPLETE and RUNNABLE, not snippets or partial code.

Global Companion Project Defaults

Defaults are stored in the database settings table. Article values override defaults.

Code Companion Project Defaults

{
  "code": {
    "technologies": ["Laravel 12", "Pest 4", "SQLite"],
    "scaffold_command": "composer create-project laravel/laravel code --prefer-dist",
    "has_tests": true,
    "run_command": "php artisan serve",
    "test_command": "php artisan test"
  }
}

Article Override

{
  "companion_project": {
    "type": "code",
    "technologies": ["Laravel 11", "MySQL"],
    "scaffold_command": "composer create-project laravel/laravel:^11.0 code"
  }
}

Companion Project Types Quick Reference

Laravel Companion Project (Full Installation)

For Laravel-related articles, create a minimal companion project:

code/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── ExampleController.php
│   ├── Models/
│   │   └── Example.php
│   └── Providers/
│       └── AppServiceProvider.php
├── database/
│   ├── migrations/
│   │   └── 2025_01_15_000000_create_examples_table.php
│   └── seeders/
│       └── ExampleSeeder.php
├── routes/
│   ├── api.php
│   └── web.php
├── tests/
│   └── Feature/
│       └── ExampleTest.php
├── .env.example
├── composer.json
└── README.md

composer.json (Minimal)

{
    "name": "example/article-demo",
    "type": "project",
    "require": {
        "php": "^8.2",
        "laravel/framework": "^11.0"
    },
    "require-dev": {
        "pestphp/pest": "^3.0",
        "pestphp/pest-plugin-laravel": "^3.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        }
    },
    "scripts": {
        "test": "pest"
    }
}

.env.example (SQLite)

APP_NAME="Article Example"
APP_ENV=local
APP_KEY=
APP_DEBUG=true

DB_CONNECTION=sqlite
DB_DATABASE=database/database.sqlite

Pest Test Template

<?php
// tests/Feature/ExampleTest.php
// ARTICLE: [Article Title]
// SECTION: [Relevant Section]

use App\Models\Example;

describe('Example Feature', function () {
    
    beforeEach(function () {
        // Setup for each test
    });

    it('demonstrates the main concept', function () {
        // Arrange
        $example = Example::factory()->create();
        
        // Act
        $result = $example->someMethod();
        
        // Assert
        expect($result)->toBeTrue();
    });

    it('handles edge case', function () {
        // Test edge case mentioned in article
    });

    it('shows error handling', function () {
        // Test error scenario
    });
});

Node.js Companion Project (Minimal)

code/
├── src/
│   └── index.js
├── tests/
│   └── example.test.js
├── package.json
└── README.md

package.json

{
  "name": "article-example",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "test": "node --test tests/"
  },
  "devDependencies": {}
}

Docker/DevOps Companion Project

code/
├── docker/
│   ├── Dockerfile
│   └── nginx.conf
├── docker-compose.yml
├── scripts/
│   ├── setup.sh
│   └── deploy.sh
└── README.md

docker-compose.yml Template

# ARTICLE: [Article Title]
# Demonstrates: [What this shows]

services:
  app:
    build:
      context: .
      dockerfile: docker/Dockerfile
    ports:
      - "8080:80"
    volumes:
      - ./src:/var/www/html
    # See article section: "[Section Name]"

Document/Template Companion Project

For non-code articles:

code/
├── templates/
│   ├── template-1.md
│   └── template-2.md
├── examples/
│   ├── filled-example-1.md
│   └── filled-example-2.md
└── README.md

Project Plan Template

# Project Plan: [Project Name]

<!-- ARTICLE: [Article Title] -->
<!-- This template demonstrates concepts from the article -->

## 1. Project Overview

**Objective**: [Clear statement of what the project achieves]

**Scope**: 
- In scope: [Items]
- Out of scope: [Items]

## 2. Timeline

| Phase | Duration | Deliverables |
|-------|----------|--------------|
| Planning | 1 week | Requirements doc |
| Development | 4 weeks | MVP |
| Testing | 1 week | Test report |

## 3. Resources

[Resource allocation as discussed in article section X]

## 4. Risks

| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk 1] | High | [Mitigation] |

README Template for Companion Projects

# Companion Project: [Topic Name]

> Demonstrates [concept] from the article "[Article Title]"

## What This Shows

- [Key concept 1]
- [Key concept 2]
- [Key concept 3]

## Requirements

- [Requirement 1]
- [Requirement 2]

## Quick Start

\`\`\`bash
# Install dependencies
composer install  # or npm install

# Setup
cp .env.example .env
php artisan key:generate

# Run migrations (SQLite)
touch database/database.sqlite
php artisan migrate --seed

# Run tests
php artisan test
\`\`\`

## Project Structure

| File/Folder | Purpose |
|-------------|---------|
| `app/Models/` | Eloquent models demonstrating [concept] |
| `tests/Feature/` | Tests covering [scenarios] |

## Key Code Sections

### [Concept 1]

See `app/Services/ExampleService.php`:
- Lines 10-25: [What it shows]

### [Concept 2]

See `app/Http/Controllers/ExampleController.php`:
- Lines 30-45: [What it shows]

## Running the Companion Project

\`\`\`bash
# Start the server
php artisan serve

# In another terminal, test the endpoint
curl http://localhost:8000/api/example
\`\`\`

## Tests

The companion project includes [N] tests:

1. `tests/Feature/ExampleTest.php`
   - `it demonstrates the main concept` - [What it tests]
   - `it handles errors gracefully` - [What it tests]

## Article Reference

This companion project accompanies:
- **Article**: [Title]
- **Author**: [Author Name]
- **Main Sections**: [List relevant sections]

Comment Styles

PHP/Laravel

<?php
// ===========================================
// ARTICLE: [Article Title]
// SECTION: [Section Name]
// ===========================================

/**
 * Demonstrates [concept].
 * 
 * See article section "[Section Name]" for full explanation.
 */
class ExampleClass
{
    // This implements the pattern discussed in "Pattern Overview"
    public function exampleMethod(): void
    {
        // Step 1: [Brief description]
        // (See article for detailed explanation)
    }
}

JavaScript

/**
 * ARTICLE: [Article Title]
 * SECTION: [Section Name]
 * 
 * Demonstrates [concept] as explained in the article.
 */

// See article section: "Implementation Details"
function exampleFunction() {
    // Implementation following article guidelines
}

YAML/Config

# ===========================================
# ARTICLE: [Article Title]
# SECTION: [Section Name]
# ===========================================

# This configuration demonstrates [concept]
# See article for full explanation of each option

setting:
  option: value  # Explained in "Configuration Options" section

Checklist for Companion Projects

Before finalizing:

• [ ] Companion project is minimal (no unnecessary code)
• [ ] Companion project is complete (runs without errors)
• [ ] Companion project uses SQLite (for database projects)
• [ ] Companion project includes tests (Pest for PHP)
• [ ] Comments reference article sections
• [ ] README explains how to run
• [ ] Key files are documented
• [ ] Companion project matches code snippets in article

Frontmatter Reference

Standard Article Frontmatter

---
title: "Article Title Here"
slug: "article-title-here"
description: "A 150-160 character meta description for SEO"
author: "mwguerra"
author_name: "MW Guerra"
language: "pt_BR"
translations:
  - lang: "en_US"
    path: "./article-title-here.en_US.md"
date: "2025-01-15"
updated: "2025-01-15"
category: "Laravel"
tags:
  - laravel
  - php
  - rate-limiting
difficulty: "Intermediate"
estimated_reading_time: "8 min"
series:
  name: "Laravel Security Series"
  part: 2
  total: 5
prerequisites:
  - "Basic Laravel knowledge"
  - "Understanding of middleware"
versions:
  php: "8.2+"
  laravel: "11.x"
featured_image: "/images/articles/rate-limiting-hero.jpg"
canonical_url: "https://example.com/articles/rate-limiting"
---

Field Descriptions

Categories (from schema)

• Architecture
• Backend
• Business
• Database
• DevOps
• Files
• Frontend
• Full-stack
• JavaScript
• Laravel
• Native Apps
• Notifications
• Performance
• PHP
• Quality
• Security
• Soft Skills
• Testing
• Tools
• AI/ML

Difficulty Levels

Series Frontmatter

For articles in a series:

series:
  name: "Building a SaaS with Laravel"
  slug: "laravel-saas-series"
  part: 3
  total: 10
  prev_slug: "part-2-authentication"
  next_slug: "part-4-billing"

Minimal Frontmatter

For quick posts:

---
title: "Quick Tip: Laravel Collection Macro"
slug: "laravel-collection-macro-tip"
description: "Add custom methods to Laravel collections easily"
author: "mwguerra"
author_name: "MW Guerra"
language: "pt_BR"
date: "2025-01-15"
category: "Laravel"
tags: [laravel, collections, tips]
difficulty: "Intermediate"
---

Translation Frontmatter

For translated versions, reference the original:

---
title: "Quick Tip: Laravel Collection Macro"
slug: "laravel-collection-macro-tip"
description: "Add custom methods to Laravel collections easily"
author: "mwguerra"
author_name: "MW Guerra"
language: "en_US"
original:
  lang: "pt_BR"
  path: "./laravel-collection-macro-tip.pt_BR.md"
date: "2025-01-15"
category: "Laravel"
tags: [laravel, collections, tips]
difficulty: "Intermediate"
---

Research Templates

sources.json (Primary Format)

{
  "researched_at": "2025-01-15T10:00:00Z",
  "topic": "Rate Limiting in Laravel 11",
  "search_queries": [
    "Laravel 11 rate limiting documentation",
    "Laravel rate limiter best practices 2024",
    "Laravel throttle middleware configuration"
  ],
  "sources": [
    {
      "url": "https://laravel.com/docs/11.x/rate-limiting",
      "title": "Rate Limiting - Laravel 11.x Documentation",
      "summary": "Official documentation covering RateLimiter facade, defining rate limiters in AppServiceProvider, and applying via middleware",
      "usage": "Primary reference for syntax, configuration options, and official best practices",
      "accessed_at": "2025-01-15T10:15:00Z",
      "type": "documentation",
      "credibility": 5
    },
    {
      "url": "https://laravel-news.com/laravel-11-rate-limiting",
      "title": "What's New in Rate Limiting for Laravel 11",
      "summary": "Article covering changes and improvements to rate limiting in Laravel 11",
      "usage": "Used for section on new features and migration notes from Laravel 10",
      "accessed_at": "2025-01-15T10:30:00Z",
      "type": "news",
      "credibility": 4
    },
    {
      "url": "https://github.com/laravel/framework/blob/11.x/src/Illuminate/Cache/RateLimiter.php",
      "title": "Laravel RateLimiter Source Code",
      "summary": "Actual implementation showing token bucket algorithm",
      "usage": "Referenced to explain how rate limiting works under the hood",
      "accessed_at": "2025-01-15T10:45:00Z",
      "type": "repository",
      "credibility": 5
    }
  ]
}

Source Types

Credibility Scale

sources.md (Alternative Markdown Format)

# Sources

## Primary Sources (Credibility 5/5)
| ID | Title | URL | Key Info | Accessed |
|----|-------|-----|----------|----------|
| P1 | Laravel Docs - Rate Limiting | https://... | Official implementation | 2025-01-15 |

## Secondary Sources (Credibility 3-4/5)
| ID | Title | URL | Key Info | Accessed |
|----|-------|-----|----------|----------|
| S1 | Laravel News Article | https://... | New features in v11 | 2025-01-15 |

## How Each Source Was Used
- **P1**: Primary reference for all code examples and configuration
- **S1**: Background on version changes, migration tips

research_notes.md

# Research Notes

## Session 1: 2025-01-15

**Focus:** Rate limiting implementation in Laravel 11

**Web Searches Performed:**
1. "Laravel 11 rate limiting documentation" 
   → Found official docs, comprehensive coverage
2. "Laravel rate limiting best practices 2024"
   → Found several tutorials, one from Laravel News
3. "Laravel throttle vs rate limiter difference"
   → Clarified that throttle middleware uses RateLimiter

**Key Findings:**
1. RateLimiter facade is the primary API (Source: P1)
2. Token bucket algorithm used internally (Source: GitHub)
3. New `perMinute()` helper in Laravel 11 (Source: S1)

**Used In Article:**
- Intro: General concept from P1
- Configuration section: Code from P1
- Best practices: Recommendations from S1
- Under the hood: Implementation from GitHub

**Questions Resolved:**
- ✅ Does Laravel 11 change rate limiting? Yes, minor API improvements
- ✅ Default rate limit? 60/minute for API routes

fact_verification.md

# Fact Verification

| Claim | Source | Verified | Notes |
|-------|--------|----------|-------|
| Laravel 11 requires PHP 8.2+ | P1 | ✅ | Confirmed in docs |
| Rate limiter uses token bucket | GitHub | ✅ | Verified in source |
| 60 requests/minute is default | P1 | ✅ | For API routes |

## Claims From Web Research
- [x] "New perMinute() helper" - Verified in Laravel News + tested
- [x] "Supports Redis and database" - Confirmed in docs
- [ ] "Performance improved 20%" - Cannot verify, removed claim

code_samples/README.md

# Code Samples

## Tested Environment
- PHP: 8.2.x
- Laravel: 11.x
- Cache: Redis (for rate limiting tests)

## Files
- `basic-limiter.php` - Basic rate limiting setup
- `custom-limiter.php` - Custom limiter with dynamic limits
- `test-results.md` - Output from running examples

## Source Attribution
- `basic-limiter.php` based on: Laravel Docs (P1)
- `custom-limiter.php` adapted from: Laravel News example (S1)