Setup Project

Setup Project Skill

This skill initializes a new project for the SaaS workflow skills by creating the necessary configuration file.

Instructions for Claude

Step 1: Verify We're in a Git Repository

git rev-parse --show-toplevel

If not in a git repo:

❌ Not in a git repository

This skill must be run from within a git repository.

Please:
1. cd into your project directory
2. Initialize git if needed: git init
3. Run /setup-project again

Step 2: Check if Config Already Exists

PROJECT_ROOT=$(git rev-parse --show-toplevel)
if [ -f "$PROJECT_ROOT/.claude/project.json" ]; then
  echo "Config already exists"
fi

If config exists:

⚠️  Project configuration already exists

Found existing .claude/project.json

Options:
1. View current config
2. Overwrite with new config
3. Cancel

Which would you like to do?

Step 3: Detect Git Repository Info

git remote get-url origin

Parse the URL to extract:

• Owner: e.g., "your-org"
• Repo: e.g., "your-repo"

If no remote: ask the user for the GitHub repository details.

Step 4: Gather Project Information

Ask the user for the following information:

1. Project Name — display name used in messages and PR descriptions. Default to repo name.
2. Linear Team — use mcp__linear__list_teams to fetch teams, ask user to pick.
3. Linear Project — use mcp__linear__list_projects for the chosen team, ask user to pick.
4. GitHub Repository — owner, repo, and default branch (usually main). Auto-detect from remote.
5. Vercel Project — use mcp__vercel__list_projects, ask user to pick. Capture projectId, teamId, teamSlug, projectName. (Optional — skip if Vercel isn't used.)
6. Build Command — default npm run build, allow override.
7. Test Command — default npm test, allow override.
8. Package Manager — auto-detect: package-lock.json → npm, yarn.lock → yarn, pnpm-lock.yaml → pnpm, bun.lockb → bun.

Step 5: Display Configuration Summary

Show the user what will be created:

📋 Project Configuration Summary

Project Name: [name]
Linear Team: [team name] ([team ID])
Linear Project: [project ID]
GitHub: [owner]/[repo] (branch: [default branch])
Vercel: [project name] ([project ID])

Build Command: [build command]
Test Command: [test command]
Package Manager: [package manager]

Is this correct?

Step 6: Create Configuration File

mkdir -p "$PROJECT_ROOT/.claude"

cat > "$PROJECT_ROOT/.claude/project.json" <<EOF
{
  "projectName": "...",
  "linear": {
    "teamId": "...",
    "teamName": "...",
    "projectId": "..."
  },
  "github": {
    "owner": "...",
    "repo": "...",
    "defaultBranch": "main"
  },
  "vercel": {
    "teamId": "...",
    "teamSlug": "...",
    "projectId": "...",
    "projectName": "..."
  },
  "buildCommand": "npm run build",
  "testCommand": "npm test",
  "packageManager": "npm"
}
EOF

Step 7: Add to Version Control (Optional)

Ask the user:

📁 Add to version control?

Would you like to commit .claude/project.json to git?

Recommended — so your team can use the same configuration.

Options:
1. Yes, commit it now
2. No, I'll commit it later
3. Add to .gitignore (keep it local only)

Step 8: Display Success Message

✅ Project setup complete!

Configuration saved to: .claude/project.json

You can now use these skills:
- /quick-start    — vague backlog item → branch + plan + sub-tasks
- /new-feature    — pick a Todo item, branch, and start
- /feature-from-backlog — refine + start from backlog
- /create-pr      — open PR with auto-linking
- /project-status — cross-tool dashboard
- /backlog        — top up the backlog with new ideas
- /compact-fix    — restore context after compaction

Next: /quick-start ABC-XX

Error Handling

Linear API Access Issues

❌ Cannot access Linear

Make sure the Linear MCP server is configured and you have access to the team.

Vercel API Issues

⚠️  Cannot access Vercel — proceeding without Vercel config.

You can add Vercel info manually to .claude/project.json later.

No Projects Found

ℹ️  No projects found in Linear

Would you like to:
1. Create a new Linear project
2. Enter project ID manually
3. Skip Linear integration for now

Related Skills

• Use /project-status after setup to verify everything works
• Use /quick-start to start your first feature

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ImTaegan
• Source: ImTaegan/claude-saas-flow
• License: MIT

Install and usage instructions live in the source repository linked above.