project-spinup

Generate a complete, ready-to-code project foundation tailored to development workflow, infrastructure, and chosen tech stack. Creates comprehensive claude.md for AI assistant context, Docker configuration, directory structure, and either guided learning prompts or full scaffolding. Complete project foundation including: - claude.md (comprehensive project context) - docker-compose.yml (local development) - Directory structure (src/, tests/, docs/) - .env.example, .gitignore, README.md - Guided setup prompts OR full scaffolding - .docs/project-foundation-complete.md (handoff marker)

---

Check for handoff documents and gather missing information conversationally. - .docs/PROJECT-MODE.md (workflow mode declaration) - .docs/brief-*.md (project brief) - .docs/tech-stack-decision.md (technology stack selection) - .docs/deployment-strategy.md (deployment strategy) 1. Scan .docs/ for expected handoff documents 2. If found: Load context and summarize conversationally 3. If missing: Gather equivalent information through questions 4. Proceed with skill workflow regardless "I can see you've completed all prerequisite phases. You're in {MODE} mode, with {tech-stack} selected for deployment on {hosting-approach}.

Ready to generate your project foundation?"

Then proceed with the skill's main workflow.

"I don't see all the expected handoff documents. No problem - let me gather what I need.

To generate your project foundation, I need to understand:

1. What's your project name? (kebab-case preferred)
2. What's your tech stack? (Frontend, backend, database)
3. Where will this deploy? (Localhost, VPS, cloud platform)
4. Learning or delivery focus? (Affects scaffolding approach)

Once you share these, I can generate your project foundation."

Gather answers conversationally, then proceed with the skill's main workflow.

This skill NEVER blocks on missing prerequisites. It gathers information conversationally and proceeds. For the project scaffolding, would you prefer:

1. Guided Setup - I'll create the foundation, then provide step-by-step prompts
   to build out the structure incrementally. You'll learn how each layer works.
   (Recommended if you're new to {tech stack})

2. Quick Start - I'll generate the complete project scaffolding immediately
   with all boilerplate code and configuration.
   (Recommended if you're familiar with {tech stack})

Which approach would you like?

- PROJECT-MODE (LEARNING/BALANCED/DELIVERY): Governs advisory skills - exploration, discussion, checkpoints. Strategic learning. - spinup_approach (Guided/Quick Start): Governs scaffolding style - step-by-step or all-at-once. Tactical implementation.

Key insight: You can be in LEARNING mode but use Quick Start if familiar with the stack. Or DELIVERY mode but use Guided Setup for a new framework.

Confirm any missing inputs. 1. project_name (kebab-case) 2. project_description 3. tech_stack (from tech-stack-decision.md or conversation) 4. hosting_plan (from deployment-strategy.md or conversation) 5. complexity_level (simple/standard/complex) 6. spinup_approach (guided/quick-start) 7. special_features (optional) Create foundation files regardless of spinup approach. 1. claude.md - Comprehensive project context 2. docker-compose.yml - Local development environment 3. Directory structure - src/, tests/, docs/ 4. .gitignore - Tech-stack-appropriate 5. README.md - Setup and development instructions 6. .env.example - Required environment variables 7. Git initialization guidance 8. .docs/project-foundation-complete.md - Handoff marker Generate foundation only, plus detailed "Next Steps" section in claude.md with: - Step-by-step prompts to give Claude Code - Explanation of what each step creates - Learning objectives for each step - Verification checkpoints - Estimated time for each step

User incrementally asks Claude Code to build out the project.

Generate complete scaffolding including: - All tech-stack-specific configuration files - Complete source file structure - Starter/example code with comments - Sample tests - All middleware/utilities - Initial git commit prepared Create .docs/project-foundation-complete.md handoff marker.

.docs/project-foundation-complete.md

# Project Foundation Complete

Project: {project_name}
Created: {date}
Tech Stack: {tech_stack_summary}
Deployment Target: {hosting_approach}
Spinup Approach: {guided/quick-start}

What Was Created

• claude.md (project context)
• docker-compose.yml (local development)
• Directory structure
• Configuration files
• README.md

Workflow Status

This marks the completion of the PLANNING and SETUP phases.

[If Localhost:]
WORKFLOW TERMINATION POINT
Your localhost project is ready for development.
No further workflow phases needed.

[If Public Deployment:]
Next Phases Available:

• Phase 4: test-orchestrator (optional, when ready for testing infrastructure)
• Phase 5: deploy-guide (when ready to deploy)
• Phase 6: ci-cd-implement (optional, for automation)

Summarize what was created and provide clear next steps based on deployment target. - What was created - How to start working - How to run development environment - Where to find documentation - Workflow status with termination point guidance - Git initialization commands

---

- Name: John - Experience: Hobbyist developer, beginner-to-intermediate - Learning Goal: Deep understanding of full-stack, professional practices - Reliance: Heavy use of Claude Code for implementation - Computers: MacBook Pro and Mac Mini - Sync: iCloud, portable SSDs, GitHub - IDE: VS Code with relevant extensions - Git: main + dev branches, conventional commits - Package Manager: Best for project - Linting: Best for project - Directory: src/, docs/, tests/ - Hostinger VPS8: 8 cores, 32GB RAM, 400GB storage - Supabase (self-hosted), PocketBase, n8n, Ollama, Wiki.js, Caddy - All in Docker containers - File Storage: Backblaze B2 - DNS: Cloudflare - VPS Access: SSH as user "john" - Deployment Options: Localhost, Shared Hosting, Cloudflare Pages, Fly.io, VPS Docker - Feature implementation - Debugging and troubleshooting - Refactoring - Testing (unit, integration, E2E) - Deployment setup - Performance optimization - Security implementation - Security: OWASP awareness - Testing: Framework-appropriate - Code Style: Framework/language best practices - Commits: Conventional commits format

---

# {PROJECT_NAME}

{PROJECT_DESCRIPTION}

Status: Active Development | Developer: John | Philosophy: Learning-Focused, Best Practices

---

Developer Profile

{Experience level, learning goals, development approach, common tasks for Claude Code}

---

Project Overview

{What project does, tech stack breakdown, architecture decisions}

---

Development Environment

{Computers/sync, local setup, prerequisites, first-time setup commands}

---

Infrastructure & Hosting

{Self-hosted infrastructure available, project-specific hosting, access/credentials}

---

Development Workflow

{Git branching strategy, commit convention, development cycle, testing strategy}

---

Code Conventions

{File organization, naming conventions, code style/linting}

---

Common Commands

{Development, database, Docker commands}

---

Project-Specific Notes

{Authentication, database schema, API endpoints, environment variables}

---

Deployment

{Deployment workflow, checklist, rollback procedure}

---

Resources & References

{Project docs, external resources, learning resources}

---

Troubleshooting

{Common issues and solutions}

---

Next Steps

{If Guided Setup: detailed step-by-step prompts}
{If Quick Start: immediate next actions}

---

## Next Steps (Guided Setup)

You now have the project foundation. Complete the setup by asking Claude Code to build out the structure step-by-step.

Learning Philosophy

Each step teaches about a specific part of the stack. Take your time, review what gets created, ask questions about why things are structured this way.

Estimated total time: {X hours}

---

Step 1: Initialize {Framework} Structure

Time: ~{X} minutes | Learning: Project structure and configuration

What you'll learn: How {framework} projects are organized, what each config file does.

Say to Claude Code:

Set up the {Framework} structure with {specifics} as specified in claude.md. Please explain the purpose of each major file and directory.

What will be created: {list}

Verification: {command}

---

Step 2: Configure Database Connection

Time: ~{X} minutes | Learning: Database configuration and connection patterns

Say to Claude Code:

Set up the database client configuration for {database} with environment variables as specified in claude.md.

---

Step 3: Implement Authentication Scaffolding

Time: ~{X} minutes | Learning: Authentication patterns, security

Say to Claude Code:

Implement authentication using {auth approach} as specified in claude.md. Include registration, login, logout, and protected route examples.

---

Step 4: Create Example CRUD Feature

Time: ~{X} minutes | Learning: Full-stack data flow, API design

Say to Claude Code:

Create a simple CRUD feature for {example entity} that demonstrates best practices. Include frontend form, API endpoints, database operations, and basic tests.

---

Step 5: Add Testing Suite

Time: ~{X} minutes | Learning: Testing strategies

Say to Claude Code:

Set up the testing framework and write example tests for the CRUD feature. Include unit and integration tests.

---

Step 6: Configure Docker Development Environment

Time: ~{X} minutes | Learning: Docker containerization

Say to Claude Code:

Review and enhance the docker-compose.yml. Explain how to use Docker for local development.

---

Step 7: Document and Prepare for First Feature

Time: ~{X} minutes | Learning: Documentation practices

Say to Claude Code:

Help me document the project structure, update the README, and create a template for building new features.

---

You're Ready to Build!

After completing these steps, you'll have:

• Complete {framework} project structure
• Database connected and configured
• Authentication working
• Example CRUD feature as template
• Testing framework ready
• Docker environment running
• Clear development workflow

---

Default Configuration: - Next.js 15 (App Router) - TypeScript (strict mode) - Tailwind CSS v4 - Supabase client (auth, database, storage) - shadcn/ui components (optional) - React Query / TanStack Query - Zod for validation - Jest or Vitest for testing

Files to generate (Quick Start):

• package.json, tsconfig.json, next.config.js
• tailwind.config.ts, postcss.config.js
• app/layout.tsx, app/page.tsx, app/api/
• lib/supabase/client.ts, lib/supabase/server.ts
• components/, middleware.ts
• .eslintrc.json, .prettierrc
• jest.config.js or vitest.config.ts
• tests/, docker-compose.yml

Default Configuration: - PHP 8.2+ - MySQL 8.0+ - Composer for dependencies - Simple MVC structure - PDO for database access - PHPUnit for testing

Files to generate (Quick Start):

• composer.json, index.php
• src/Controllers/, src/Models/, src/Views/
• src/Router.php, src/Database.php
• config/database.php, config/config.php
• public/index.php, public/css/, public/js/
• tests/, docker-compose.yml (PHP, MySQL, phpMyAdmin)

Default Configuration: - FastAPI - PostgreSQL 15 - SQLAlchemy ORM - Alembic for migrations - Pydantic for validation - pytest for testing - uvicorn for ASGI server

Files to generate (Quick Start):

• requirements.txt, pyproject.toml, main.py
• app/init.py, app/models/, app/routers/
• app/schemas/, app/database.py, app/config.py
• tests/, alembic/
• docker-compose.yml

---

<template> ## Project Foundation Created <p><strong>Project:</strong> {project_name}<br><strong>Tech Stack:</strong> {primary technologies}<br><strong>Spinup Approach:</strong> {Guided Setup or Quick Start}<br><strong>Deployment Target:</strong> {localhost / hosting approach}</p> <hr> <h3>Workflow Status</h3> <p><strong>PLANNING PHASES - COMPLETE</strong></p> <ul> <li>Phase 0: project-brief-writer</li> <li>Phase 1: tech-stack-advisor</li> <li>Phase 2: deployment-advisor</li> </ul> <p><strong>SETUP PHASE - COMPLETE</strong></p> <ul> <li>Phase 3: project-spinup (this skill)</li> </ul> <p>[If Localhost:]<br><strong>WORKFLOW TERMINATION POINT</strong></p> <p>Your localhost project is ready for development. No further workflow phases needed.</p> <p>If you later decide to deploy publicly:</p> <ol> <li>Re-run deployment-advisor to choose a hosting target</li> <li>Continue with deploy-guide and optionally ci-cd-implement</li> </ol> <p>[If Public Deployment:]<br><strong>DEVELOPMENT PHASE - START</strong></p> <p>Build your features! When you&#39;re ready:</p> <ul> <li>Phase 4: test-orchestrator (optional - set up testing infrastructure)</li> <li>Phase 5: deploy-guide (deploy your application)</li> <li>Phase 6: ci-cd-implement (optional - automate deployments)</li> </ul> <hr> <h3>Generated Files</h3> <ul> <li>claude.md - Comprehensive project context</li> <li>docker-compose.yml - Local development environment</li> <li>Directory structure (src/, tests/, docs/)</li> <li>.env.example, .gitignore, README.md</li> <li>.docs/project-foundation-complete.md - Handoff marker<br>{If Quick Start: - Complete project scaffolding with starter code}</li> </ul> <hr> <h3>Quick Start Commands</h3> <pre><code class="language-bash" data-language="bash"># Initialize git cd {project_name} git init git checkout -b main git add . git commit -m &quot;chore: initial project setup via project-spinup skill&quot; git checkout -b dev # Start development docker compose up -d # or native commands {dev server command}</code></pre><p>Open <a href="http://localhost:{port}" target="_blank" rel="noopener noreferrer nofollow">http://localhost:{port}</a> to see your application.</p> <hr> <h3>Next Actions</h3> <p>{If Guided Setup:}</p> <ol> <li>Open claude.md and read &quot;Next Steps (Guided Setup)&quot;</li> <li>Copy the first prompt and paste it to Claude Code</li> <li>Follow the guided steps incrementally</li> <li>Ask questions as you go</li> </ol> <p>{If Quick Start:}</p> <ol> <li>Review generated code structure</li> <li>Copy .env.example to .env.local and configure</li> <li>Start building features!</li> </ol> <p>Happy coding!<br></template>

---

- Load ALL handoff documents first (if they exist) - Use handoff documents as primary source (if available) - Gather missing information conversationally (never block) - Ask about spinup approach with MODE-informed suggestion - Adapt templates to tech stack - Be comprehensive in claude.md - Include user's context (workflow, infrastructure, learning goals) - Respect user choice (Guided/Quick Start equally valid) - Include testing setup and examples - Always include docker-compose.yml - Security-conscious (.env for secrets, .gitignore) - Create .docs/project-foundation-complete.md handoff marker - Show workflow status with termination point guidance - Indicate clearly if this is a termination point (localhost) - Skip reading handoff documents (if they exist) - Use wrong templates for tech stack - Assume spinup approach without asking - Generate incomplete foundation - Block on missing prerequisites (gather info instead) - Treat localhost projects as incomplete workflows

---

Phase 3 of 7: Project Foundation

Status:
Phase 0: Project Brief (project-brief-writer)
Phase 1: Tech Stack (tech-stack-advisor)
Phase 2: Deployment Strategy (deployment-advisor)
Phase 3: Project Foundation (you are here) <- TERMINATION POINT (localhost)
Phase 4: Test Strategy (test-orchestrator) - optional
Phase 5: Deployment (deploy-guide) <- TERMINATION POINT (manual deploy)
Phase 6: CI/CD (ci-cd-implement) <- TERMINATION POINT (full automation)

---

Phase 3 of 7 in the Skills workflow chain. Expected input: .docs/deployment-strategy.md (gathered conversationally if missing) Produces: Project foundation + .docs/project-foundation-complete.md

This is a TERMINATION POINT for localhost/learning projects.

This skill can be invoked standalone without prior phases. Missing context is gathered through conversation rather than blocking. - If deployment target is localhost: Workflow terminates here - If deployment target is public: Workflow continues to deploy-guide (Phase 5) Users can invoke the **workflow-status** skill at any time to: - See current workflow progress - Check which phases are complete - Get guidance on next steps - Review all handoff documents

Mention this option when users seem uncertain about their progress.