article-writer

What this skill does

# 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:
```json
{
  "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:**

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

**Or read JSON and extract:**
```javascript
// 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

```bash
# 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:**

```bash
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

| Article Topic | Project Type | What to Create |
|---------------|--------------|----------------|
| Laravel/PHP code | `code` | **Full Laravel project** via composer create-project |
| JavaScript/Node | `node` | **Full Node project** via npm init |
| Python | `python` | **Full Python project** with venv |
| DevOps/Docker | `config` | Complete docker-compose setup |
| Architecture | `diagram` | Complete Mermaid diagrams |
| Project management | `document` | Complete templates + filled examples |

#### 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