@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plan-build-run/templates/codebase/stack.md

@@ -0,0 +1,186 @@
+# Technology Stack Template
+
+Template for `.planning/codebase/STACK.md` - captures the technology foundation.
+
+**Purpose:** Document what technologies run this codebase. Focused on "what executes when you run the code."
+
+---
+
+## File Template
+
+```markdown
+# Technology Stack
+
+**Analysis Date:** [YYYY-MM-DD]
+
+## Languages
+
+**Primary:**
+- [Language] [Version] - [Where used: e.g., "all application code"]
+
+**Secondary:**
+- [Language] [Version] - [Where used: e.g., "build scripts, tooling"]
+
+## Runtime
+
+**Environment:**
+- [Runtime] [Version] - [e.g., "Node.js 20.x"]
+- [Additional requirements if any]
+
+**Package Manager:**
+- [Manager] [Version] - [e.g., "npm 10.x"]
+- Lockfile: [e.g., "package-lock.json present"]
+
+## Frameworks
+
+**Core:**
+- [Framework] [Version] - [Purpose: e.g., "web server", "UI framework"]
+
+**Testing:**
+- [Framework] [Version] - [e.g., "Jest for unit tests"]
+- [Framework] [Version] - [e.g., "Playwright for E2E"]
+
+**Build/Dev:**
+- [Tool] [Version] - [e.g., "Vite for bundling"]
+- [Tool] [Version] - [e.g., "TypeScript compiler"]
+
+## Key Dependencies
+
+[Only include dependencies critical to understanding the stack - limit to 5-10 most important]
+
+**Critical:**
+- [Package] [Version] - [Why it matters: e.g., "authentication", "database access"]
+- [Package] [Version] - [Why it matters]
+
+**Infrastructure:**
+- [Package] [Version] - [e.g., "Express for HTTP routing"]
+- [Package] [Version] - [e.g., "PostgreSQL client"]
+
+## Configuration
+
+**Environment:**
+- [How configured: e.g., ".env files", "environment variables"]
+- [Key configs: e.g., "DATABASE_URL, API_KEY required"]
+
+**Build:**
+- [Build config files: e.g., "vite.config.ts, tsconfig.json"]
+
+## Platform Requirements
+
+**Development:**
+- [OS requirements or "any platform"]
+- [Additional tooling: e.g., "Docker for local DB"]
+
+**Production:**
+- [Deployment target: e.g., "Vercel", "AWS Lambda", "Docker container"]
+- [Version requirements]
+
+---
+
+*Stack analysis: [date]*
+*Update after major dependency changes*
+```
+
+<good_examples>
+```markdown
+# Technology Stack
+
+**Analysis Date:** 2025-01-20
+
+## Languages
+
+**Primary:**
+- TypeScript 5.3 - All application code
+
+**Secondary:**
+- JavaScript - Build scripts, config files
+
+## Runtime
+
+**Environment:**
+- Node.js 20.x (LTS)
+- No browser runtime (CLI tool only)
+
+**Package Manager:**
+- npm 10.x
+- Lockfile: `package-lock.json` present
+
+## Frameworks
+
+**Core:**
+- None (vanilla Node.js CLI)
+
+**Testing:**
+- Vitest 1.0 - Unit tests
+- tsx - TypeScript execution without build step
+
+**Build/Dev:**
+- TypeScript 5.3 - Compilation to JavaScript
+- esbuild - Used by Vitest for fast transforms
+
+## Key Dependencies
+
+**Critical:**
+- commander 11.x - CLI argument parsing and command structure
+- chalk 5.x - Terminal output styling
+- fs-extra 11.x - Extended file system operations
+
+**Infrastructure:**
+- Node.js built-ins - fs, path, child_process for file operations
+
+## Configuration
+
+**Environment:**
+- No environment variables required
+- Configuration via CLI flags only
+
+**Build:**
+- `tsconfig.json` - TypeScript compiler options
+- `vitest.config.ts` - Test runner configuration
+
+## Platform Requirements
+
+**Development:**
+- macOS/Linux/Windows (any platform with Node.js)
+- No external dependencies
+
+**Production:**
+- Distributed as npm package
+- Installed globally via npm install -g
+- Runs on user's Node.js installation
+
+---
+
+*Stack analysis: 2025-01-20*
+*Update after major dependency changes*
+```
+</good_examples>
+
+<guidelines>
+**What belongs in STACK.md:**
+- Languages and versions
+- Runtime requirements (Node, Bun, Deno, browser)
+- Package manager and lockfile
+- Framework choices
+- Critical dependencies (limit to 5-10 most important)
+- Build tooling
+- Platform/deployment requirements
+
+**What does NOT belong here:**
+- File structure (that's STRUCTURE.md)
+- Architectural patterns (that's ARCHITECTURE.md)
+- Every dependency in package.json (only critical ones)
+- Implementation details (defer to code)
+
+**When filling this template:**
+- Check package.json for dependencies
+- Note runtime version from .nvmrc or package.json engines
+- Include only dependencies that affect understanding (not every utility)
+- Specify versions only when version matters (breaking changes, compatibility)
+
+**Useful for phase planning when:**
+- Adding new dependencies (check compatibility)
+- Upgrading frameworks (know what's in use)
+- Choosing implementation approach (must work with existing stack)
+- Understanding build requirements
+</guidelines>

package/plan-build-run/templates/codebase/structure.md

@@ -0,0 +1,285 @@
+# Structure Template
+
+Template for `.planning/codebase/STRUCTURE.md` - captures physical file organization.
+
+**Purpose:** Document where things physically live in the codebase. Answers "where do I put X?"
+
+---
+
+## File Template
+
+```markdown
+# Codebase Structure
+
+**Analysis Date:** [YYYY-MM-DD]
+
+## Directory Layout
+
+[ASCII box-drawing tree of top-level directories with purpose - use ├── └── │ characters for tree structure only]
+
+```
+[project-root]/
+├── [dir]/          # [Purpose]
+├── [dir]/          # [Purpose]
+├── [dir]/          # [Purpose]
+└── [file]          # [Purpose]
+```
+
+## Directory Purposes
+
+**[Directory Name]:**
+- Purpose: [What lives here]
+- Contains: [Types of files: e.g., "*.ts source files", "component directories"]
+- Key files: [Important files in this directory]
+- Subdirectories: [If nested, describe structure]
+
+**[Directory Name]:**
+- Purpose: [What lives here]
+- Contains: [Types of files]
+- Key files: [Important files]
+- Subdirectories: [Structure]
+
+## Key File Locations
+
+**Entry Points:**
+- [Path]: [Purpose: e.g., "CLI entry point"]
+- [Path]: [Purpose: e.g., "Server startup"]
+
+**Configuration:**
+- [Path]: [Purpose: e.g., "TypeScript config"]
+- [Path]: [Purpose: e.g., "Build configuration"]
+- [Path]: [Purpose: e.g., "Environment variables"]
+
+**Core Logic:**
+- [Path]: [Purpose: e.g., "Business services"]
+- [Path]: [Purpose: e.g., "Database models"]
+- [Path]: [Purpose: e.g., "API routes"]
+
+**Testing:**
+- [Path]: [Purpose: e.g., "Unit tests"]
+- [Path]: [Purpose: e.g., "Test fixtures"]
+
+**Documentation:**
+- [Path]: [Purpose: e.g., "User-facing docs"]
+- [Path]: [Purpose: e.g., "Developer guide"]
+
+## Naming Conventions
+
+**Files:**
+- [Pattern]: [Example: e.g., "kebab-case.ts for modules"]
+- [Pattern]: [Example: e.g., "PascalCase.tsx for React components"]
+- [Pattern]: [Example: e.g., "*.test.ts for test files"]
+
+**Directories:**
+- [Pattern]: [Example: e.g., "kebab-case for feature directories"]
+- [Pattern]: [Example: e.g., "plural names for collections"]
+
+**Special Patterns:**
+- [Pattern]: [Example: e.g., "index.ts for directory exports"]
+- [Pattern]: [Example: e.g., "__tests__ for test directories"]
+
+## Where to Add New Code
+
+**New Feature:**
+- Primary code: [Directory path]
+- Tests: [Directory path]
+- Config if needed: [Directory path]
+
+**New Component/Module:**
+- Implementation: [Directory path]
+- Types: [Directory path]
+- Tests: [Directory path]
+
+**New Route/Command:**
+- Definition: [Directory path]
+- Handler: [Directory path]
+- Tests: [Directory path]
+
+**Utilities:**
+- Shared helpers: [Directory path]
+- Type definitions: [Directory path]
+
+## Special Directories
+
+[Any directories with special meaning or generation]
+
+**[Directory]:**
+- Purpose: [e.g., "Generated code", "Build output"]
+- Source: [e.g., "Auto-generated by X", "Build artifacts"]
+- Committed: [Yes/No - in .gitignore?]
+
+---
+
+*Structure analysis: [date]*
+*Update when directory structure changes*
+```
+
+<good_examples>
+```markdown
+# Codebase Structure
+
+**Analysis Date:** 2025-01-20
+
+## Directory Layout
+
+```
+plan-build-run/
+├── bin/                # Executable entry points
+├── commands/           # Slash command definitions
+│   └── gsd/           # PBR-specific commands
+├── plan-build-run/     # Skill resources
+│   ├── references/    # Principle documents
+│   ├── templates/     # File templates
+│   └── workflows/     # Multi-step procedures
+├── src/               # Source code (if applicable)
+├── tests/             # Test files
+├── package.json       # Project manifest
+└── README.md          # User documentation
+```
+
+## Directory Purposes
+
+**bin/**
+- Purpose: CLI entry points
+- Contains: install.js (installer script)
+- Key files: install.js - handles npx installation
+- Subdirectories: None
+
+**commands/pbr/**
+- Purpose: Slash command definitions for Claude Code
+- Contains: *.md files (one per command)
+- Key files: new-project.md, plan-phase.md, execute-plan.md
+- Subdirectories: None (flat structure)
+
+**plan-build-run/references/**
+- Purpose: Core philosophy and guidance documents
+- Contains: principles.md, questioning.md, plan-format.md
+- Key files: principles.md - system philosophy
+- Subdirectories: None
+
+**plan-build-run/templates/**
+- Purpose: Document templates for .planning/ files
+- Contains: Template definitions with frontmatter
+- Key files: project.md, roadmap.md, plan.md, summary.md
+- Subdirectories: codebase/ (new - for stack/architecture/structure templates)
+
+**plan-build-run/workflows/**
+- Purpose: Reusable multi-step procedures
+- Contains: Workflow definitions called by commands
+- Key files: execute-plan.md, research-phase.md
+- Subdirectories: None
+
+## Key File Locations
+
+**Entry Points:**
+- `bin/install.js` - Installation script (npx entry)
+
+**Configuration:**
+- `package.json` - Project metadata, dependencies, bin entry
+- `.gitignore` - Excluded files
+
+**Core Logic:**
+- `bin/install.js` - All installation logic (file copying, path replacement)
+
+**Testing:**
+- `tests/` - Test files (if present)
+
+**Documentation:**
+- `README.md` - User-facing installation and usage guide
+- `CLAUDE.md` - Instructions for Claude Code when working in this repo
+
+## Naming Conventions
+
+**Files:**
+- kebab-case.md: Markdown documents
+- kebab-case.js: JavaScript source files
+- UPPERCASE.md: Important project files (README, CLAUDE, CHANGELOG)
+
+**Directories:**
+- kebab-case: All directories
+- Plural for collections: templates/, commands/, workflows/
+
+**Special Patterns:**
+- {command-name}.md: Slash command definition
+- *-template.md: Could be used but templates/ directory preferred
+
+## Where to Add New Code
+
+**New Slash Command:**
+- Primary code: `commands/pbr/{command-name}.md`
+- Tests: `tests/commands/{command-name}.test.js` (if testing implemented)
+- Documentation: Update `README.md` with new command
+
+**New Template:**
+- Implementation: `plan-build-run/templates/{name}.md`
+- Documentation: Template is self-documenting (includes guidelines)
+
+**New Workflow:**
+- Implementation: `plan-build-run/workflows/{name}.md`
+- Usage: Reference from command with `@~/.claude/plan-build-run/workflows/{name}.md`
+
+**New Reference Document:**
+- Implementation: `plan-build-run/references/{name}.md`
+- Usage: Reference from commands/workflows as needed
+
+**Utilities:**
+- No utilities yet (`install.js` is monolithic)
+- If extracted: `src/utils/`
+
+## Special Directories
+
+**plan-build-run/**
+- Purpose: Resources installed to ~/.claude/
+- Source: Copied by bin/install.js during installation
+- Committed: Yes (source of truth)
+
+**commands/**
+- Purpose: Slash commands installed to ~/.claude/commands/
+- Source: Copied by bin/install.js during installation
+- Committed: Yes (source of truth)
+
+---
+
+*Structure analysis: 2025-01-20*
+*Update when directory structure changes*
+```
+</good_examples>
+
+<guidelines>
+**What belongs in STRUCTURE.md:**
+- Directory layout (ASCII box-drawing tree for structure visualization)
+- Purpose of each directory
+- Key file locations (entry points, configs, core logic)
+- Naming conventions
+- Where to add new code (by type)
+- Special/generated directories
+
+**What does NOT belong here:**
+- Conceptual architecture (that's ARCHITECTURE.md)
+- Technology stack (that's STACK.md)
+- Code implementation details (defer to code reading)
+- Every single file (focus on directories and key files)
+
+**When filling this template:**
+- Use `tree -L 2` or similar to visualize structure
+- Identify top-level directories and their purposes
+- Note naming patterns by observing existing files
+- Locate entry points, configs, and main logic areas
+- Keep directory tree concise (max 2-3 levels)
+
+**Tree format (ASCII box-drawing characters for structure only):**
+```
+root/
+├── dir1/           # Purpose
+│   ├── subdir/    # Purpose
+│   └── file.ts    # Purpose
+├── dir2/          # Purpose
+└── file.ts        # Purpose
+```
+
+**Useful for phase planning when:**
+- Adding new features (where should files go?)
+- Understanding project organization
+- Finding where specific logic lives
+- Following existing conventions
+</guidelines>