How to onboard existing project to Puffin

[kurochig]

I understand how to start a new project. Could you, please, provide a step-by-step guide on onboarding an existing project to Puffin? I'd like to continue project development via Puffin from a stable working state of an application and plan the next sprint. How to educate Puffin about the project?

[github-actions[bot]]

Onboarding an Existing Project to Puffin

Here's a step-by-step guide to onboard your existing project to Puffin and prepare it for sprint-based development:

Step 1: Initialize Puffin in Your Project

# Navigate to your existing project directory
cd /path/to/your/existing/project

# Start Puffin (this will create the .puffin/ directory)
npm start -- $(pwd)
# or from Puffin's directory:
npm start -- /path/to/your/existing/project

When you first run Puffin on an existing project, it will automatically create the .puffin/ directory with initial configuration files.

Step 2: Configure Project Context

Set Branch Contexts

1. Open the Claude Config plugin (gear icon in sidebar)
2. Configure context for each branch type based on your project:
   • Specifications: Add project requirements, business rules
   • Architecture: Describe your current tech stack, patterns, structure
   • UI: Frontend framework, design system, component patterns
   • Backend: API patterns, database schema, services
   • Fullstack: Integration patterns, deployment setup

Example Architecture Context:

This is a React/Node.js e-commerce application:
- Frontend: React 18, TypeScript, Tailwind CSS
- Backend: Express.js, PostgreSQL, Prisma ORM
- Authentication: JWT with refresh tokens
- Payment: Stripe integration
- Deployment: Docker on AWS ECS

Step 3: Create Initial Architecture Documentation

Start a Specifications or Architecture conversation to document your current state:

Prompt Example:

Please analyze my existing project structure and create comprehensive documentation covering:
1. Current architecture overview
2. Key components and their responsibilities
3. Database schema and relationships
4. API endpoints and patterns
5. Frontend component structure
6. Build and deployment process

Focus on documenting what exists rather than suggesting changes.

This conversation will be saved and provide context for future development sessions.

Step 4: Build Your Backlog

Extract User Stories from Existing Features

Use Puffin's AI-powered story derivation:

Prompt in Specifications branch:

Based on my existing application, help me create user stories for:
1. Current implemented features (mark as completed)
2. Partially implemented features (mark as in-progress)
3. Known bugs or issues (for bug fix stories)
4. Planned enhancements from my TODO comments or issues

Please structure each as: "As a [user], I want [goal] so that [benefit]"

Manual Story Creation

1. Go to User Stories section
2. Click "Create Story"
3. Add stories for your next development phase
4. Define acceptance criteria for each story

Step 5: Set Up Your Current Git State

1. Ensure you're on your main/stable branch
2. Commit any pending changes
3. Use Puffin's git integration to view your current branch status
4. Consider creating a new branch for your first Puffin-managed sprint

Step 6: Create Your First Sprint

1. Navigate to Sprints section
2. Click "Create Sprint"
3. Select user stories from your backlog
4. Set sprint goals and duration
5. Start the sprint

Step 7: Test the Integration

Run a Small Test Session

Start with a simple, low-risk task:

Example test prompt:

Please review the current project structure and suggest improvements to the README.md file. 
Focus only on documentation - no code changes needed.

This helps you verify:

• Claude Code CLI integration works
• Context is being passed correctly
• Responses are captured and stored

Step 8: Educate Puffin About Your Codebase

Use Code Review Sessions

Start Code Reviews conversations to have Claude analyze your existing code:

Please review my authentication module in /src/auth/ and:
1. Identify the current patterns and conventions
2. Note any potential security concerns
3. Document the authentication flow
4. Suggest areas for improvement (but don't implement yet)

Gradual Context Building

As you work on new features, Puffin will naturally learn more about your project through:

• Conversation history
• Code changes Claude makes
• Architecture discussions
• Bug fix sessions

Pro Tips for Existing Projects

Start Small

• Begin with documentation or small improvements
• Use Specifications branch for planning before coding
• Test Puffin's understanding with code reviews

Leverage History

• Each conversation builds context for future sessions
• Use branched conversations to separate concerns
• Reference previous conversations in new prompts

Incremental Adoption

You don't need to migrate everything at once:

• Continue using your existing workflow for urgent fixes
• Use Puffin for planned feature development
• Gradually shift more development activities to Puffin

Git Integration

• Consider committing the .puffin/ directory to share context with team members
• Use Puffin's branch management for feature development
• Leverage automatic commit message generation

Common Onboarding Challenges

Large Codebase: Start with high-level architecture documentation, then drill down into specific modules as needed.

Complex Dependencies: Document your build process and deployment requirements in the Architecture branch context.

Team Workflow: Establish conventions for how your team will use branched conversations and sprint management.

Legacy Code: Use Code Review sessions to gradually document and understand older parts of the codebase.

Once you complete this onboarding process, Puffin will have sufficient context about your project to provide intelligent assistance for your ongoing development sprints!

---

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 understand how to start a new project. Could you, please, provide a step-by-step guide on onboarding an existing project to Puffin? I'd like to continue project development via Puffin from a stable working state of an application and plan the next sprint. How to educate Puffin about the project?

Basically, start puffin from its directory, choose the directory of your existing project and Puffin will add a .puffin/ directory where it will keep everything.

There is a new release v3.1.0 which implements the latest Google paper on "double-prompts" for non reasoning LLMs.

Let me know if you have any other questions. Feel free to connect directly if you have any questions. https://www.linkedin.com/in/jdubray/

[github-actions[bot]]

Thank you for the clarification! You're absolutely right - the onboarding process is much simpler than I made it seem.

Simple Onboarding for Existing Projects

Quick Start

1. Start Puffin from its directory:

   npm start

2. Select your existing project directory when prompted (or pass it as an argument):

   npm start -- /path/to/your/existing/project

3. Puffin automatically creates the .puffin/ directory in your project with all necessary configuration files.

That's it! Puffin is now ready to work with your existing project.

Next Steps

Once initialized, you can:

• Start conversations in different branches to understand your codebase
• Create user stories for your next development phase
• Set up your first sprint
• Use the Claude Config plugin to add project-specific context

The .puffin/ directory will store all conversations, user stories, and project context as you work.

About v3.1.0

Interesting! The "double-prompts" implementation from the latest Google paper sounds like it could improve how non-reasoning LLMs handle complex development tasks. This should enhance the quality of responses when working with your existing codebase.

Thanks for the correction - the onboarding really is that straightforward! Do you have any specific questions about working with your existing project once Puffin is set up?

---

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