CLI for generating standardized document templates (BRD, FRD, ADD, TSD)
npm install @satoshibits/create-docsA CLI tool for scaffolding standardized documentation templates (BRD, FRD, ADD, TSD, ADR).
create-docs helps teams establish and maintain comprehensive, traceable documentation by generating standardized templates with proper YAML frontmatter, traceability links, and consistent structure. Instead of starting from scratch, get expert-informed templates that guide you through documenting your project's business requirements, functional specs, architecture decisions, and technical specifications.
- Three project profiles: greenfield, migration, library - each with tailored document sets
- 5 CLI commands: init, new, lint, status, migrate
- 21 Handlebars templates: covering strategy, requirements, architecture, specs, guidelines, and operations
- Interactive setup: guided prompts for technology decisions (database, API style, auth, cloud provider, etc.)
- Document validation: lint command checks frontmatter schema, broken links, and stale documents
- Health tracking: status command provides at-a-glance view of documentation coverage
- Migration support: incrementally adopt the standard structure for existing documentation
``bash`
npm install @satoshibits/create-docsor
pnpm add @satoshibits/create-docsor
yarn add @satoshibits/create-docs
Initialize documentation in your project:
`bashinteractive setup
npx create-docs init
This creates the following structure:
docs/
├── README.md
├── 00-meta/
│ └── glossary.md
├── 01-strategy/
│ └── brd.md # greenfield only
├── 02-requirements/
│ └── frd.md
├── 03-architecture/
│ ├── add.md
│ └── decisions/
├── 04-specs/
│ ├── index.md
│ ├── api.md # if hasApi
│ ├── authentication.md # if hasApi
│ ├── database.md # if hasDatabase
│ └── background-jobs.md # if hasAsyncProcessing
├── 05-guidelines/
│ ├── coding.md
│ ├── testing.md
│ ├── deployment.md
│ ├── observability.md
│ └── change-management.md # if isRegulated
├── 06-operations/
│ ├── runbook.md
│ └── security.md
└── archive/
Plus a
configuration file in your project root.Commands Reference
$3
Initialize documentation structure and create
.create-docs.json config.`bash
create-docs init [options]Options:
-p, --profile Project profile (greenfield, migration, library)
-y, --yes Skip prompts and use defaults
-f, --force Overwrite existing docs/ directory
`Profiles:
- greenfield: Full document suite including BRD for new projects
- migration: Tailored for modernization projects (no BRD)
- library: Minimal set for library/package documentation
$3
Generate a new document from template.
bash
create-docs new [name]Document types:
adr Architecture Decision Record (auto-numbered)
spec Technical specification (in 04-specs/)
guideline Engineering guideline (in 05-guidelines/)
basic Generic document template
Examples:
create-docs new adr "Use PostgreSQL for relational data"
create-docs new spec api
create-docs new guideline code-review-process
`$3
Validate documentation integrity.
bash
create-docs lint
`Checks performed:
- YAML frontmatter schema validation
- Required fields (title, status, version, owner, last_updated)
- Valid status values (Draft, Review, Approved, Deprecated)
- Broken internal links
- Orphan requirement ID references
- Stale documents (>6 months without update)
$3
Display document health table.
bash
create-docs status
`Shows:
- Document status (Draft, Review, Approved, Deprecated)
- Owner assignment
- Last updated date
- Version numbers
- Coverage metrics
$3
Migrate existing documentation to standard structure.
bash
create-docs migrate [options]Options:
--dry-run Show what would change without making modifications
-t, --tier Migration tier (structure, frontmatter, conventions)
--no-backup Skip creating backup before migration
-r, --restore [name] Restore from backup (list backups if no name given)
-y, --yes Skip prompts and use defaults
Migration tiers:
structure Move files to standard directory layout (Tier 1)
frontmatter Add/standardize YAML frontmatter (Tier 2)
conventions Standardize IDs, links, traceability (Tier 3)
Examples:
create-docs migrate --dry-run # Preview changes
create-docs migrate --tier structure # Move files only
create-docs migrate # Interactive full migration
create-docs migrate --restore # List available backups
create-docs migrate --restore # Restore from backup
`Configuration
The
file stores project settings:`json
{
"projectName": "my-app",
"profile": "greenfield",
"owner": "@lead-engineer",
"adrCounter": 1,
"variance": {
"hasApi": true,
"hasDatabase": true,
"hasAsyncProcessing": false,
"isRegulated": false,
"databaseEngine": "postgres",
"ormStrategy": "prisma",
"apiStyle": "rest",
"identityProvider": "auth0",
"cloudProvider": "aws",
"gitStrategy": "trunk-based"
},
"createdAt": "2024-01-15"
}
`Key fields:
-
: Determines which core documents are generated
- adrCounter: Auto-increments for ADR numbering
- variance: Technology decisions that customize template contentTemplates
$3
| Template | Description | Location |
|----------|-------------|----------|
| readme | Documentation index | docs/README.md |
| glossary | Project terminology | docs/00-meta/glossary.md |
| brd | Business Requirements Document | docs/01-strategy/brd.md |
| frd | Functional Requirements Document | docs/02-requirements/frd.md |
| add | Application Design Document | docs/03-architecture/add.md |
| adr | Architecture Decision Record | docs/03-architecture/decisions/ |$3
| Template | Description |
|----------|-------------|
| api | API endpoints, versioning, authentication |
| authentication | Auth flows, token management, session handling |
| database | Schema design, migrations, query patterns |
| background-jobs | Async processing, queues, scheduled tasks |
| generic | Generic specification template |$3
| Template | Description |
|----------|-------------|
| coding | Code style, conventions, best practices |
| testing | Test strategy, coverage, frameworks |
| deployment | CI/CD, environments, release process |
| observability | Logging, metrics, tracing, alerting |
| change-management | Change control for regulated environments |
| generic | Generic guideline template |$3
| Template | Description |
|----------|-------------|
| runbook | Operational procedures, incident response |
| security | Security controls, compliance, threat model |Document Status Lifecycle
All documents use standardized status values:
`
Draft → Review → Approved → Deprecated
- Draft: Initial creation, work in progress
- Review: Ready for stakeholder review
- Approved: Finalized and accepted
- Deprecated: No longer current, moved to archive
- Node.js >= 18.0.0
MIT