Setup Project

Setup Project

Initialize a new project with Claude Copilot. This command only works on projects that haven't been set up yet.

Step 1: Verify This Is a New Project

ls .mcp.json 2>/dev/null && echo "PROJECT_EXISTS" || echo "NEW_PROJECT"

If PROJECT_EXISTS:

Stop and tell the user:

This project is already configured.

Found .mcp.json - this project has already been set up with Claude Copilot.

To update this project with the latest Claude Copilot files, use:

/update-project

Then STOP. Do not continue.

If NEW_PROJECT: Continue to Step 1B.

Step 1B: Check for Minimal Setup

Look at the user's message for keywords: "minimal", "quick start", "memory only", "simple", "fast"

If found: Set SETUP_MODE = "MINIMAL" and continue to Step 2. If not found: Set SETUP_MODE = "FULL" and continue to Step 2.

Step 2: Verify Machine Setup

ls ~/.claude/copilot/mcp-servers/copilot-memory/dist/index.js 2>/dev/null && echo "MEMORY_OK" || echo "MEMORY_MISSING"

If MEMORY_MISSING:

Tell user:

Claude Copilot is not installed on this machine.

Please complete machine setup first:

1. Clone the repository:

   mkdir -p ~/.claude
   cd ~/.claude
   git clone https://github.com/Everyone-Needs-A-Copilot/claude-copilot.git copilot
   

2. Open Claude Code in ~/.claude/copilot and follow the setup instructions in SETUP.md

Then return here and run /setup-project again.

Then STOP.

Note: Skills Copilot MCP is optional. For local skills, use native @include directives instead. Only install Skills Copilot if you need SkillsMP marketplace access or private skill storage.

If SETUP_MODE = "MINIMAL": Skip to Minimal Setup Flow.

Step 3: Get Project Info

echo $HOME
pwd
basename $(pwd)

Store:

• HOME_PATH = result of $HOME
• PROJECT_PATH = result of pwd
• PROJECT_NAME = result of basename

Step 4: Create Directory Structure

mkdir -p .claude/commands
mkdir -p .claude/agents
mkdir -p .claude/skills

Step 5: Copy Project Commands

Only copy commands that belong at project level (protocol and continue):

cp ~/.claude/copilot/.claude/commands/protocol.md .claude/commands/
cp ~/.claude/copilot/.claude/commands/continue.md .claude/commands/

Verify:

ls .claude/commands/

Should show: continue.md and protocol.md

Step 6: Copy Agents

cp ~/.claude/copilot/.claude/agents/*.md .claude/agents/

Verify:

ls .claude/agents/ | wc -l

Should show 12+ files.

Step 7: Create .mcp.json with Template Variable Expansion

Read the template and expand variables automatically:

cat ~/.claude/copilot/templates/mcp.json

Expand these variables:

Process:

1. Read template from ~/.claude/copilot/templates/mcp.json
2. Replace all variables:
   • $HOME → actual home path (NO tilde)
   • $PROJECT_PATH → result of pwd
   • $PROJECT_NAME → result of basename $(pwd)
   • $COPILOT_PATH → $HOME/.claude/copilot (expanded)
3. Validate expansion (see validation below)
4. Write to .mcp.json

CRITICAL:

• All paths must be absolute (no ~ or $HOME in final output)
• No unexpanded variables ($xxx) in final file
• Verify JSON is valid

Validation After Expansion:

# Check for unexpanded variables
grep -E '\$[A-Z_]+' .mcp.json && echo "ERROR: Unexpanded variables found" || echo "Variables OK"

# Verify critical paths exist
ls -l "$HOME/.claude/copilot/mcp-servers/copilot-memory/dist/index.js" && echo "Memory server OK" || echo "Memory server MISSING"

# Note: Skills Copilot is optional - only check if configured in template

# Validate JSON
node -e "JSON.parse(require('fs').readFileSync('.mcp.json', 'utf8'))" && echo "JSON valid" || echo "JSON INVALID"

If validation fails:

Report clear error with fix instructions:

ERROR: Template expansion failed

Variable: $COPILOT_PATH
Expected: ~/.claude/copilot/mcp-servers/copilot-memory/dist/index.js
Found: File does not exist

Fix: Run /setup from ~/.claude/copilot first to build MCP servers

Step 8: Detect Knowledge

8.1: Check Global Knowledge

ls ~/.claude/knowledge/knowledge-manifest.json 2>/dev/null && echo "GLOBAL_KNOWLEDGE_EXISTS" || echo "NO_GLOBAL_KNOWLEDGE"
cat ~/.claude/knowledge/knowledge-manifest.json 2>/dev/null | grep '"name"' | head -1

Store:

• GLOBAL_KNOWLEDGE_EXISTS = true/false
• KNOWLEDGE_NAME = from manifest (if exists)

8.2: Check Project Expectation

Look for signals that this project expects knowledge:

# Check if CLAUDE.md references knowledge tools
grep -q "knowledge_search\|knowledge_get" CLAUDE.md 2>/dev/null && echo "PROJECT_EXPECTS_KNOWLEDGE" || echo "NO_EXPECTATION"

# Check for team repo URL in existing manifest (if any)
cat ~/.claude/knowledge/knowledge-manifest.json 2>/dev/null | grep '"repository"' -A2 | grep '"url"'

Store:

• PROJECT_EXPECTS_KNOWLEDGE = true/false
• TEAM_REPO_URL = if found in manifest

8.3: Decision Matrix

If NO_GLOBAL_KNOWLEDGE but PROJECT_EXPECTS_KNOWLEDGE:

Use AskUserQuestion to offer knowledge setup:

Question: "This project references team knowledge, but none is configured on this machine. Would you like to set it up?" Header: "Knowledge" Options:

1. "Yes, set up knowledge now" - Will run /knowledge-copilot after setup
2. "Skip for now" - Continue without knowledge (can run /knowledge-copilot later)

Store user's choice in SETUP_KNOWLEDGE_NOW.

Step 9: Ask Project Details

Use AskUserQuestion to gather:

Question 1: "What's this project about?"

• Header: "Description"
• Let user type freely

Question 2: "What's the main tech stack?"

• Header: "Stack"
• Options:
  • "React/Next.js"
  • "Node.js/Express"
  • "Python/Django"
  • "Other (describe)"

Step 10: Create CLAUDE.md

Read the template from ~/.claude/copilot/templates/CLAUDE.template.md and create CLAUDE.md with:

• PROJECT_NAME = folder name
• PROJECT_DESCRIPTION = user's answer
• TECH_STACK = user's answer
• KNOWLEDGE_STATUS = detected status
• KNOWLEDGE_NAME = if available

Step 11: Verify Setup

ls -la .mcp.json
ls -la CLAUDE.md
ls .claude/commands/
ls .claude/agents/ | head -5

All must exist.

Step 12: Report Success

Project Setup Complete!

Created:

• .mcp.json - MCP server configuration
• CLAUDE.md - Project instructions
• .claude/commands/ - Protocol commands (/protocol, /continue)
• .claude/agents/ - 12 specialized agents
• .claude/skills/ - For project-specific skills

Configuration:

• Memory workspace: {{PROJECT_NAME}}
• Skills: Local (.claude/skills) {{IF GLOBAL_KNOWLEDGE_EXISTS}}
• Knowledge: {{KNOWLEDGE_NAME}} (global) {{ELSE}}
• Knowledge: Not configured {{END IF}}

Next steps:

1. Restart Claude Code to load the MCP servers
2. Run /mcp to verify servers are connected:

   ● copilot-memory
   

   Note: Skills Copilot (optional) only shows if configured in .mcp.json
3. Run /protocol to start working

Using Skills:

• For local skills: Use @include .claude/skills/NAME/SKILL.md in your prompts
• For marketplace access: Install Skills Copilot MCP (see mcp-servers/skills-copilot/README.md)

{{IF NO_GLOBAL_KNOWLEDGE AND NOT SETUP_KNOWLEDGE_NOW}} Optional: Set up shared knowledge

Create a knowledge repository for company/product information:

/knowledge-copilot

{{END IF}}

{{IF SETUP_KNOWLEDGE_NOW}}

Step 13: Set Up Knowledge

Since you chose to set up knowledge now, running /knowledge-copilot:

Note: This will guide you through connecting to your team's knowledge repository.

{{END IF}}

Minimal Setup Flow

This flow is triggered when SETUP_MODE = "MINIMAL". It installs only Memory Copilot for the fastest path to getting started.

Report:

Mode: Minimal Setup (Memory Only)

What you'll get:
- Memory Copilot - Session persistence and context
- /continue command - Resume previous work
- Automatic progress tracking

What you WON'T get:
- Agents - No specialized expertise
- Skills Copilot - No on-demand skills
- /protocol command - No Agent-First workflow

You can upgrade to the full framework anytime by running /setup-project again (without "minimal").

Minimal Step 1: Get Project Info

echo $HOME
pwd
basename $(pwd)

Store:

• HOME_PATH = result of $HOME
• PROJECT_PATH = result of pwd
• PROJECT_NAME = result of basename

Minimal Step 2: Create Directory and Copy Continue Command

mkdir -p .claude/commands
cp ~/.claude/copilot/.claude/commands/continue.md .claude/commands/

Verify:

ls .claude/commands/

Should show: continue.md

Minimal Step 3: Create .mcp.json with Minimal Template

cat ~/.claude/copilot/templates/minimal-mcp.json

Expand variables (same rules as Step 7 above):

Write expanded JSON to .mcp.json.

Validate:

grep -E '\$[A-Z_]+' .mcp.json && echo "ERROR: Unexpanded variables found" || echo "Variables OK"
ls -l "$HOME/.claude/copilot/mcp-servers/copilot-memory/dist/index.js" && echo "Memory server OK" || echo "Memory server MISSING"
node -e "JSON.parse(require('fs').readFileSync('.mcp.json', 'utf8'))" && echo "JSON valid" || echo "JSON INVALID"

Minimal Step 4: Create Minimal CLAUDE.md

Create a minimal CLAUDE.md:

# CLAUDE.md

This file provides guidance to Claude Code when working in this repository.

## Project Overview

**Name:** {{PROJECT_NAME}}

---

## Claude Copilot (Minimal Setup)

This project uses Memory Copilot only - the minimal Claude Copilot configuration.

**Full documentation:** `~/.claude/copilot/docs/00-overview.md`

### What You Have

| Feature | Status |
|---------|--------|
| **Memory Copilot** | Enabled - Persistent session memory |
| **`/continue` command** | Enabled - Resume previous work |
| **Agents** | Not installed |
| **Skills** | Not installed |
| **`/protocol`** | Not installed |

### Commands

| Command | Purpose |
|---------|---------|
| `/continue` | Resume previous work via Memory Copilot |

### Memory Tools

| Tool | Purpose |
|------|---------|
| `initiative_start` | Begin new initiative |
| `initiative_get` | Retrieve current initiative |
| `initiative_update` | Update progress, decisions, lessons |
| `initiative_complete` | Archive completed initiative |
| `memory_store` | Store decisions, lessons, context |
| `memory_search` | Semantic search across memories |

### Configuration

- Memory workspace: `{{PROJECT_NAME}}`
- Memory path: `~/.claude/memory/`

---

## Upgrading to Full Framework

When you're ready for agents, skills, and the full protocol:

1. Run `/setup-project` again (without "minimal")
2. This will add all agents, skills, and commands
3. Your memory will be preserved

---

## Session Management

**Resume work:** `/continue` - Loads from Memory Copilot

**End session:** Just close Claude Code - progress auto-saves

Replace {{PROJECT_NAME}} with the actual project name. Write to CLAUDE.md.

Minimal Step 5: Verify and Report

ls -la .mcp.json
ls -la CLAUDE.md
ls .claude/commands/

Report:

Minimal Setup Complete! (Memory Only)

Created:

• .mcp.json - Memory Copilot configuration
• CLAUDE.md - Project instructions (minimal)
• .claude/commands/continue.md - Resume command

Configuration:

• Memory workspace: {{PROJECT_NAME}}
• Memory path: ~/.claude/memory/

Next steps:

1. Restart Claude Code to load Memory Copilot
2. Run /mcp to verify connection
3. Test with /continue or start using memory tools directly

To upgrade to full framework later: Run /setup-project again (without saying "minimal").

Then STOP.

Remember

• Be patient and encouraging
• Run commands yourself instead of asking user to copy/paste
• Use actual paths, never placeholders in final files