Automated Claude Code configuration setup for existing projects with comprehensive task management, git worktree workflows, and testing infrastructure.

Demo

Requirements

Node.js 18+ (ESM support required)
Git (must be installed and configured)
npm or yarn package manager
Existing project with package.json
Git initialized (git init)
Git remote configured (git remote add origin <url>)

Installation

npx @fullstacktard/claude-flow init

Quick Start

Add Claude Code configuration to an existing project

# Navigate to your existing project
cd your-project

# Run the init command
npx @fullstacktard/claude-flow init

What happens during init:

The CLI will:

Prompt for workflow preferences:
- Git sync before each task? (default: yes)
- Use pull requests instead of direct merges? (default: yes)
Create complete project structure:
- src/, tests/, docs/, data/, scripts/ directories
- Complete backlog system with tasks/, completed/, drafts/, templates/
Install Claude Code configuration:
- .claude/settings.json with permissions
- .claude/worktree-setup.md with git worktree workflows
- .claude/backlog-reference.md with task management guide
- .claude/testing-setup.md with testing standards
- Notification scripts (notify.sh, enhanced-notify.sh)
Set up development files:
- CLAUDE.md - Base AI instructions (auto-managed, don't edit!)
- CLAUDE_PROJECT.md - Your project-specific customizations
- vitest.config.js - Testing configuration
- .gitignore - Sensible defaults (only if missing)
- .env - Environment template (only if missing)
- main.js - Entry point template
Configure package.json:
- Add Vitest and testing scripts
- Set "type": "module" for ESM support
- Preserve all existing scripts and dependencies
Install git hooks:
- Pre-commit hook for task validation
Install backlog CLI:
- Automatically installs backlog.md CLI globally
- Configured with your project name

Typical Workflows

Basic Development Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. Run init                                                 │
│    npx @fullstacktard/claude-flow init                      │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Customize CLAUDE_PROJECT.md                              │
│    Add your API endpoints, DB schema, deployment info       │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Tell Claude what to build                                │
│    Claude reads your context and creates structured tasks   │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Claude works on tasks                                    │
│    Creates worktrees, implements features, runs tests       │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ 5. Review and merge                                         │
│    Claude creates PRs, you review, merge to main            │
└─────────────────────────────────────────────────────────────┘

Multi-Project Setup

Project A (crypto-trading-bot)
    │
    ├─ npx @fullstacktard/claude-flow init
    ├─ Edit CLAUDE_PROJECT.md (add trading API details)
    └─ Claude builds features

Project B (nft-marketplace)
    │
    ├─ npx @fullstacktard/claude-flow init
    ├─ Edit CLAUDE_PROJECT.md (add blockchain config)
    └─ Claude builds features

Same Claude behavior, different project context!

Use Case Examples

Example 1: Solo Crypto Developer

Scenario: Building 3 different Solana DeFi projects simultaneously.

Before this package:

Copy-paste CLAUDE.md between projects
Re-explain git workflow every session
Context limits hit constantly
Inconsistent task structure

After this package:

# Project 1: Token swap
cd token-swap && npx @fullstacktard/claude-flow init
# Edit CLAUDE_PROJECT.md with Solana program details

# Project 2: NFT staking
cd nft-staking && npx @fullstacktard/claude-flow init
# Edit CLAUDE_PROJECT.md with staking logic

# Project 3: DAO governance
cd dao-governance && npx @fullstacktard/claude-flow init
# Edit CLAUDE_PROJECT.md with governance rules

Result: Same consistent Claude behavior across all 3 projects. Context stays lean. Task isolation via worktrees means no conflicts.

Example 2: Small Development Team

Scenario: 2-person team building a fullstack app. Want Claude to help both developers consistently.

Setup:

# Team lead runs once
npx @fullstacktard/claude-flow init

# Answer prompts:
# Git sync? Yes
# Pull requests? Yes

# Edit CLAUDE_PROJECT.md with:
# - API endpoints
# - Database schema
# - Testing requirements
# - Code review process

# Commit everything to git
git add .
git commit -m "Add Claude configuration"
git push

Other team member:

# Clone and get instant Claude setup
git clone <repo>
cd <repo>

# Claude immediately understands:
# - Project structure
# - Task workflow
# - Testing standards
# - PR requirements

Result: Both developers get identical Claude behavior. No setup discussions needed.

Example 3: Rapid Prototyping

Scenario: Need to validate 5 different startup ideas quickly.

Traditional approach: Spend 2 hours per project configuring Claude, writing docs, setting up workflows.

With this package:

# Idea 1: 5 minutes to full Claude setup
mkdir idea-1 && cd idea-1
npm init -y && git init && git remote add origin <url>
npx @fullstacktard/claude-flow init
# Tell Claude what to build

# Idea 2: 5 minutes to full Claude setup
mkdir idea-2 && cd idea-2
npm init -y && git init && git remote add origin <url>
npx @fullstacktard/claude-flow init
# Tell Claude what to build

# ... repeat for ideas 3-5

Result: Go from idea to working prototype in hours, not days. Spend time building, not configuring.

Best Practices

DO:

Run init in existing projects only - Requires package.json and git
Edit CLAUDE_PROJECT.md for customizations - This file is yours to modify
Let Claude handle task workflows - The system guides Claude through the workflow
Use the backlog system - Structured tasks keep Claude focused
Commit configuration files - Share setup with your team via git
One init per project - Each project gets its own configuration

DON'T:

Edit CLAUDE.md directly - Auto-managed, will be overwritten on updates
Run init without package.json - Won't work without an existing project
Run init without git - Git is required for the workflow system
Ignore the task template - Standardized format helps Claude understand requirements
Skip CLAUDE_PROJECT.md - Add project-specific context so Claude knows your setup
Run init in this package's source directory - Only for consuming projects

COMMON USES:

For solo developers:

Maintain consistent Claude behavior across multiple projects
Skip manual Claude Code configuration for each project
Get opinionated defaults that work
Ship faster without configuration overhead

For teams:

Share Claude configuration via git
Standardize task structure across the team
Consistent AI assistance for all team members
Onboard new developers instantly

For rapid prototyping:

Spin up new projects with full Claude integration in minutes
Focus on building, not configuration
Lean context management for faster iterations
Validate ideas quickly

For agencies/consultants:

Consistent setup across client projects
Professional workflows out of the box
Easy handoff (configuration is documented)
Faster project delivery

What's Included

Core Files

CLAUDE.md - Comprehensive AI instructions (auto-managed from npm package, never edit!)
CLAUDE_PROJECT.md - Your project-specific customizations (edit this!)
.claude/ - Complete Claude Code configuration directory
backlog/ - Full task management system
scripts/ - Task validation and utility scripts

Key Features

Backlog Task Management - Complete task workflow system
Git Worktree Workflows - Isolated development environments
Smart Configuration - Conditional workflows based on preferences
Testing Infrastructure - Vitest setup with ESM support
Task Templates - Standardized task structure
Validation Scripts - Enforce task quality
Standard Structure - Consistent project organization
Workflow Flexibility - Choose PR-based or direct merge workflows

Project Structure After Init

your-project/
├── CLAUDE.md                      # Base AI instructions (auto-managed, DON'T EDIT)
├── CLAUDE_PROJECT.md              # Your custom rules (EDIT THIS)
├── .env                           # Environment variables (created if missing)
├── .gitignore                     # Git exclusions (created if missing)
├── main.js                        # Entry point
├── package.json                   # Updated with test scripts
├── vitest.config.js               # Test configuration
├── .claude/
│   ├── settings.json              # Claude permissions & hooks
│   ├── worktree-setup.md          # Git worktree workflows
│   ├── backlog-reference.md       # Task management guide
│   ├── testing-setup.md           # Testing standards
│   ├── notify.sh                  # Basic notifications
│   └── enhanced-notify.sh         # Enhanced notifications
├── backlog/
│   ├── tasks/                     # Active tasks
│   ├── completed/                 # Archived tasks
│   ├── drafts/                    # Draft tasks
│   ├── templates/
│   │   └── task-template.md       # Task structure template
│   └── config.yml                 # Backlog configuration
├── scripts/
│   ├── validate-task.js           # Task validation
│   └── update-project-structure.js # Project file sync
├── src/                           # Source code
├── tests/                         # Test files
├── docs/                          # Documentation
└── data/                          # Data files (git-ignored)

Workflow Customization

During Installation

When you run init, you'll be asked:

"Sync with main before starting each task?"
- Yes (default): Adds mandatory git sync instructions
- No: Skips sync requirements in workflows
"Use pull requests instead of direct merges?"
- Yes (default): Enforces PR-based workflow
- No: Allows direct merges to main

Effect on Templates

Your choices modify the generated templates:

If git sync is disabled:

CLAUDE.md - Removes "MANDATORY GIT SYNC" section
worktree-setup.md - Removes sync instructions
backlog-reference.md - Removes sync steps

If PRs are disabled:

CLAUDE.md - Changes to "Direct merges allowed"
task-template.md - Updates acceptance criteria
Workflow instructions use direct merge instead of gh pr create

Configuration

Project Customization

NEVER edit CLAUDE.md directly! It's auto-managed from the npm package.

Instead, edit CLAUDE_PROJECT.md to add:

Project-specific API endpoints
Custom commands and scripts
Domain-specific rules
External service configurations
Team conventions
Database schemas
Deployment procedures

Example:

# Project-Specific Configuration

## API Endpoints

- Production: https://api.myproject.com
- Staging: https://staging.myproject.com

## Database

- Schema: PostgreSQL 15
- Migration tool: `npm run migrate`
- Seed data: `npm run seed`

## Deployment

- Production: `npm run deploy:prod`
- Requires: AWS_ACCESS_KEY, AWS_SECRET_KEY

## Restrictions

- Never modify `/legacy` directory
- Always use custom logger at `src/utils/logger.js`
- All API calls must go through `src/api/client.js`

.gitignore Setup

The package creates a .gitignore file (if missing) with:

node_modules/
.env
.env.local
.env.*.local
data/

Note: CLAUDE.md and .claude/ are tracked in git so team members get the configuration.

How It Works

Task Management System

The setup includes a complete backlog.md integration that structures how Claude works with tasks:

What Claude gets:

.claude/backlog-reference.md - Complete guide on task workflows
backlog/templates/task-template.md - Standardized task format
scripts/validate-task.js - Automated task validation

How Claude uses it:

Reads task files to understand requirements
Follows structured format (Description, Acceptance Criteria, Implementation Plan)
Tracks progress in the task file's Progress Log
Validates tasks before marking complete

Task structure includes:

Description (what and why)
Implementation Summary (filled after completion)
Acceptance Criteria (checkboxes for validation)
Implementation Plan (step-by-step approach)
Git Workflow (branch and merge strategy)
Progress Log (real-time updates)

Claude doesn't need manual instructions - the task template guides the entire workflow.

Git Worktree Integration

The system provides Claude with comprehensive worktree workflows:

What Claude gets:

.claude/worktree-setup.md - Complete worktree guide with examples
Pre-configured commands and workflows
Isolation strategy for parallel task work

Benefits:

Work on multiple tasks simultaneously without conflicts
Isolated dependencies per task
No branch switching disruption
Clean separation of concerns

How it's organized:

your-project/                    # Main repository
../your-project-worktrees/
  ├── task-42/                   # Worktree for task 42
  ├── task-43/                   # Worktree for task 43
  └── task-44/                   # Worktree for task 44

Claude understands:

When to create worktrees (new task started)
Where to create them (outside main repo)
How to work within them (isolated development)
When to merge back (task completed)

No manual explanation needed - Claude reads the workflow guide and follows it.

Testing Infrastructure

Vitest Configuration

The package includes vitest.config.js with:

ESM support out of the box
Test file patterns (**/*.test.js, **/*.spec.js)
Coverage configuration
10-second default timeout

Test Commands (added to package.json)

{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run"
  }
}

Writing Tests

import { describe, it, expect } from 'vitest';

describe('User Authentication', () => {
  it('should validate credentials', () => {
    expect(validateUser('user', 'pass')).toBe(true);
  });
});

See .claude/testing-setup.md for standards.

Automatically Installed

When running init:

backlog.md CLI - Task management (installed globally via npm)
Vitest - Test framework (installed as dev dependency)

Manual Installation Recommended

GitHub CLI (for PR workflows):

# macOS
brew install gh

# Authenticate
gh auth login

Troubleshooting

"No Project Detected"

# Ensure package.json exists
npm init -y

# Then run init
claude-flow init

"Git Not Initialized"

# Initialize git
git init

# Then run init
claude-flow init

"Git Remote Not Configured"

# Add remote
git remote add origin https://github.com/user/repo.git

# Or create with GitHub CLI
gh repo create

# Then run init
claude-flow init

Task Validation Errors

# Manually validate task
node scripts/validate-task.js backlog/tasks/task-42-*.md

Permission Issues

# Install globally with appropriate permissions
sudo npm install -g @fullstacktard/claude-flow

Updating the Package

For Users

# Update to latest version
npm update -g @fullstacktard/claude-flow

# Or with npx (always uses latest)
npx @fullstacktard/claude-flow@latest init

What Gets Updated

When you reinstall or update:

Latest templates downloaded
New CLI features available
Bug fixes applied

Your customizations are safe:

CLAUDE_PROJECT.md is never touched
.gitignore is only created if missing
.env is only created if missing
Existing configs preserved

Philosophy

The Three-File System

CLAUDE.md (Base) - Managed by npm package, never edit
CLAUDE_PROJECT.md (Custom) - Your project rules, always preserved
.claude/* (Reference) - Detailed guides and workflows

Task-Driven Development

Every feature is a task
Tasks have clear acceptance criteria
Validation before implementation
Documentation before completion
Progress tracking in real-time

Git Worktree First

One task = one worktree
Isolated environments
Parallel development
Clean branch management

License

Keywords

FAQs

What is @fullstacktard/claude-flow?

Is @fullstacktard/claude-flow well maintained?

Package last updated on 06 Oct 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@fullstacktard/claude-flow