companion-project-creator

What this skill does

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

```bash
# 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:**
1. Read the error message
2. Fix the code
3. Re-run verification from step 1
4. 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:**

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

| File | Description |
|------|-------------|
| `app/Models/Post.php` | Demonstrates [concept] |
| `routes/web.php` | Routes for [feature] |
| `tests/Feature/PostTest.php` | Tests for [feature] |

## Article Reference

This companion project accompanies: "[Article Title]"
```

#### Node.js Application

**Creation Process:**

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

```bash
# 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
│   └── spr