How do I start a project with Puffin?

[jdubray]

How do I start a project with Puffin? Can you provide a step-by-step guide, starting with a new directory?

[github-actions[bot]]

Starting a New Project with Puffin

Here's a step-by-step guide to get started with Puffin on a new project:

Prerequisites

1. Install Node.js 18+
2. Install Claude Code CLI and authenticate it:

   # Install Claude Code CLI (if not already installed)
   npm install -g @anthropic-ai/claude-3-cli
   
   # Authenticate with your API key
   claude auth

3. Ensure Git is installed

Step-by-Step Setup

1. Clone and Set Up Puffin

# Clone the Puffin repository
git clone https://github.com/jdubray/puffin.git

# Navigate to Puffin directory
cd puffin

# Install dependencies
npm install

2. Create Your New Project Directory

# Create your project directory (anywhere you want)
mkdir ~/my-new-project
cd ~/my-new-project

# Initialize as a git repository (recommended)
git init

3. Launch Puffin for Your Project

# From the puffin directory, start Puffin pointing to your project
npm start -- ~/my-new-project

# Or in development mode for more verbose logging
npm run dev -- ~/my-new-project

4. First-Time Project Setup

When Puffin launches for a new project:

1. Puffin will automatically create a .puffin/ directory in your project with:

   • config.json - Project configuration
   • puffin.db - SQLite database
   • history.json - Conversation history
   • user-stories.json - Backlog management

2. Configure your project in the GUI:

   • Set project name and description
   • Define the tech stack you'll be using
   • Set up branch contexts (optional, but recommended)

5. Start Your First Conversation

1. Choose a conversation branch (e.g., "Specifications" for planning)
2. Enter your initial prompt, such as:

   I want to create a [describe your project]. 
   Help me plan the architecture and create a development roadmap.
   

3. Let Claude Code respond and build from there

6. Organize with User Stories (Optional but Recommended)

1. Use Puffin's "Derive Stories" feature to convert your initial planning into structured user stories
2. Create a sprint from your backlog
3. Use Automated Sprint Implementation to let Claude orchestrate the development

Example First Session

# 1. Create project
mkdir ~/todo-app
cd ~/todo-app
git init

# 2. Start Puffin (from puffin directory)
cd /path/to/puffin
npm start -- ~/todo-app

# 3. In Puffin GUI:
# - Branch: "Specifications"
# - Prompt: "I want to create a todo application with user authentication, 
#           task management, and a modern web interface. Help me plan the 
#           architecture and tech stack."

Tips for Success

• Start with Specifications branch for planning and requirements
• Use the GUI Designer if you want visual mockups
• Enable Sprint Management for structured development
• Commit the .puffin/ directory to git so team members can share context
• Use branched conversations to keep different concerns (UI, Backend, etc.) organized

The key is that Puffin provides the orchestration layer while Claude Code CLI does the actual code generation and project building!

---

This response was generated by the Puffin Q&A Bot powered by Claude. For complex questions or issues, please open a GitHub Issue.

[jdubray]

I believe you cannot use a node version greater than 20 because of the native SQLite library. Could you also explain how to start with the executable (Windows, Mac, Linux), when you don't want to install the whole project?