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 → docs/system/assistant.md (Claude Code)
├── AGENTS.md              # Pointer → docs/system/assistant.md (Codex, agents)
├── .cursorrules           # Pointer → docs/system/assistant.md (Cursor IDE)
├── .windsurfrules         # Pointer → docs/system/assistant.md (Windsurf IDE)
├── docs/
│   └── system/
│       ├── 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 docs/system/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 docs/system/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