🚀 AI Agent Handoff Framework Generator

Automatically generate AI-ready project documentation for seamless cross-chat continuity. Works with React, Python, Node.js, Go, or any project.

What It Does

This script generates 14 customized files for any new project in under 2 minutes:

AI Framework Files (Generic)

• AI_MASTER.md - Master onboarding protocol
• AI_SYSTEM_PROMPT.md - Execution principles
• AI_CONTEXT.md - Architecture for agents
• AI_RULES.md - Operating constraints
• DECISIONS.md - Settled decisions tracker
• PROGRESS.md - Task state tracking
• SCRATCHPAD.md - Mid-task resume state
• AUDIT_LOG.md - Activity log
• AGENT_SESSION_TEMPLATE.md - Log entry format

Project Setup Files (Customized per project type)

• .env.example - Tailored for React/Python/Node/Go
• .gitignore - Tailored for project type
• .cursorrules - AI development rules
• README.md - Setup guide

Why This Matters

Problem: When working with AI agents across multiple chats, context is lost every time you start a new conversation.

Solution: This generator creates a repo-level documentation system that:

• ✅ Survives across chats (stored in git repo, not chat history)
• ✅ Works with any AI model (Claude, ChatGPT, Cursor, etc.)
• ✅ Automatically tailored to your project type
• ✅ Enforces continuity (audits, progress tracking, handoffs)
• ✅ Zero manual editing needed

Installation

Option 1: Run Directly

node generate-ai-framework.js

Option 2: Install Globally (optional)

npm install -g /path/to/ai-framework-generator

# Then run anywhere
ai-framework-gen

Option 3: Use as NPM Dependency

npm install ai-framework-generator --save-dev

# Add to package.json scripts
"scripts": {
  "generate-framework": "node node_modules/ai-framework-generator/generate-ai-framework.js"
}

# Run
npm run generate-framework

Quick Start

Step 1: Navigate to Your Project

cd /path/to/your/new/project

Step 2: Run the Generator

node generate-ai-framework.js

Step 3: Answer the Questions

The script will ask:

Project name (e.g., MyAwesomeApp): 
One-line description: 
Tech stack (e.g., React 19 + TypeScript): 
Main entry point (e.g., src/App.tsx): 

What kind of project is this?
1) React/Frontend
2) Python (FastAPI/Django/Flask)
3) Node.js/Backend
4) Go
5) Other
Pick (1-5): 

[Additional questions based on project type...]

Step 4: All Files Generated!

✨ Framework generated successfully!

📁 Generated files:
  ✓ AI Framework (9 files)
  ✓ Project Setup (.env.example, .gitignore, .cursorrules, README.md)

🎯 Next steps:
  1. Review the generated files
  2. Edit AI_CONTEXT.md to add architecture details
  3. Update PROGRESS.md with your first task
  4. Commit all files to git
  5. Start using the framework!

How It Customizes

The script asks about your project to customize all files:

What You Tell It

• Project type: React, Python, Node.js, Go, etc.
• Framework: Django, FastAPI, Flask, Express, etc.
• Features: Database? Authentication? External APIs? Tailwind CSS?

What It Customizes

• .env.example: Pre-filled variables for your project type
• .gitignore: Patterns specific to React/Python/Node/Go
• .cursorrules: Development rules matching your tech stack
• README.md: Setup instructions for your project type
• AI_CONTEXT.md: Architecture template for your tech stack

Example: React + Firebase Project

Project name: MyAuthApp
Project type: React
Do you use authentication? jwt/oauth: oauth
Do you call external APIs? firebase: Yes

Generates:

• .env.example with VITE_FIREBASE_API_KEY, VITE_AUTH_CLIENT_ID, etc.
• .cursorrules with React hooks, TypeScript, Firebase patterns
• .gitignore with React-specific patterns
• README.md with React/Vite/Firebase setup instructions

Example: Python FastAPI + PostgreSQL

Project name: UserAPI
Project type: Python
Python framework: FastAPI
Database: postgresql

Generates:

• .env.example with DATABASE_URL, JWT_SECRET, etc.
• .cursorrules with FastAPI, async/await, type hints rules
• .gitignore with Python/venv patterns
• README.md with FastAPI/PostgreSQL setup

File Descriptions

AI Framework Files

| File | Purpose | |---|---| | AI_MASTER.md | Start here - tells agents how to work | | AI_SYSTEM_PROMPT.md | Quality standards and principles | | AI_CONTEXT.md | Your project architecture (agent-readable) | | AI_RULES.md | Don't-do list and constraints | | DECISIONS.md | Locked-in architecture decisions | | PROGRESS.md | Current task status | | SCRATCHPAD.md | Resume state if mid-task | | AUDIT_LOG.md | Append-only activity log | | AGENT_SESSION_TEMPLATE.md | Format for audit entries |

Project Files

| File | Purpose | |---|---| | .env.example | Environment variables template | | .gitignore | Git ignore rules | | .cursorrules | Development practices | | README.md | Project setup guide |

Usage Examples

New React Project

cd ~/projects/my-react-app
node ../ai-framework-generator/generate-ai-framework.js
# Answer prompts...
git add .
git commit -m "chore: add AI framework"

New Python FastAPI Project

cd ~/projects/my-api
node ~/Documents/Projects/ai-framework-generator/generate-ai-framework.js
# Answer prompts...
git add .
git commit -m "chore: add AI framework"

Existing Project

# Go to project root
cd ~/projects/existing-app

# Run generator in a new branch
git checkout -b feat/add-ai-framework
node ../ai-framework-generator/generate-ai-framework.js

# Review generated files
git add .
git commit -m "chore: add AI framework"
git push

After Generation

1. Review & Customize

Open AI_CONTEXT.md and fill in details about your architecture:

## Folder structure
- src/components/ - React components
- src/services/ - API calls
- src/utils/ - Helpers

2. Set First Task

Edit PROGRESS.md:

## In progress
- Phase 1: Setup project structure
- Phase 2: Create authentication

3. Commit to Git

git add .
git commit -m "chore: initialize AI handoff framework"
git push

4. Use in AI Chats

When starting a new chat:

Continue MyAwesomeApp project.
Task: Implement user login.
Follow AI_MASTER.md protocol.

The AI will automatically:

1. Read AI_MASTER.md → learns the protocol
2. Read PROGRESS.md → sees current status
3. Read AI_CONTEXT.md → understands architecture
4. Execute with full context
5. Update PROGRESS.md + AUDIT_LOG.md

Project Types Supported

React/Frontend

• Customizes for React, TypeScript, Vite
• Includes Tailwind CSS option
• React Testing Library patterns

Python

• FastAPI: async/await, Pydantic, OpenAPI
• Django: ORM, migrations, Django patterns
• Flask: blueprints, requests patterns

Node.js

• Express with TypeScript
• Database support (PostgreSQL, MongoDB)
• Jest/Vitest testing

Go

• Project structure (cmd/, internal/, pkg/)
• Connection pooling, concurrency patterns
• go test -race standards

Other/Generic

• Creates basic templates
• Can be customized manually

File Structure After Generation

your-project/
├── AI_MASTER.md
├── AI_CONTEXT.md
├── AI_RULES.md
├── AI_SYSTEM_PROMPT.md
├── DECISIONS.md
├── PROGRESS.md
├── SCRATCHPAD.md
├── AUDIT_LOG.md
├── AGENT_SESSION_TEMPLATE.md
├── .env.example
├── .gitignore
├── .cursorrules
├── README.md
├── [your other files...]

Advanced: Customization

After generation, you can customize:

1. AI_CONTEXT.md: Add specific architecture details
2. AI_RULES.md: Add project-specific constraints
3. .cursorrules: Add team-specific practices
4. .env.example: Add more variables
5. PROGRESS.md: Define your actual phases

Troubleshooting

"Command not found: node"

Install Node.js from https://nodejs.org/

Files already exist

The generator will overwrite existing files. Back them up first if needed.

Need to regenerate

Just run the script again and answer the prompts. It will create new files.

Support

• See generated README.md for project-specific help
• See generated AI_MASTER.md for AI collaboration guidelines
• Check .cursorrules for development standards

License

MIT

Built to solve the AI continuity problem across chats and agents.