Scaf-cli

Creates a .project/ folder with pre-structured docs (design, planning, quality) plus optional AGENTS.md and CHANGELOG.md. Built for people using AI-assisted dev tools (Cursor, Claude, Copilot) who want consistent project documentation in every repo—no more manually recreating the same structure.

Disclaimer: Built for personal use; contributions welcome.

Table of contents

• Quick start
• Installation
• Updating
• Example
• Usage
• Commands
• Help
• Version
• What It Creates
• Config
• Development
• Requirements
• Contributing
• License

Quick start

cd your-project
npx @lelborn/scaf-cli init
# Choose "Everything" at the prompt

Installation

npm install -g @lelborn/scaf-cli

This exposes the scaf command globally.

Or run without installing:

npx @lelborn/scaf-cli init

Updating

Global install:

npm install -g @lelborn/scaf-cli@latest

npx: Use npx @lelborn/scaf-cli@latest init to run the latest version.

Check version: scaf --version or npm list -g @lelborn/scaf-cli

The CLI checks npm for updates when you run it. If a newer version exists, you'll see a notification.

Example

mkdir my-project
cd my-project

npx @lelborn/scaf-cli init

Prompts you'll see:

1. How would you like to scaffold? — Choose "Everything" or "Pick and choose"
2. Everything — Installs full .project + AGENTS.md + CHANGELOG.md
3. Pick and choose — Multiselect: design/, planning/, quality/, AGENTS.md, CHANGELOG.md

Result (everything):

my-project/
├── .project/
│   ├── design/
│   ├── planning/
│   ├── quality/
│   └── README.md
├── AGENTS.md
└── CHANGELOG.md

Usage

scaf init [path] [options]

Options

Option	Description
-p, --path <dir>	Target directory (alternative to positional path). Creates parent directories if they don't exist.
-f, --force	Recreate .project if it already exists
-y, --yes	Skip prompts, scaffold full .project only (no AGENTS.md, CHANGELOG.md). Fails if .project exists unless --force is used.
-r, --refresh	Replace existing .project with fresh templates. Prompts for confirmation unless --force.
-d, --dry-run	Show what would be created without writing. Shows created vs skipped (already exists).

Examples

# Create .project in current directory (interactive prompts)
scaf init

# Create .project in a specific directory
scaf init ./my-repo
scaf init --path ./my-repo

# Non-interactive: scaffold only, no prompts
scaf init -y

# Recreate .project if it exists
scaf init --force

# Refresh .project with latest templates (prompts for confirmation if .project exists)
scaf init --refresh

# Refresh without confirmation
scaf init --refresh --force

Commands

scaf list          # List available templates and sections
scaf init --help   # Init options

Example output for scaf list:

.project sections:
  design/   — Architecture, brand guidelines, tech stack, technical design
  planning/ — Content strategy, product requirements, project spec, roadmap
  quality/  — Accessibility, legal requirements, security, testing

Root files:
  AGENTS.md   — AI agent instructions
  CHANGELOG.md — Version history (Keep a Changelog format)

Help

scaf --help
scaf init --help

Version

scaf --version

What It Creates

Each file is a template with placeholder sections. Replace placeholders with project-specific content as you develop.

.project folder structure

Section	Purpose
design/	Architecture, brand guidelines, tech stack, technical design
planning/	Content strategy, product requirements, project spec, roadmap
quality/	Accessibility, legal requirements, security, testing

.project/
├── design/
│   ├── architecture.md
│   ├── brand-guidelines.md
│   ├── tech-stack.md
│   └── technical-design.md
├── planning/
│   ├── content-strategy.md
│   ├── product-requirements.md
│   ├── project-spec.md
│   └── roadmap.md
├── quality/
│   ├── accessibility.md
│   ├── legal-requirements.md
│   ├── security.md
│   └── testing.md
└── README.md

Root files (optional, when prompted)

• AGENTS.md — in project root (template: build/test commands, code style, project structure, gotchas)
• CHANGELOG.md — in project root (template: Keep a Changelog format)

Choose "Everything" to install both, or "Pick and choose" to select individually.

Config

Place .scafrc (JSON) or scaf.config.js in the target directory to customize. Paths are relative to the directory containing the config file.

Option	Description
agentsFile	Root filename for agent instructions. Use to rename the file (e.g. agents.md instead of AGENTS.md).
templatesPath	Path to custom templates, relative to the config directory.

Required layout for custom templates:

• {templatesPath}/project/ — must contain design/, planning/, quality/, README.md
• {templatesPath}/AGENTS.md, {templatesPath}/CHANGELOG.md — for root files

Example .scafrc:

{
  "agentsFile": "agents.md",
  "templatesPath": "./.scaf-templates"
}

Development

Clone the repo and run locally:

git clone https://github.com/lelborn/scaf-cli
cd scaf-cli
npm install
npm link

Then run scaf init from any directory to test.

Requirements

• Node.js >= 18.0.0

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

MIT

Sponsor

If this tool is useful to you, consider supporting me on Ko-fi.