create-project-scaffold

Generate context/ files, feature-specs/ backlog, and AGENTS.md from an architecture document using the Ghost AI template pattern.

Works anywhere — Node.js CLI tool, no AI assistant required.

Installation

npm install -g create-project-scaffold

Or use with npx (no installation):

npx create-project-scaffold <architecture-file>

Usage

create-project-scaffold ./ARCHITECTURE.md

Options

create-project-scaffold <architecture-file> [options]

Options:
  -o, --output <dir>         Output directory (default: current directory)
  --granularity <type>       Spec granularity: fine or coarse (default: fine)
  --markers <type>           Customization marker style: html, visible, or section (default: html)
  -V, --version              Output version number
  -h, --help                 Display help

Examples

# Generate in current directory
create-project-scaffold ./ARCHITECTURE.md

# Generate in specific directory
create-project-scaffold ./docs/spec.md -o ./my-project

# Use coarse-grained specs (fewer, larger files)
create-project-scaffold ./ARCHITECTURE.md --granularity coarse

# Use visible markers instead of HTML comments
create-project-scaffold ./ARCHITECTURE.md --markers visible

What it generates

Running the tool produces:

1. context/ folder (6 files)

• project-overview.md — product definition, roles, features, scope
• architecture-context.md — stack, multi-tenancy, storage, invariants
• ui-context.md — theme, colors, typography, layout patterns
• code-standards.md — conventions, file structure
• ai-workflow-rules.md — development workflow, scoping rules
• progress-tracker.md — phase tracking template

2. feature-specs/ folder (20-50 numbered specs)

• Sequential build backlog: 01, 02, 03, ...
• Foundation → entities → integration → production
• Backend before UI (schema → actions → mock UI → wire)
• Each spec: Goal → Implementation → Scope Limits → Check when done
• <!-- CUSTOMIZE: ... --> HTML comment markers for adjustable choices

3. AGENTS.md

• Entry-point that tells AI assistants to read context files first

Input requirements

Your architecture document should include:

• Product overview and feature list
• Tech stack (framework, database, auth, storage)
• User roles and permissions (if applicable)
• Data models or entities
• UI/UX direction (theme, colors, typography)
• Deployment target (Docker, Vercel, etc.)

Missing sections will be inferred with reasonable defaults based on common patterns.

Example workflow

# 1. Create your architecture document
vim ARCHITECTURE.md

# 2. Generate the scaffold
npx create-project-scaffold ./ARCHITECTURE.md

# Output:
# ✅ Scaffold generated successfully!
# 
# Output directory: /path/to/project
#   - context/ (6 files)
#   - feature-specs/ (27 files)
#   - AGENTS.md

# 3. Review and customize
# Edit the <!-- CUSTOMIZE --> blocks in context/ and feature-specs/

# 4. Start building
# Work through feature-specs/ in order, starting with 01

Template pattern

Uses the Ghost AI template pattern:

• Fine-grained specs — backend and UI split, mock-data UI before wiring
• HTML comment CUSTOMIZE markers — invisible when rendered, easy to grep
• Flat numbering — 01, 02, ... N (no phase prefixes)
• Reuse-first approach — specs mandate "follow existing pattern"
• Security by default — org-scoped queries, role checks, server-side ownership

How it works

The tool parses your architecture document and:

1. Extracts key information (stack, features, roles, models)
2. Generates context files with project-specific details
3. Creates a sequenced feature spec backlog
4. Writes customization markers for team-specific decisions
5. Produces an AGENTS.md entry point for AI assistants

All processing happens locally. No data is sent to external services.

Use with AI assistants

The generated files work with:

• Claude Code — copy AGENTS.md and context/ to your project
• Cursor — the .cursorrules equivalent
• GitHub Copilot — context files guide suggestions
• Any AI assistant — the pattern is tool-agnostic

Or use without AI — the specs are human-readable build instructions.

License

MIT

Contributing

Issues and PRs welcome at: https://github.com/yourusername/create-project-scaffold