init-project

name: init-project description: Initialize a new project with guided configuration wizard. Checks for .parade/ scaffolding, creates comprehensive constitution, governance policies, design system, and custom agents. Supports single app and monorepo configurations. Use when setting up a new project or adding configuration to an existing one.

Init Project Skill

Purpose

Guide users through comprehensive project configuration with progressive disclosure: check environment, capture project basics, create project constitution, configure stack and governance, optionally add design system and custom SME agents, then generate project.yaml and create directory scaffold.

When to Use

• Starting a new project from scratch
• Adding Claude Code configuration to an existing codebase
• User says "init project", "set up project", "configure this project"
• No project.yaml exists at repository root
• Enhancing an existing project.yaml with scaffolding, agents, and design docs

Arguments

/init-project [--minimal]

• --minimal: Skip optional sections, only ask required questions (6 questions, ~3-4 minutes)

Auto-Detection Mode

When the skill starts, it checks for an existing project.yaml with pre-filled values. This allows projects that already have basic configuration to skip redundant questions and proceed directly to scaffolding enhancements.

Step 0: Check for Existing Configuration

Before starting the wizard, check if project.yaml exists and parse its contents:

if [ -f "project.yaml" ]; then
  # Parse existing config
  # Skip questions for pre-filled sections
  # Inform user: "Detected existing project.yaml with pre-filled values"
fi

Detection Logic

Read project.yaml and check for the following pre-filled sections:

Display Detected Configuration

When existing config is found with values, display:

Detected existing project.yaml with:
- Project name: <name>
- Description: <description>
- Stack: <stack type> / <framework> / <language>
- Vision: <defined | not defined>
- [other pre-filled values]

Proceeding with scaffolding enhancements...

Auto-Detection Workflow

1. Read project.yaml using Read tool
2. Parse YAML to identify pre-filled sections
3. Store detected values in wizard state
4. Display summary of what was detected
5. Skip corresponding questions in subsequent phases
6. Proceed to enhancements - create directories, agents, design docs, etc.

Example: Partially Pre-filled Config

Given this existing project.yaml:

version: "1.0"
project:
  name: "MyApp"
  description: "A fitness tracking application"
stacks:
  mobile:
    framework: "SwiftUI"
    language: "Swift"

The skill will:

1. Display: "Detected existing project.yaml with: Project name: MyApp, Stack: mobile / SwiftUI / Swift"
2. Skip Phase 1 (Project Basics) and Phase 2 (Primary Stack) questions
3. Ask Phase 3 (Optional Sections) questions
4. Ask Phase 8 (Constitution) questions if vision section is missing
5. Proceed to Phase 5 (Directory Scaffold) and Phase 6 (Generate Coding Agents)

Example: Fully Pre-filled Config

If project.yaml has all required sections including vision:

version: "1.0"
project:
  name: "MyApp"
  description: "A fitness tracking application"
stacks:
  mobile:
    framework: "SwiftUI"
    language: "Swift"
vision:
  purpose: "Help users track fitness goals"
  target_users: "Health-conscious individuals"
  core_principles:
    - "Privacy first"
    - "Offline capable"
  boundaries:
    - "No cloud sync required"
  success_metrics:
    - "Daily active users"

The skill will:

1. Display full summary of detected configuration
2. Skip all configuration questions
3. Proceed directly to scaffolding:
   • Create .claude/, .beads/, .design/ directories
   • Generate coding agents based on detected stack
   • Create design system templates if enabled
   • Initialize beads if not already done

Process Overview

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
| PHASE 0          | --> | PHASE 1          | --> | PHASE 2          | --> | PHASE 3          |
| Environment      |     | Project Basics   |     | Constitution     |     | Tech Stack       |
| Check .parade/   |     | - Name           |     | - Vision         |     | - Framework      |
| Check .beads/    |     | - Description    |     | - Target users   |     | - Language       |
| Suggest npx      |     | - Repo type      |     | - Success metrics|     | - Testing        |
└──────────────────┘     └──────────────────┘     | - Core principles|     └──────────────────┘
                                                  | - Boundaries     |
                                                  └──────────────────┘
         ↓                        ↓                        ↓                        ↓
┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
| PHASE 3.5        | --> | PHASE 4          | --> | PHASE 5          | --> | PHASE 6          |
| MCP Setup        |     | Governance       |     | Design System    |     | Custom Agents    |
| - Detect config  |     | - Data gov       |     | - Enable/disable |     | - Domain experts |
| - Recommendations|     | - Code gov       |     | - Color scheme   |     | - Agent prompts  |
| - Configure MCPs |     | - Naming rules   |     | - Typography     |     | - Label mapping  |
└──────────────────┘     └──────────────────┘     └──────────────────┘     └──────────────────┘
         ↓
┌──────────────────┐
| PHASE 7          |
| First Feature    |
| Prompt /discover |
| - Guide next     |
| - Summarize      |
└──────────────────┘

Target: Complete comprehensive setup in under 10 minutes

Execution Protocol

When this skill is invoked:

1. Phase 0: Environment Check - Verify .parade/ and .beads/ directories exist
2. Run Auto-Detection: Check if project.yaml exists with pre-filled values
   • If detected, display summary and skip questions for pre-filled sections
   • Store detected values in wizard state for use in later phases
3. Phase 1: Project Basics - Capture name, description, repo type
4. Phase 2: Constitution Creation - Build comprehensive project constitution
5. Phase 3: Tech Stack - Configure framework, language, testing
6. Phase 3.5: MCP Setup - Configure MCP servers for Claude Desktop (optional)
7. Phase 4: Governance Policies - Set data and code governance rules
8. Phase 5: Design System - Optional design system setup
9. Phase 6: Custom Agents - Define domain-specific expert agents
10. Phase 7: First Feature Prompt - Guide user to /discover
11. Write final project.yaml using Write tool
12. Create directory scaffold with templates
13. Generate agents and constitution files
14. Show summary with next steps

Important: Ask questions ONE AT A TIME, validate each response before proceeding.

Phase 0: Environment Check

Before starting the configuration wizard, verify that the required directory structure has been created.

0.1 Check for .parade/ Directory

Check: Does .parade/ directory exist at project root?

ls -d .parade/ 2>/dev/null && echo "EXISTS" || echo "NOT_FOUND"

If NOT_FOUND:

⚠️  .parade/ directory not found

The .parade/ directory contains essential templates and scaffolding.
It should be created by running:

  npx parade-init

This will create:
- .parade/templates/ (agent templates, constitution template)
- .parade/schemas/ (validation schemas)
- Basic directory structure

Would you like to:
[1] Exit and run npx parade-init first (recommended)
[2] Continue without .parade/ (limited functionality)

If user selects [1]: Exit skill with instructions If user selects [2]: Log warning and continue

0.2 Check for .beads/ Directory

Check: Does .beads/ directory exist at project root?

ls -d .beads/ 2>/dev/null && echo "EXISTS" || echo "NOT_FOUND"

If NOT_FOUND:

Note: Beads is not yet initialized. This will be handled later in the setup process.

Continue to Phase 1

0.3 Display Environment Summary

Once checks are complete, display:

Environment Check Complete:
- .parade/ directory: ✓ Found | ✗ Not found (limited functionality)
- .beads/ directory: ✓ Found | ○ Will initialize later

Proceeding with project configuration...

Phase 1: Project Basics (Required)

1.1 Project Name

Ask: "What is the name of this project?" Validate: Pattern ^[a-zA-Z][a-zA-Z0-9-_ ]*$, max 100 chars Error: "Project name must start with a letter and can only contain letters, numbers, spaces, dashes, and underscores."

1.2 Purpose/Description

Ask: "Describe the project in 1-2 sentences. What problem does it solve?" Validate: Non-empty string

1.3 Repository Type

Ask: "Is this a single-app or monorepo project? [1] Single app [2] Monorepo" Store: repo_type = "single" or "monorepo"

Phase 2: Constitution Creation (Enhanced)

Create a comprehensive project constitution defining vision, principles, and boundaries.

2.1 Prompt for Constitution

Ask: "Would you like to create a project constitution? This defines your app's vision, principles, and boundaries. [Y/n]"

Default: Yes (press Enter to accept)

If user declines: Skip to Phase 3 (Tech Stack)

2.2 Vision Statement

Ask: "What is the vision statement for this project? Describe in 1-2 sentences what this project aims to achieve and why it matters."

Validate: Non-empty string, at least 20 characters Example: "Empower individuals to take control of their health through simple, privacy-first fitness tracking." Store: constitution_vision

2.3 Target Users

Ask: "Who are the target users? List the primary audience(s) for this project (comma-separated or one per line)."

Validate: Non-empty string Transform: Format as bullet list Example Input: "Health-conscious individuals, fitness beginners, personal trainers" Example Output:

- Health-conscious individuals
- Fitness beginners
- Personal trainers

Store: constitution_target_users

2.4 Success Metrics

Ask: "How will you measure success? Define 2-4 measurable outcomes that indicate this project is successful."

Validate: Non-empty string Transform: Format as bullet list Example Input: "Daily active users > 1000, 4.5+ app store rating, <2s load time" Example Output:

- Daily active users > 1000
- 4.5+ app store rating
- Page load time < 2 seconds

Store: constitution_success_metrics

2.5 Core Principles

Ask: "What are the core principles that guide this project? List 3-5 guiding values (comma-separated or one per line)."

Validate: Non-empty string, at least 3 items recommended Transform: Format as bullet list Example Input: "Privacy first, Offline capable, Simple and intuitive, Data ownership" Example Output:

- Privacy first
- Offline capable
- Simple and intuitive
- Data ownership

Store: constitution_core_principles

2.6 Boundaries

Ask: "What are the boundaries of this project? What will this project NOT do or support?"

Validate: Non-empty string Transform: Format as bullet list Example Input: "No social features, No cloud sync required, No third-party tracking" Example Output:

- No social features
- No cloud sync required
- No third-party tracking

Store: constitution_boundaries

2.7 Write Constitution File

1. Check if .parade/templates/CONSTITUTION.md.template exists

   • If exists: Read template
   • If not exists: Use fallback inline template

2. Substitute placeholders:

   • {{PROJECT_NAME}} → project_name (from Phase 1)
   • {{VISION}} → constitution_vision
   • {{TARGET_USERS}} → constitution_target_users (formatted list)
   • {{SUCCESS_METRICS}} → constitution_success_metrics (formatted list)
   • {{CORE_PRINCIPLES}} → constitution_core_principles (formatted list)
   • {{BOUNDARIES}} → constitution_boundaries (formatted list)

3. Create docs/ directory if needed:

   mkdir -p docs
   

4. Write to docs/CONSTITUTION.md using Write tool

If docs/CONSTITUTION.md already exists:

• Offer: [1] View [2] Replace (backup to .md.bak) [3] Skip
• Backup logic: cp docs/CONSTITUTION.md docs/CONSTITUTION.md.bak.TIMESTAMP

Phase 3: Tech Stack (Required)

3.1 Stack Type

Ask: "What type of stack? [1] Frontend [2] Backend [3] Mobile [4] Database" Store: stack_type = "frontend"/"backend"/"mobile"/"database"

3.2 Framework

Ask: Framework options based on stack_type (Next.js, React, SwiftUI, Express, etc.) Offer: Numbered menu with "Other (specify)" option

3.3 Language

Ask: "Primary language? [1] TypeScript [2] JavaScript [3] Swift [4] Python [5] Go [6] Other"

3.4 Testing Framework

Ask: "Unit testing framework? [1] Jest [2] Vitest [3] XCTest [4] pytest [5] None [6] Other"

3.5 Commands

Ask: Test, lint, and build commands Offer smart defaults based on stack type (e.g., npm test, swift test, pytest)

Phase 3.5: MCP Setup (Optional)

Configure Model Context Protocol (MCP) servers for enhanced Claude Desktop integration.

3.5.1 Prompt for MCP Setup

Ask: "Would you like to configure MCP servers for Claude Desktop? This enables Claude to interact with databases, file systems, and other services. [Y/n]"

Default: Yes (press Enter to accept)

If user declines: Skip to Phase 4 (Governance Policies)

3.5.2 Detect Claude Desktop Config

Check if Claude Desktop configuration exists:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

If config not found:

Note: Claude Desktop configuration not found at expected location.

This could mean:
1. Claude Desktop is not installed
2. Claude Desktop hasn't been run yet (config created on first launch)
3. Config is at a non-standard location

Options:
[1] Create new config file (will be used when Claude Desktop is installed)
[2] Skip MCP setup for now

If user selects [1]: Continue with MCP setup, create config directory if needed If user selects [2]: Skip to Phase 4

3.5.3 Generate MCP Recommendations

Based on stack selection from Phase 3, generate MCP recommendations using the McpRecommendationEngine patterns:

MCP Mapping (Framework → MCP Servers):

Priority Levels:

• required: Essential for the selected stack to function properly
• recommended: Significantly enhances development experience
• optional: Nice-to-have, can be added later

3.5.4 Display Recommendations

Display:

Based on your stack (${framework} / ${language}), I recommend these MCP servers:

| Priority    | MCP Server  | Rationale                                           |
|-------------|-------------|-----------------------------------------------------|
| recommended | filesystem  | Enables file system operations for ${framework}    |
|             |             | development, allowing Claude to read, write, and   |
|             |             | manage project files.                              |
| recommended | supabase    | Provides direct integration with Supabase database |
|             |             | and auth services for seamless backend development.|
| optional    | github      | Allows Claude to interact with GitHub repositories,|
|             |             | issues, and pull requests for enhanced project     |
|             |             | management.                                        |

Select MCPs to configure:
[1] All recommended (default)
[2] All (including optional)
[3] Choose individually
[4] Skip MCP setup

If user selects [3]: Display checklist for each MCP server

3.5.5 Configure Selected MCPs

For each selected MCP server, collect required configuration:

filesystem MCP

Configuring filesystem MCP...

This MCP allows Claude to read and write files in specified directories.

**Ask:** "Which directories should Claude have access to? (comma-separated paths, or '.' for current project)"

**Default:** Current project directory
**Validate:** Paths exist or will be created
**Store:** `mcp_filesystem_paths`

**Config Example:**
{
  "command": "npx",
  "args": ["-y", "@anthropic/mcp-server-filesystem"],
  "env": {
    "ALLOWED_PATHS": "${mcp_filesystem_paths}"
  }
}

supabase MCP

Configuring Supabase MCP...

This MCP enables direct interaction with your Supabase project.

**Ask:** "Enter your Supabase project URL (e.g., https://xxx.supabase.co):"
**Validate:** URL format, starts with https://
**Store:** `mcp_supabase_url`

**Ask:** "Enter your Supabase anon/public key:"
**Validate:** Non-empty string
**Sensitive:** Do not log or display after entry
**Store:** `mcp_supabase_key`

**Config Example:**
{
  "command": "npx",
  "args": ["-y", "@supabase/mcp-server-supabase"],
  "env": {
    "SUPABASE_URL": "${mcp_supabase_url}",
    "SUPABASE_KEY": "${mcp_supabase_key}"
  }
}

postgres MCP

Configuring PostgreSQL MCP...

This MCP enables direct PostgreSQL database operations.

**Ask:** "Enter your PostgreSQL connection URL (e.g., postgresql://user:pass@localhost:5432/db):"
**Validate:** PostgreSQL URL format
**Sensitive:** Do not log or display after entry
**Store:** `mcp_postgres_url`

**Config Example:**
{
  "command": "npx",
  "args": ["-y", "@anthropic/mcp-server-postgres"],
  "env": {
    "DATABASE_URL": "${mcp_postgres_url}"
  }
}

sqlite MCP

Configuring SQLite MCP...

This MCP provides SQLite database access.

**Ask:** "Enter the path to your SQLite database file (e.g., ./database.sqlite):"
**Validate:** Path format (file doesn't need to exist yet)
**Store:** `mcp_sqlite_path`

**Config Example:**
{
  "command": "npx",
  "args": ["-y", "@anthropic/mcp-server-sqlite"],
  "env": {
    "DATABASE_PATH": "${mcp_sqlite_path}"
  }
}

github MCP

Configuring GitHub MCP...

This MCP enables GitHub repository interactions.

**Ask:** "Enter your GitHub personal access token (with repo scope):"
**Validate:** Non-empty string
**Sensitive:** Do not log or display after entry
**Store:** `mcp_github_token`

**Config Example:**
{
  "command": "npx",
  "args": ["-y", "@anthropic/mcp-server-github"],
  "env": {
    "GITHUB_TOKEN": "${mcp_github_token}"
  }
}

3.5.6 Write to Claude Desktop Config

Step 1: Backup existing config (if exists)

# Create timestamped backup
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json \
   ~/Library/Application\ Support/Claude/claude_desktop_config.backup-${TIMESTAMP}.json

Display: "Backed up existing config to claude_desktop_config.backup-${TIMESTAMP}.json"

Step 2: Read existing config or create new

If config exists:

• Parse existing JSON
• Preserve all existing settings
• Merge new mcpServers entries

If config doesn't exist:

• Create parent directory if needed
• Initialize with empty mcpServers object

Step 3: Add MCP server entries

For each configured MCP, add entry to mcpServers object:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/path/to/project"
      }
    },
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_URL": "https://xxx.supabase.co",
        "SUPABASE_KEY": "your-anon-key"
      }
    }
  }
}

Step 4: Write atomically

Write to temp file first, then rename to prevent corruption:

# Write to temp file
echo "${config_json}" > ~/Library/Application\ Support/Claude/claude_desktop_config.json.tmp

# Atomic rename
mv ~/Library/Application\ Support/Claude/claude_desktop_config.json.tmp \
   ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 5: Handle existing server entries

If a server name already exists in config:

Ask: "MCP server '${server_name}' already exists in config. [1] Keep existing [2] Replace with new [3] Skip this server"

Default: Keep existing (to preserve user customizations)

3.5.7 Display MCP Setup Summary

MCP Setup Complete!

Configured servers:
- filesystem: /path/to/project
- supabase: https://xxx.supabase.co
- github: configured

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json
Backup: ~/Library/Application Support/Claude/claude_desktop_config.backup-20260105_143000.json

Note: Restart Claude Desktop for changes to take effect.

3.5.8 Error Handling

Permission denied:

Error: Cannot write to Claude Desktop config directory.

Please ensure you have write permissions to:
  ~/Library/Application Support/Claude/

You can manually add MCP servers by editing claude_desktop_config.json
or running this setup again with appropriate permissions.

Invalid JSON in existing config:

Error: Existing Claude Desktop config contains invalid JSON.

Options:
[1] View backup and continue (creates new config)
[2] Exit and fix manually

Backup location: ~/Library/Application Support/Claude/claude_desktop_config.backup-${TIMESTAMP}.json

MCP server validation failed:

Warning: Could not validate ${server_name} MCP configuration.

The server entry was added but may not work correctly.
Common issues:
- Missing environment variables
- Incorrect command or args
- Network connectivity (for remote services)

You can test by restarting Claude Desktop and checking for errors.

Phase 4: Governance Policies (New/Enhanced)

Configure data and code governance policies for the project.

4.1 Data Governance

4.1.1 Auth Provider

Ask: "What authentication provider will you use? [1] Supabase [2] Firebase [3] Custom [4] None [5] Other"

Store: auth_provider = "supabase" | "firebase" | "custom" | "none" | "<other>"

4.1.2 Naming Conventions

Ask: "Preferred naming conventions:"

Field naming:

• Ask: "Database field naming? [1] snake_case (recommended) [2] camelCase [3] PascalCase"
• Store: naming_fields = "snake_case" | "camelCase" | "PascalCase"

File naming:

• Ask: "File naming? [1] kebab-case (recommended) [2] camelCase [3] PascalCase"
• Store: naming_files = "kebab-case" | "camelCase" | "PascalCase"

Date fields:

• Offer smart default: created_at, updated_at based on field naming convention
• Store: naming_dates = "created_at" | "createdAt" | etc.

4.2 Code Governance

4.2.1 Linting Rules

Ask: "Linting configuration? [1] Strict (recommended) [2] Standard [3] Relaxed [4] Custom"

Store: linting_mode = "strict" | "standard" | "relaxed" | "custom"

If custom: Ask for specific linting command

4.2.2 Testing Requirements

Ask: "Minimum test coverage? [1] 80% (strict) [2] 60% (standard) [3] 40% (relaxed) [4] None"

Store: test_coverage_min = 80 | 60 | 40 | 0

4.2.3 Review Requirements

Ask: "Code review requirements? [1] Required for all changes [2] Required for critical files [3] Optional [4] None"

Store: review_requirement = "all" | "critical" | "optional" | "none"

4.3 Write Governance to project.yaml

All governance settings are written to the data_governance and code_governance sections of project.yaml:

data_governance:
  auth_provider: "${auth_provider}"
  naming_conventions:
    fields: "${naming_fields}"
    files: "${naming_files}"
    directories: "kebab-case"
    dates: "${naming_dates}"
    enums: "SCREAMING_SNAKE"

code_governance:
  linting:
    mode: "${linting_mode}"
    command: "${lint_command}"
  testing:
    min_coverage: ${test_coverage_min}
    command: "${test_command}"
  review:
    requirement: "${review_requirement}"

Phase 5: Design System (Enhanced)

5.1 Prompt for Design System

Ask: "Would you like to set up a design system for this project? [Y/n]"

Default: Yes (press Enter to accept)

If user declines: Skip to Phase 6 (Custom Agents)

5.2 Enable Design System

Set: design_system_enabled = true Set: design_system_path = ".design/"

5.3 Color Scheme

Ask: "What color scheme will your design support? [1] Light only [2] Dark only [3] Both light and dark [4] Custom"

Store: design_color_scheme = "light" | "dark" | "both" | "custom"

5.4 Primary Colors

Ask: "What are your primary brand colors? (Enter hex codes, comma-separated, e.g., #3B82F6, #10B981)"

Validate: Hex color format #[0-9A-Fa-f]{6} Store: design_primary_colors as array

Example Input: "#3B82F6, #10B981, #F59E0B" Example Output:

design_system:
  colors:
    primary:
      - "#3B82F6"
      - "#10B981"
      - "#F59E0B"

5.5 Typography Preferences

Ask: "Font family preference? [1] System fonts (recommended) [2] Google Fonts [3] Custom [4] Skip"

Store: design_typography = "system" | "google" | "custom" | "none"

If Google Fonts or Custom:

• Ask: "Font family name(s)? (comma-separated)"
• Store: design_font_families as array

5.6 Create Design System Files

If design system is enabled, create starter files in .design/:

1. Create .design/ directory:

   mkdir -p .design
   

2. Generate Colors.md with actual content:

   • Use colors from 5.4
   • Include semantic colors (success, warning, error, info)
   • Include neutral palette (gray scale)

3. Generate Typography.md with actual content:

   • Use font families from 5.5
   • Include type scale (headings, body, captions)
   • Include font weights and line heights

4. Generate Components.md with starter patterns:

   • Button variants
   • Form inputs
   • Cards
   • Navigation

Template location: Check for .parade/templates/design/ templates, or use inline fallbacks

Write files using Write tool to:

• .design/Colors.md
• .design/Typography.md
• .design/Components.md

5.7 Update project.yaml

Add design system configuration:

design_system:
  enabled: true
  path: ".design/"
  color_scheme: "${design_color_scheme}"
  colors:
    primary: ${design_primary_colors}
  typography:
    mode: "${design_typography}"
    families: ${design_font_families}
  docs:
    - ".design/Colors.md"
    - ".design/Typography.md"
    - ".design/Components.md"

Phase 6: Custom Agents (Enhanced)

6.1 Prompt for Custom Agents

Ask: "Does your project have domain-specific expertise that requires custom agents? (e.g., fitness domain, compliance, security) [Y/n]"

Default: No (press Enter to skip)

If user declines: Skip to Phase 7 (First Feature Prompt)

6.2 Custom Agent Definition Loop

For each custom agent the user wants to create:

6.2.1 Agent Name

Ask: "What should this agent be called? Use kebab-case (e.g., 'fitness-domain', 'security-expert', 'compliance-sme')"

Validate: kebab-case format, no spaces Store: agent_label

Transform to display name: Convert kebab-case to Title Case

• Example: "fitness-domain" → "Fitness Domain Expert"
• Store: agent_name

6.2.2 Domain Expertise Description

Ask: "Describe the domain expertise this agent should have. What area does it specialize in?"

Validate: Non-empty string, 1-2 sentences Example: "Expert in fitness tracking algorithms, workout plan validation, and health metrics analysis." Store: domain_expertise

6.2.3 Key Patterns and Focus Areas

Ask: "What key files, patterns, or areas of the codebase should this agent focus on when reviewing?"

Validate: Non-empty string Example: "Workout calculation logic, health data models, fitness goal validation" Store: key_patterns

6.2.4 Generate Agent File

1. Check for template:

   • Try to read .parade/templates/agents/custom-sme-agent.md.template
   • If not found, use inline fallback template

2. Substitute placeholders:

   • {{AGENT_NAME}} → agent_name (Title Case: "Fitness Domain Expert")
   • {{AGENT_LABEL}} → agent_label (kebab-case: "fitness-domain")
   • {{DOMAIN_DESCRIPTION}} → domain_expertise
   • {{DOMAIN_EXPERTISE}} → domain_expertise (detailed description)
   • {{KEY_PATTERNS}} → key_patterns

3. Create .claude/agents/ directory if needed:

   mkdir -p .claude/agents
   

4. Write agent file to .claude/agents/<agent-label>.md using Write tool

Note: The template includes standardized output format (findings as JSON, recommendations/concerns as plain text)

6.2.5 Add to project.yaml

Add entry to agents.custom[] array:

agents:
  custom:
    - name: "${agent_name}"
      label: "${agent_label}"
      prompt_file: ".claude/agents/${agent_label}.md"

6.3 Repeat or Continue

Ask: "Would you like to add another custom agent? [Y/n]"

• If yes: Return to 6.2.1
• If no: Continue to Phase 7

Phase 7: First Feature Prompt (New)

7.1 Prompt for First Feature

Display:

Setup complete! Your project configuration is ready.

Would you like to walk through your first feature now? This will guide you
through the discovery process to capture a feature idea and generate a spec.

[Y] Yes, let's create a feature (recommended)
[N] No, I'll do this later

Default: Yes

7.2 If Yes - Guide to /discover

Display:

Great! Let's capture your first feature idea.

To start the discovery process, describe your feature idea in 1-2 sentences.
I'll use the /discover skill to:
1. Capture your feature brief
2. Run discovery with SME agents
3. Generate a detailed specification

What feature would you like to build?

Wait for user input, then:

• Invoke /discover skill with the user's feature description
• This transitions the user directly into the workflow

7.3 If No - Summarize Next Steps

Display:

No problem! Here's what you can do next:

1. **Start building a feature:**
   Run `/discover` and describe your feature idea

2. **Verify setup:**
   Run `/parade-doctor` to check everything is configured correctly

3. **Review your constitution:**
   Open `docs/CONSTITUTION.md` to review your project's guiding principles

4. **Review project config:**
   Open `project.yaml` to review or manually adjust settings

5. **Add more custom agents:**
   Run `/init-project` again to add more domain experts

6. **Review generated agents:**
   Check `.claude/agents/` for coding agents tailored to your stack

---

**Visual Dashboard (Optional)**

The Parade app provides a visual Kanban board for tracking briefs, epics, and tasks.

To install (one-time setup):
   git clone https://github.com/JeremyKalmus/parade.git ~/parade
   cd ~/parade && npm install

To run:
   cd ~/parade && npm run dev

Then open your project folder in the app.

---

Need help? Run `/help` for available commands.

Generate Configuration and Scaffold

YAML Generation

Use Write tool to create project.yaml at repository root with all collected values.

Single-app structure:

version: "1.0"
project:
  name: "${project_name}"
  description: "${project_description}"
vision:
  purpose: "${constitution_vision}"
  target_users: "${constitution_target_users}"
  success_metrics: "${constitution_success_metrics}"
  core_principles: "${constitution_core_principles}"
  boundaries: "${constitution_boundaries}"
stacks:
  ${stack_type}:
    framework: "${framework}"
    language: "${language}"
    testing:
      unit: "${test_framework}"
      commands:
        test: "${test_command}"
        lint: "${lint_command}"
        build: "${build_command}"
design_system:
  enabled: ${design_system_enabled}
  path: "${design_system_path}"
  color_scheme: "${design_color_scheme}"
  colors:
    primary: ${design_primary_colors}
  typography:
    mode: "${design_typography}"
    families: ${design_font_families}
  docs:
    - ".design/Colors.md"
    - ".design/Typography.md"
    - ".design/Components.md"
data_governance:
  auth_provider: "${auth_provider}"
  naming_conventions:
    fields: "${naming_fields}"
    files: "${naming_files}"
    directories: "kebab-case"
    dates: "${naming_dates}"
    enums: "SCREAMING_SNAKE"
code_governance:
  linting:
    mode: "${linting_mode}"
    command: "${lint_command}"
  testing:
    min_coverage: ${test_coverage_min}
    command: "${test_command}"
  review:
    requirement: "${review_requirement}"
agents:
  custom: ${custom_agents_array}

See: docs/project-yaml-spec.md for validation checklist and complete examples

Create Directory Scaffold

Core Directories (always created)

mkdir -p .claude/skills .claude/agents .claude/schemas .claude/templates .beads
mkdir -p .design  # if design_system.enabled

Template Files

CLAUDE.md: Project instructions with stack info

• Check if exists, offer: [1] Keep [2] Replace (backup) [3] Merge (add Stack section)
• Use templates from .claude/templates/CLAUDE.md.template
• Substitute: {{PROJECT_NAME}}, {{FRAMEWORK}}, {{LANGUAGE}}, etc.

beads/config.yaml: Beads CLI configuration

• Check if exists, offer: [1] Keep [2] Replace (backup)
• Use templates from .claude/templates/beads-config.yaml.template
• Substitute: {{PROJECT_PREFIX}} (lowercase, no spaces)

Design System Templates (if enabled)

Create starter files in .design/:

• Colors.md - Color palette (primary, semantic, neutral)
• Typography.md - Font families and scale
• Components.md - Component patterns

Check and Initialize Beads

Beads is a required dependency for Parade. Check if it's installed:

which bd

If Beads is NOT installed:

Display installation instructions:

⚠️  Beads CLI not found

Beads is required for task management. Install it with:

  npm install -g beads

Or visit: https://github.com/steveyegge/beads

Options:
1. Install now (I'll wait)
2. Continue without beads (limited functionality)
3. Exit and install manually

If Beads IS installed:

Initialize the project:

bd init --prefix "$PROJECT_PREFIX"

Verify initialization:

bd doctor

See: docs/init-troubleshooting.md for error handling scenarios

Generate Coding Agents

After stack selection (Phase 3), generate stack-specific coding agents to assist with implementation tasks.

Framework-to-Template Mapping

Based on the selected stack, copy and customize the appropriate agent template:

Agent Generation Logic

For each applicable stack type:

1. Detect framework type from user responses in Phase 2
2. Select template based on mapping table above
3. Read template from .claude/templates/agents/<template-name>
4. Substitute placeholders with collected values:
   • {{PROJECT_NAME}} → project_name
   • {{FRAMEWORK}} → framework (e.g., "Vitest", "SwiftUI", "PostgreSQL")
   • {{LANGUAGE}} → language (e.g., "TypeScript", "Swift")
   • {{TEST_COMMAND}} → test_command
   • {{BUILD_COMMAND}} → build_command
5. Write agent file to .claude/agents/<agent-name>.md

Placeholder Substitution Examples

TypeScript Agent:

• {{PROJECT_NAME}} → "MyAwesomeApp"
• {{FRAMEWORK}} → "Vitest"
• {{LANGUAGE}} → "TypeScript"
• {{TEST_COMMAND}} → "npm test"
• {{BUILD_COMMAND}} → "npm run build"

Swift Agent:

• {{PROJECT_NAME}} → "MyiOSApp"
• {{FRAMEWORK}} → "SwiftUI"
• {{LANGUAGE}} → "Swift"
• {{TEST_COMMAND}} → "swift test"
• {{BUILD_COMMAND}} → "swift build"

SQL Agent:

• {{PROJECT_NAME}} → "MyDatabaseProject"
• {{FRAMEWORK}} → "PostgreSQL"
• {{LANGUAGE}} → "SQL"
• {{TEST_COMMAND}} → "psql -f tests/schema_test.sql"
• {{BUILD_COMMAND}} → "supabase db reset"

Multi-Stack Projects

For projects with multiple stack types (e.g., full-stack apps):

• Generate agents for each relevant stack
• Example: A Next.js + Supabase project generates:
  • typescript-agent.md (frontend/backend)
  • sql-agent.md (database)

Agent File Handling

If agent file exists:

• Offer: [1] Keep [2] Replace (backup to .md.bak) [3] Skip
• Default: Keep existing agents to preserve customizations

Backup naming:

• typescript-agent.md.bak
• If backup exists, use timestamp: typescript-agent.md.bak.20260102_143000

Existing Configuration Handling

Detection

ls -la project.yaml 2>/dev/null && echo "EXISTS" || echo "NOT_FOUND"

If EXISTS

Offer options:

1. View - Display current configuration
2. Merge - Add new sections while preserving existing
3. Replace - Backup to project.yaml.bak and start fresh

Merge Strategy

• Use Edit tool to surgically add/update sections
• Preserve existing project name, description, stacks
• Add new optional sections (design_system, agents, etc.)
• Show diff before applying changes

Backup Logic

# Always backup before replace
cp project.yaml project.yaml.bak
# If backup exists, create timestamped: project.yaml.bak.20260102_143000

See: docs/config-merge-patterns.md for detailed merge procedures and examples

Output

Success Summary

Display at the end of the wizard (only if NOT transitioning to /discover):

## Project Initialized Successfully!

### Files Created
- project.yaml (comprehensive project configuration)
- .claude/CLAUDE.md (project-specific instructions)
- .claude/agents/typescript-agent.md (TypeScript coding agent) [example]
- .claude/agents/fitness-domain.md (custom SME) [if created]
- docs/CONSTITUTION.md (project constitution) [if created]
- .design/Colors.md (color palette) [if design system enabled]
- .design/Typography.md (typography system) [if design system enabled]
- .design/Components.md (component patterns) [if design system enabled]

**Note:** All custom SME agents use the standardized output format (findings as JSON, recommendations/concerns as plain text).

### Directories Created
- .claude/skills/, .claude/agents/, .claude/schemas/, .claude/templates/
- .beads/ (task management)
- .design/ [if design system enabled]
- docs/ [if constitution created]

### Configuration Summary
Project: ${project_name}
Vision: ${constitution_vision} [if created]
Stack: ${framework} / ${language} / ${test_framework}
Auth Provider: ${auth_provider}
Design System: ${design_system_enabled ? "Enabled" : "Disabled"}
Governance: Data (${naming_fields} fields) + Code (${linting_mode} linting)
Coding Agents: ${generated_agents}
Custom SMEs: ${custom_agents} [if created]
Constitution: ${constitution_created ? "Created" : "Skipped"}

---

## What's Next?

[Content from Phase 7.3 - Next Steps]

Quick Reference: Minimal Flow

For --minimal flag:

Phase 0: Environment check (always runs)

Phase 1: Project basics (3 questions)

1. Project name
2. Project description (1-2 sentences)
3. Repository type [1-2]

Phase 2: Skip constitution (auto-skip with --minimal)

Phase 3: Tech stack (4 questions)

1. Stack type [1-4]
2. Framework (based on stack)
3. Primary language [1-6]
4. Test command (with smart default)

Phase 3.5: Skip MCP setup (auto-skip with --minimal)

Phase 4: Skip governance (use smart defaults)

Phase 5: Skip design system (auto-skip with --minimal)

Phase 6: Skip custom agents (auto-skip with --minimal)

Phase 7: Skip first feature prompt (auto-skip with --minimal)

Generate minimal YAML with smart defaults, create directories, show success message. Total time: ~3-4 minutes (7 questions + environment check)

Reference Documentation

For detailed specifications, merge procedures, and troubleshooting:

• docs/project-yaml-spec.md - Complete YAML schema, validation rules, examples
• docs/config-merge-patterns.md - Merge/replace logic, backup procedures, existing config handling
• docs/init-troubleshooting.md - Error scenarios, validation failures, recovery procedures