Comet Apps Agent Framework

Autonomous AI agent that builds and operates SaaS products using the SaaS Boilerplate.

Introduction

The Agent Framework is a Dockerized orchestration system that uses Claude Code (Anthropic's coding agent) to autonomously build, review, and deploy full-stack SaaS applications — from an empty repo to a live product.

What it does

You give it a one-line description like "Build a habit tracker with streaks and a calendar heatmap", and the framework takes it from there. It spins up a Docker container, clones a production-ready SaaS Boilerplate, initializes a structured Knowledge Template for memory and state, then runs through a multi-role pipeline — Initiator → Planner → Developer → Reviewer → Marketer → Deployer — cycling Claude Code with role-specific prompts until the product is built and deployed.

How it works

The framework is built around three core ideas:

Role-based prompting — Instead of one massive prompt, the agent assumes distinct roles (planner, developer, reviewer, etc.), each with focused instructions and responsibilities. The orchestrator automatically selects the right role based on the project's current phase.
Knowledge-driven state — The agent reads and writes to a .knowledge/ directory inside the project repo. This structured store (JSON files for context, work items, decisions, and metrics) acts as persistent memory across cycles, so the agent always knows what it's done, what's next, and why decisions were made. The knowledge structure is initialized from the Knowledge Template.
Boilerplate-first development — Every product starts from the SaaS Boilerplate, which provides authentication (Clerk), database (MongoDB), payments (Stripe), UI (Tailwind + shadcn/ui), and deployment (Vercel) out of the box. The agent extends this foundation rather than building from scratch, so it can focus on product-specific features.

The ecosystem

This repo is one piece of a three-part system:

Repository	Purpose
Agent Framework (this repo)	Orchestration engine — Docker container, role prompts, state machine, Claude Code integration
SaaS Boilerplate	Product template — Next.js 15, Clerk, MongoDB, Stripe, Tailwind, shadcn/ui
Knowledge Template	Agent memory — structured JSON store for context, work tracking, decisions, and metrics

The framework clones the boilerplate to create a new product repo, initializes the knowledge template inside it, then iteratively builds features until the product is deployed to Vercel.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     Agent Container                              │
│                                                                  │
│  1. Initialize/clone project repository                          │
│  2. Load knowledge from .knowledge/                              │
│  3. Read role-specific instructions                              │
│  4. Run Claude Code to execute tasks                             │
│  5. Update .knowledge/ with progress                             │
│  6. Commit and push changes                                      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Project Repository                   SaaS Boilerplate (fork)
       │                                     │
       │  ┌─────────────────────────────────┘
       │  │
       ▼  ▼
┌──────────────────────────────────────────────────────┐
│                  Product Instance                     │
│                                                       │
│  /project/                                            │
│  ├── .knowledge/          ← Agent memory & state     │
│  │   ├── context/                                     │
│  │   ├── work/                                        │
│  │   ├── decisions/                                   │
│  │   └── metrics/                                     │
│  │                                                    │
│  ├── app/                 ← Next.js routes           │
│  ├── components/          ← React components         │
│  ├── lib/                 ← Utilities & DB           │
│  ├── config/              ← Plans & settings         │
│  └── CLAUDE.md            ← Agent instructions       │
│                                                       │
└──────────────────────────────────────────────────────┘

Quick Start

Prerequisites

Docker installed
Anthropic API key with Claude Code access
(Optional) GitHub token for pushing changes

Option 1: Local Mode (Quick Testing)

Uses mounted volumes - good for development and testing.

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

# Or create .env file
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

# Build and run
docker compose build
docker compose up

# Check output
ls -la output/
cd output && npm install && npm run dev

Option 2: GitHub Mode (Full Autonomy)

Clones repos from GitHub and pushes changes back.

# Create .env with all variables
cat > .env << EOF
ANTHROPIC_API_KEY=sk-ant-...
GITHUB_TOKEN=ghp_...
PROJECT_NAME=my-saas-product
PROJECT_BRANCH=main
KNOWLEDGE_TEMPLATE=your-org/knowledge-template
EOF

# Run
docker compose --profile github up

Running the Full Pipeline

Smart Orchestration (Recommended)

Run the full pipeline inside a single Docker container - no external scripts needed:

# Set up your .env file first, then:
ORCHESTRATE_MODE=smart \
BUILD_TASK="Build a habit tracker app" \
docker compose up --build

Or add to your .env:

ORCHESTRATE_MODE=smart
BUILD_TASK="Build a habit tracker with streaks and calendar heatmap"
MAX_CYCLES=25
MAX_DEV_CYCLES=6
REVIEW_EVERY=3

Then just:

docker compose up --build

The container will:

Set up the project repo and knowledge store (once)
Run the orchestration loop internally
Cycle through roles based on phase until complete
Exit when done or stuck

GitHub Actions (Cloud Deployment)

Run the agent in the cloud using GitHub Actions - no local Docker required:

# 1. Set up secrets in GitHub (Settings → Secrets → Actions):
#    - ANTHROPIC_API_KEY
#    - GH_PAT (Personal Access Token with repo scope)
#    - VERCEL_TOKEN (optional, for deployments)

# 2. Trigger via GitHub UI:
#    Actions → 🤖 Run Comet Agent → Run workflow → Fill form

# 3. Or trigger via API:
curl -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/YOUR_USER/cometapps/actions/workflows/run-agent.yml/dispatches \
  -d '{
    "ref": "main",
    "inputs": {
      "project_name": "habit-tracker",
      "build_task": "Build a habit tracker with streaks",
      "orchestrate_mode": "smart"
    }
  }'

See .github/README.md for full documentation on GitHub Actions workflows.

Example output:

🎯 [ORCHESTRATOR] Cycle 1 of 20
   Phase: new → Role: initiator
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎭 Running: INITIATOR
...

🎯 [ORCHESTRATOR] Cycle 2 of 20
   Phase: initialized → Role: planner
...

🎯 [ORCHESTRATOR] Cycle 5 of 20
   Phase: building → Role: developer
...

Phase State Machine

The orchestrator reads .knowledge/context/current.json and routes based on phase:

Phase	Next Role	Description
`new`	INITIATOR	Fresh project
`initialized`	PLANNER	Needs task breakdown
`planned` / `building`	DEVELOPER	Build features (multiple cycles)
`reviewed` / `needs_fixes`	DEVELOPER	Address review feedback
`ready_for_staging`	MARKETER	Update marketing pages first
(after marketer)	DEPLOYER	Then deploy to staging
`deployment_failed`	DEVELOPER	Fix deployment issues
`staged` / `deployed`	✓ DONE	Success!
`blocked`	✗ ABORT	Something went wrong

Full Pipeline:

INITIATOR → PLANNER → DEVELOPER (×N) → REVIEWER → DEVELOPER (fixes)
    → MARKETER → DEPLOYER → ✓ DONE

Single Role Mode

Run just one role (original behavior):

# Run a specific role
AGENT_ROLE=developer docker compose up --build

# Or for deployment only
AGENT_ROLE=deployer docker compose up --build

Helper Scripts (for local development)

These scripts run on your host machine and call docker compose repeatedly:

# Interactive - prompts y/n before each role
./orchestrate.sh my-project "Build a TODO app"

# Continuous development loop
./auto-cycle.sh my-project

How It Works

Agent Roles

The framework supports different operational modes:

Role	Purpose	Trigger
initiator	Project setup from template	New projects only
planner	Strategic planning, prioritization	After init
developer	Build features, fix bugs, write code	Main work loop
reviewer	Code review, quality checks	Every N dev cycles
marketer	Update landing page & marketing copy	Before deployment
deployer	Vercel setup, branch promotions	When ready for staging

Git Branching Strategy

The agent uses a three-branch release workflow:

release/dev     →    release/stage    →    release/prod
(Agent works)        (Auto-promoted)       (Human-only)

Branch	Who Controls	Vercel Environment
`release/dev`	Agent (all roles)	Preview
`release/stage`	DEPLOYER role	Preview (staging alias)
`release/prod`	Human only	Production

Use the helper script for branch management:

./git-workflow.sh status            # Show branch status
./git-workflow.sh promote-to-staging # Merge dev → stage
./git-workflow.sh create-prod-pr    # Create PR for production

Knowledge-Driven Development

The agent reads from and writes to .knowledge/ to maintain state:

.knowledge/
├── context/
│   ├── project.json      # Project definition
│   ├── objectives.json   # Goals and metrics
│   └── current.json      # Current focus
├── work/
│   ├── backlog.json      # Future tasks
│   ├── in-progress.json  # Active work
│   └── completed.json    # Done (changelog)
├── decisions/
│   └── log.jsonl         # Decision history
└── metrics/
    └── latest.json       # Health metrics

⚠️ Important: The .knowledge/ directory is initialized from knowledge-template but all commits go to the project repository. The template's .git is removed after cloning to prevent accidental pushback. Never push changes to knowledge-template.

Build-in-Public Integration

The knowledge structure powers the boilerplate's Build in Public dashboard:

CurrentFocus widget shows context/current.json
TaskBoard displays work/*.json
DecisionFeed streams decisions/log.jsonl
Changelog page renders work/completed.json
MetricsPanel shows metrics/latest.json

This creates transparency for users and accountability for the agent.

Environment Variables

Core

Variable	Required	Description
`ANTHROPIC_API_KEY`	Yes	Your Anthropic API key
`GITHUB_TOKEN`	For GitHub mode	Personal access token with repo scope
`PROJECT_NAME`	For GitHub mode	Repository name (auto-prefixed with `agent-`)
`KNOWLEDGE_TEMPLATE`	No	GitHub repo with knowledge template
`BUILD_TASK`	No	Override task to execute
`AGENT_ROLE`	No	Role to run (default: developer)
`LOG_FORMAT`	No	`json` for raw output

Branching

Variable	Default	Description
`PROJECT_BRANCH`	`release/dev`	Development branch (agent works here)
`STAGING_BRANCH`	`release/stage`	Staging branch (pre-production)
`PRODUCTION_BRANCH`	`release/prod`	Production branch (human-controlled)
`AUTO_MERGE_TO_STAGING`	`false`	Auto-merge dev→stage when ready

Vercel Deployment

Variable	Required	Description
`VERCEL_TOKEN`	For deployments	Vercel API token
`VERCEL_TEAM_ID`	For teams	Team ID (optional for personal accounts)
`VERCEL_ORG_ID`	For teams	Organization ID
`AUTO_SETUP_VERCEL`	No	Auto-create Vercel project on init

Using the SaaS Boilerplate

Every product starts from the SaaS Boilerplate, which provides:

Pre-Built Features

✅ Next.js 15 with App Router
✅ Clerk Authentication
✅ MongoDB with connection pooling
✅ Stripe/Clerk Billing (subscriptions)
✅ Tailwind CSS + shadcn/ui
✅ Zod validation
✅ Rate limiting
✅ Sentry monitoring

Established Patterns

The boilerplate has strict conventions:

// API routes follow this pattern
export async function POST(request: NextRequest) {
  // 1. Authenticate
  const authResult = await authenticateRequest(request);
  if (!authResult) return unauthorizedResponse();
  
  // 2. Validate with Zod
  const validation = validateBody(schema, body);
  if (!validation.success) return errorResponse(validation.error);
  
  // 3. Check subscription limits
  const { allowed } = await checkFeatureLimit(userId, 'todos');
  if (!allowed) return errorResponse('Limit reached', 403);
  
  // 4. Execute and respond
  return NextResponse.json<ApiResponse<T>>({ success: true, data });
}

Adding Features

When extending the boilerplate:

Types → lib/types.ts
Validation → lib/validation/schemas.ts
Collection → lib/mongodb.ts
API Routes → app/api/{feature}/route.ts
Components → components/features/{feature}/
Plan Limits → config/plans.ts

Directory Structure

agent-framework/
├── Dockerfile           # Container with Claude Code CLI
├── entrypoint.sh        # Main execution script
├── docker-compose.yml   # Local and GitHub modes
├── env.example          # Example environment variables
├── smart-orchestrate.sh # ⭐ State-based intelligent orchestration
├── run-full-cycle.sh    # Simple fixed-sequence pipeline
├── orchestrate.sh       # Interactive multi-role orchestration
├── auto-cycle.sh        # Continuous development loop
├── git-workflow.sh      # Branch management helper
├── roles/               # Role-specific prompts
│   ├── developer.txt
│   ├── planner.txt
│   ├── reviewer.txt
│   ├── initiator.txt
│   └── deployer.txt     # Vercel & branch promotions
├── config/              # Configuration files
├── output/              # Local mode output (gitignored)
├── CLAUDE.md            # Agent coding standards
└── README.md

Creating a GitHub Token

Go to GitHub → Settings → Developer settings → Personal access tokens
Generate new token (classic)
Select scopes: repo (full control of private repositories)
Copy the token to your .env file

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github/workflows		.github/workflows
roles		roles
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
README.md		README.md
auto-cycle.sh		auto-cycle.sh
docker-compose.yml		docker-compose.yml
entrypoint.sh		entrypoint.sh
env.example		env.example
format-logs.sh		format-logs.sh
git-workflow.sh		git-workflow.sh
orchestrate.sh		orchestrate.sh
package.json		package.json
run-full-cycle.sh		run-full-cycle.sh
smart-orchestrate.sh		smart-orchestrate.sh

nxtlvlrob/agent-framework

Folders and files

Latest commit

History

Repository files navigation