create-ai-scaffold

Scaffold the AI-collaboration layer for any software project. No app code, no framework lock-in — just the working agreements, context structures, and maintenance workflows that make AI-assisted development sustainable.

Quick Start

npx create-ai-scaffold my-project

Or scaffold in an existing project:

cd my-project
npx create-ai-scaffold .

What It Creates

my-project/
├── CLAUDE.md              # Pointer → .ai/assistant.md (Claude Code)
├── AGENTS.md              # Pointer → .ai/assistant.md (Codex, agents)
├── .cursorrules           # Pointer → .ai/assistant.md (Cursor IDE)
├── .windsurfrules         # Pointer → .ai/assistant.md (Windsurf IDE)
├── .ai/
│   ├── assistant.md       # Single source of truth for AI instructions
│   ├── buildplan.md       # Implementation plan (synced by the sync command)
│   ├── conventions.md     # Code style and project conventions
│   ├── context/           # Drop reference docs, API specs, examples here
│   │   └── README.md
│   └── decisions/         # Architecture Decision Records (team/production)
│       └── 000-template.md
└── .gitignore             # Sensible defaults (merged with existing)

Tiers

Choose a collaboration tier when scaffolding:

Tier	Who it's for	What's included
solo	Just you and AI assistants	Core files, minimal conventions
team	Multiple contributors	+ ADR template, git/branching conventions, expanded style guide
production	Full quality gates	+ Testing requirements, security notes, documentation standards

npx create-ai-scaffold my-project --tier team

Sync Command

Keep your build plan in sync with reality. The sync command gathers project context (file tree, git log, TODOs, dependencies), sends it to an AI backend, and proposes updates to .ai/buildplan.md.

# Full sync — auto-detects available AI CLI
create-ai-scaffold sync

# Record recent accomplishments
create-ai-scaffold sync --checkpoint

# Plan next steps
create-ai-scaffold sync --plan

# Audit for drift between plan and reality
create-ai-scaffold sync --review

# Preview the prompt without calling AI
create-ai-scaffold sync --dry-run

The sync command shows a diff of proposed changes and lets you accept, edit in $EDITOR, or reject (saving the proposal for later).

AI Backends

The sync command supports pluggable AI backends. By default it auto-detects which CLI is installed:

Backend	CLI	Detection order
claude	Claude Code	1st
codex	OpenAI Codex	2nd
clipboard	None (copies prompt to clipboard)	Fallback

# Explicitly choose a backend
create-ai-scaffold sync --backend codex

# Use clipboard fallback (no CLI required)
create-ai-scaffold sync --backend clipboard

The clipboard backend copies the prompt to your system clipboard so you can paste it into any AI tool, then paste the response back.

Options

Usage: create-ai-scaffold [project-name] [options]

Options:
  -t, --tier <tier>  Collaboration tier: solo, team, or production
  -y, --yes          Skip prompts and use defaults
  -V, --version      Output the version number
  -h, --help         Display help

Philosophy

• Stack-agnostic — generates zero application code. Your first AI session is where you choose a stack.
• Single source of truth — all AI instructions live in .ai/assistant.md. Pointer files (CLAUDE.md, .cursorrules, etc.) just redirect there.
• Non-destructive — never overwrites existing files. Only .gitignore is merged.
• Living system — the sync command keeps your build plan current as the project evolves.

Requirements

• Node.js >= 18
• For the sync command: Claude Code, OpenAI Codex, or any AI tool (via the clipboard fallback)

License

ISC