project-patterns

Project Patterns

Architecture Overview

Single-process Node.js CLI tool. No server, no database, no external service dependencies (except npm registry for version checks with 5s timeout). Pure filesystem operations — reads templates, writes scaffolded files, merges with existing user files.

Layer diagram:

CLI Entry (index.js)
  └── Commands (commands/*.js) — orchestration, user flow
        ├── Prompts (prompts/*.js) — Inquirer interactions, isolated from logic
        ├── Core (core/*.js) — business logic, no user interaction*
        ├── Generators (generators/*.js) — produce file content dynamically
        ├── Data (data/*.js) — constants, catalogs, registries
        └── Utils (utils/*.js) — pure helpers, no side effects

*Exception: merger.js calls promptHookConflict() directly — pragmatic compromise.

Key invariant: Commands orchestrate between prompts and core. Prompts never call core directly. Core never prompts the user (except merger.js).

Naming Conventions

• Files: kebab-case everywhere, no exceptions (agent-routing.js, file-categorizer.js, claude-md-merge.js)
• Test files: mirror source name + .test.js suffix (merger.test.js, agent-routing-integration.test.js)
• Functions: camelCase (buildSettingsJson, mergeSettingsPermissionsAndHooks)
• Constants: UPPER_SNAKE_CASE (UNIVERSAL_AGENTS, AGENT_CATALOG)
• No private prefix: unexported functions are private by convention — no underscore prefix

File Organization

Layer-based (not feature-based):

src/
├── index.js              # CLI entry point (Commander.js setup)
├── commands/             # One file per CLI command (init, upgrade, status, backup, restore, diff)
├── core/                 # Business logic: scaffolder, merger, detector, backup, config, file-categorizer
├── prompts/              # Inquirer prompt definitions: project-type, tech-stack, agent-selection, conflicts
├── generators/           # Dynamic content builders (agent-routing.js)
├── data/                 # Constants: agents.js (catalogs), agent-registry.js (routing metadata)
└── utils/                # Pure helpers: display.js, file.js, hash.js, time.js, npm.js

templates/                # User-facing template files (quality matters — these ship to users)
├── settings/             # 16 language-specific + base + docker JSON templates
├── agents/               # universal/ (5) + optional/ (18 across 6 categories)
├── commands/             # 10 slash command templates
└── skills/               # universal/ (9) + templates/ (3 placeholder skills)

tests/
├── commands/             # Tests mirror src/ structure
├── core/
├── prompts/
├── utils/
└── fixtures/             # Test projects: fresh-project, existing-project, workflow-project