npm package: @lelborn/scaf-cli
Description: Scaffold .project folder with documentation structure
Latest version: 1.0.1

# Scaf-cli

[![npm version](https://img.shields.io/npm/v/@lelborn/scaf-cli?style=flat-square)](https://www.npmjs.com/package/@lelborn/scaf-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/node/v/@lelborn/scaf-cli?style=flat-square)](https://nodejs.org)
[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-ff5e5b?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/lelborn)

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](#quick-start)
- [Installation](#installation)
- [Updating](#updating)
- [Example](#example)
- [Usage](#usage)
- [Commands](#commands)
- [Help](#help)
- [Version](#version)
- [What It Creates](#what-it-creates)
- [Config](#config)
- [Development](#development)
- [Requirements](#requirements)
- [Contributing](#contributing)
- [License](#license)

## Quick start

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

## Installation

```bash
npm install -g @lelborn/scaf-cli
```

This exposes the `scaf` command globally.

Or run without installing:

```bash
npx @lelborn/scaf-cli init
```

## Updating

**Global install:**
```bash
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

```bash
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

```bash
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

```bash
# 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

```bash
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

```bash
scaf --help
scaf init --help
```

## Version

```bash
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`:

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

## Development

Clone the repo and run locally:

```bash
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](CONTRIBUTING.md) for guidelines.

## License

[MIT](LICENSE)

## Sponsor

If this tool is useful to you, consider [supporting me on Ko-fi](https://ko-fi.com/lelborn).