Companion Project Creator

Create complete, executable companion projects that readers can clone and run immediately.

Core Principle

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

A Laravel companion project is a full Laravel installation. A Node companion project is a full Node project. A document companion project is a complete, usable document.

⚠️ CRITICAL: Mandatory Verification

Every code companion project MUST be verified by actually running it before it is considered complete.

This is NOT optional. A companion project that hasn't been executed and tested is NOT complete.

Verification Workflow

┌─────────────────────────────────────────────────────────────────────────────┐ │ COMPANION PROJECT CREATION FLOW │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ 1. SCAFFOLD Create base project (composer/npm/etc) │ │ ↓ │ │ 2. CUSTOMIZE Add article-specific code │ │ ↓ │ │ 3. VERIFY ⭐ ACTUALLY RUN THE CODE │ │ │ │ │ ├── Install dependencies → Must succeed │ │ ├── Run application → Must start without errors │ │ └── Run tests → All tests must pass │ │ │ │ │ ├── ✅ All pass → Companion project complete │ │ └── ❌ Any fail → Fix code, return to step 3 │ │ │ └─────────────────────────────────────────────────────────────────────────────┘

Verification Commands by Type

Type Install Run Test

Laravel composer install

php artisan serve

php artisan test

Node.js npm install

npm start or node src/index.js

npm test

Python pip install -r requirements.txt

python src/main.py

pytest

React npm install

npm start

npm test

Vue npm install

npm run dev

npm test

Go go mod download

go run .

go test ./...

What "Verify" Means

You must actually execute these commands and confirm they succeed:

Example: Laravel verification

cd code

1. Install - MUST SUCCEED

composer install

✓ Check: No errors, vendor/ folder created

2. Setup - MUST SUCCEED

cp .env.example .env php artisan key:generate touch database/database.sqlite php artisan migrate

✓ Check: No errors, database has tables

3. Run - MUST START

php artisan serve &

✓ Check: Server starts on localhost:8000

✓ Check: Can access in browser (if web app)

Then stop the server

4. Test - ALL MUST PASS

php artisan test

✓ Check: "Tests: X passed" with 0 failures

If ANY step fails:

• Read the error message

• Fix the code

• Re-run verification from step 1

• Repeat until ALL steps pass

Verification Checklist

Before marking a companion project complete, confirm:

• install_command executed successfully (no errors)

• All dependencies installed (vendor/, node_modules/, etc. exists)

• run_command starts the application without errors

• Application is accessible (if web app, can load in browser)

• test_command executed successfully

• All tests pass (0 failures)

• No warnings that indicate missing functionality

DO NOT proceed to the next phase until all boxes are checked.

Companion Project Types

1. Code Companion Projects (code )

Complete application installations that can be:

• Cloned/copied

• Installed with one command

• Run immediately

• Tested

Laravel Application

Creation Process:

1. Create full Laravel project

cd content/articles/YYYY_MM_DD_slug/ composer create-project laravel/laravel code --prefer-dist

2. Configure for SQLite (no external DB)

cd code cp .env.example .env sed -i 's/DB_CONNECTION=mysql/DB_CONNECTION=sqlite/' .env touch database/database.sqlite php artisan key:generate

3. Install Pest

composer require pestphp/pest --dev --with-all-dependencies php artisan pest:install

4. Add article-specific code

- Models, Controllers, Routes, Views

- Migrations, Seeders

- Tests

5. VERIFY - Run migrations and tests

php artisan migrate php artisan test

⚠️ DO NOT CONTINUE IF TESTS FAIL

Required Files (auto-generated by Laravel):

code/ ├── app/ │ ├── Http/Controllers/ │ ├── Models/ │ └── Providers/ ├── bootstrap/ ├── config/ ├── database/ │ ├── migrations/ │ ├── seeders/ │ └── database.sqlite ├── public/ ├── resources/views/ ├── routes/ │ ├── web.php │ └── api.php ├── storage/ ├── tests/ │ ├── Feature/ │ └── Unit/ ├── .env ├── .env.example ├── artisan ├── composer.json ├── composer.lock ├── package.json ├── phpunit.xml └── README.md # Custom: explains the companion project

Article-Specific Additions:

• Custom models in app/Models/

• Custom controllers in app/Http/Controllers/

• Custom routes in routes/web.php or routes/api.php

• Custom views in resources/views/

• Custom migrations in database/migrations/

• Custom seeders in database/seeders/

• Feature tests in tests/Feature/

README.md Template:

Companion Project: [Article Topic]

Complete Laravel application demonstrating [concept].

Requirements

• PHP 8.2+
• Composer

Installation

```bash cd code composer install cp .env.example .env php artisan key:generate touch database/database.sqlite php artisan migrate --seed ```

Run the Application

```bash php artisan serve ```

Visit http://localhost:8000 to see the example.

Run Tests

```bash php artisan test ```

What This Demonstrates

1. [Concept 1] - See app/Models/Example.php
2. [Concept 2] - See app/Http/Controllers/ExampleController.php
3. [Concept 3] - See tests/Feature/ExampleTest.php

Key Files

Article Reference

This companion project accompanies: "[Article Title]"

Node.js Application

Creation Process:

1. Create project

cd content/articles/YYYY_MM_DD_slug/ mkdir code && cd code npm init -y

2. Install dependencies

npm install express npm install --save-dev jest

3. Configure package.json

Add scripts: "start", "test", "dev"

4. Add article-specific code

5. Run tests

npm test

Structure:

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

Python Application

Creation Process:

1. Create project

cd content/articles/YYYY_MM_DD_slug/ mkdir code && cd code python -m venv venv

2. Create requirements.txt

3. Add article-specific code

4. Add tests with pytest

Structure:

code/ ├── src/ │ └── main.py ├── tests/ │ └── test_main.py ├── requirements.txt ├── setup.py └── README.md

2. Document Companion Projects (document )

Complete, usable documents that readers can adapt.

Types:

• Project plans

• Technical specifications

• Process documents

• Meeting templates

• Report templates

Structure:

code/ ├── templates/ │ ├── project-plan-template.md │ └── sprint-planning-template.md ├── examples/ │ ├── project-plan-filled.md │ └── sprint-planning-filled.md └── README.md

Each template must be:

• Complete (all sections present)

• Well-commented (explain each section)

• Ready to use (just fill in the blanks)

3. Diagram Companion Projects (diagram )

Complete Mermaid diagrams that render correctly.

Structure:

code/ ├── diagrams/ │ ├── architecture.mermaid │ ├── sequence.mermaid │ └── flowchart.mermaid ├── rendered/ # Optional: PNG exports │ └── architecture.png └── README.md

Each diagram must:

• Be valid Mermaid syntax

• Include comments explaining components

• Render correctly in GitHub/VS Code

4. Configuration Companion Projects (config )

Complete, working configuration files.

Structure:

code/ ├── docker/ │ ├── Dockerfile │ ├── nginx.conf │ └── php.ini ├── docker-compose.yml ├── .env.example └── README.md

Must be:

• Complete (all required config present)

• Runnable (docker-compose up works)

• Well-commented

5. Script Companion Projects (script )

Complete, executable scripts.

Structure:

code/ ├── scripts/ │ ├── deploy.sh │ ├── backup.sh │ └── setup.sh ├── lib/ │ └── helpers.sh └── README.md

Must be:

• Executable (chmod +x )

• Include shebang (#!/bin/bash )

• Handle errors properly

• Include usage documentation

6. Data Companion Projects (dataset )

Complete datasets with schema.

Structure:

code/ ├── data/ │ ├── sample-data.json │ ├── sample-data.csv │ └── seed.sql ├── schemas/ │ └── schema.json └── README.md

7. Template Companion Projects (template )

Reusable file templates.

Structure:

code/ ├── templates/ │ ├── component.tsx.template │ ├── controller.php.template │ └── model.php.template ├── generated/ # Example outputs │ └── UserController.php └── README.md

8. Spreadsheet Companion Projects (spreadsheet )

Complete spreadsheets with formulas.

Structure:

code/ ├── spreadsheets/ │ ├── budget-tracker.xlsx │ └── project-timeline.xlsx ├── csv/ │ └── raw-data.csv └── README.md

Creation Workflow

Step 1: Determine Companion Project Type

Based on article content:

Article Topic Companion Project Type What to Create

Laravel feature code

Full Laravel app

API design code

Full API server

Architecture diagram

Mermaid diagrams

Project management document

Complete templates

DevOps config

Docker setup

Automation script

Executable scripts

Data analysis dataset

• code

Data + analysis code

Step 2: Create Base Project

For code companion projects, ALWAYS start with proper project scaffolding:

Laravel

composer create-project laravel/laravel code

Node.js

mkdir code && cd code && npm init -y

Python

mkdir code && cd code && python -m venv venv

React

npx create-react-app code

Vue

npm create vue@latest code

Step 3: Add Article-Specific Code

After base project exists:

• Add models/classes

• Add controllers/routes

• Add views/templates

• Add tests

• Add seeders/sample data

Step 4: Verify Completeness

Code Companion Projects Checklist:

• Can be cloned fresh

• composer install / npm install works

• Application starts without errors

• Can be accessed in browser (if web app)

• All tests pass

• README explains setup and usage

Document Companion Projects Checklist:

• All sections are complete

• Placeholders are clearly marked

• At least one filled example exists

• README explains how to use

Step 5: Document the Companion Project

Every companion project needs a README.md with:

• What it demonstrates

• Requirements

• Installation steps

• How to run

• How to test

• Key files explained

• Article reference

Integration with Article

Referencing Companion Project in Article

Setting Up the Project

Clone the example and install dependencies:

```bash cd code composer install cp .env.example .env php artisan key:generate ```

See the complete working companion project in the code/ folder.

Code Snippets from Companion Project

When showing code in the article, reference actual files:

Here's our Post model (code/app/Models/Post.php):

```php // From: code/app/Models/Post.php <?php

namespace App\Models;

class Post extends Model { // ... actual code from example } ```

Settings Integration

ALWAYS load settings before creating companion projects.

Step 1: Load Settings

View settings for your example type

bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/show.ts settings code

Or use article-stats.ts for programmatic access:

bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/article-stats.ts --json

Step 2: Get Values from Settings

// Database settings → companion_project_defaults.code { "technologies": ["Laravel 12", "Pest 4", "SQLite"], "scaffold_command": "composer create-project laravel/laravel code --prefer-dist", "post_scaffold": [ "cd code", "composer require pestphp/pest pestphp/pest-plugin-laravel --dev --with-all-dependencies", "php artisan pest:install", "sed -i 's/DB_CONNECTION=.*/DB_CONNECTION=sqlite/' .env", "touch database/database.sqlite" ], "run_command": "php artisan serve", "test_command": "php artisan test" }

Step 3: Merge with Article Overrides

If the article task has a companion_project field, those values override settings:

settings defaults + article.companion_project = final config ────────────────────── ──────────────── ──────────── scaffold_command: X scaffold_command: Y Y (article wins) technologies: [A, B] (not set) [A, B] (use default) has_tests: true has_tests: false false (article wins)

Step 4: Execute Commands

1. Run scaffold_command

composer create-project laravel/laravel code --prefer-dist

2. Run each post_scaffold command

cd code composer require pestphp/pest pestphp/pest-plugin-laravel --dev --with-all-dependencies php artisan pest:install

... etc

Step 5: Verify with test_command

From settings.companion_project_defaults.code.test_command

php artisan test

Global defaults from database settings:

{ "companion_project_defaults": { "code": { "technologies": ["Laravel 12", "Pest 4", "SQLite"], "scaffold_command": "composer create-project laravel/laravel code", "post_scaffold": [ "cd code", "composer require pestphp/pest --dev", "php artisan pest:install" ] } } }

Article can override:

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

Common Mistakes to Avoid

❌ Wrong: Partial Code

code/ ├── app/Models/Post.php # Just one file! └── README.md

✅ Correct: Complete Project

code/ ├── app/ # Full Laravel structure ├── bootstrap/ ├── config/ ├── database/ ├── public/ ├── resources/ ├── routes/ ├── storage/ ├── tests/ ├── .env.example ├── artisan ├── composer.json └── README.md

❌ Wrong: Untested Code

// Example that might not work class PostController { public function index() { return Post::all(); // Is Post even defined? } }

✅ Correct: Tested, Working Code

// Tested with: php artisan test class PostController extends Controller { public function index() { return Post::with('comments')->paginate(10); } }

// tests/Feature/PostTest.php exists and passes

Companion Project Task Recording

After creating companion project, update the article record in the database:

{ "companion_project": { "type": "code", "path": "code/", "description": "Complete Laravel app with rate limiting", "technologies": ["Laravel 12", "Pest 4", "SQLite"], "has_tests": true, "scaffold_command": "composer create-project laravel/laravel code", "files": [ "app/Http/Controllers/ApiController.php", "app/Http/Middleware/RateLimitMiddleware.php", "routes/api.php", "tests/Feature/RateLimitTest.php" ], "run_instructions": "composer install && php artisan serve", "test_command": "php artisan test", "verified": true, "verified_at": "2025-01-15T14:00:00Z" } }