pan-wizard 2.8.1

package/pan-wizard-core/templates/codebase/architecture.md

@@ -0,0 +1,283 @@
+# Architecture Template
+
+Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code organization.
+
+**Purpose:** Document how the code is organized at a conceptual level. Complements STRUCTURE.md (which shows physical file locations).
+
+---
+
+## File Template
+
+```markdown
+# Architecture
+
+**Analysis Date:** [YYYY-MM-DD]
+
+## Business Architecture
+
+[What the system does — capabilities, user-facing processes, business value]
+
+**Purpose:** [What problem the system solves]
+
+**Key Capabilities:**
+- [Capability 1]
+- [Capability 2]
+- [Capability 3]
+
+## Application Architecture
+
+### Pattern Overview
+
+**Overall:** [Pattern name: e.g., "Monolithic CLI", "Serverless API", "Full-stack MVC"]
+
+**Key Characteristics:**
+- [Characteristic 1: e.g., "Single executable"]
+- [Characteristic 2: e.g., "Stateless request handling"]
+- [Characteristic 3: e.g., "Event-driven"]
+
+### Component Relationships
+
+[Mermaid flowchart showing how major components relate to each other]
+
+```mermaid
+graph LR
+    EntryPoint[Entry Point] --> Router[Router/Dispatcher]
+    Router --> ServiceA[Service A]
+    Router --> ServiceB[Service B]
+    ServiceA --> Core[Core/Shared]
+    ServiceB --> Core
+    Core --> Utils[Utilities]
+```
+
+### Layers
+
+**[Layer Name]:**
+- Purpose: [What this layer does]
+- Contains: [Types of code: e.g., "route handlers", "business logic"]
+- Depends on: [What it uses: e.g., "data layer only"]
+- Used by: [What uses it: e.g., "API routes"]
+
+**[Layer Name]:**
+- Purpose: [What this layer does]
+- Contains: [Types of code]
+- Depends on: [What it uses]
+- Used by: [What uses it]
+
+### Request Lifecycle
+
+[Mermaid sequence diagram showing the primary data flow]
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant E as Entry Point
+    participant R as Router
+    participant S as Service
+    participant D as Data Layer
+    U->>E: Input
+    E->>R: Route request
+    R->>S: Invoke handler
+    S->>D: Read/write data
+    D-->>S: Result
+    S-->>R: Response
+    R-->>E: Output
+    E-->>U: Display result
+```
+
+### Data Flow
+
+**[Flow Name] (e.g., "HTTP Request", "CLI Command", "Event Processing"):**
+
+1. [Entry point: e.g., "User runs command"]
+2. [Processing step: e.g., "Router matches path"]
+3. [Processing step: e.g., "Controller validates input"]
+4. [Processing step: e.g., "Service executes logic"]
+5. [Output: e.g., "Response returned"]
+
+**State Management:**
+- [How state is handled: e.g., "Stateless - no persistent state", "Database per request", "In-memory cache"]
+
+### Key Abstractions
+
+**[Abstraction Name]:**
+- Purpose: [What it represents]
+- Examples: [e.g., "UserService, ProjectService"]
+- Pattern: [e.g., "Singleton", "Factory", "Repository"]
+
+### Entry Points
+
+**[Entry Point]:**
+- Location: [Brief: e.g., "src/index.ts", "API Gateway triggers"]
+- Triggers: [What invokes it: e.g., "CLI invocation", "HTTP request"]
+- Responsibilities: [What it does: e.g., "Parse args, route to command"]
+
+### Error Handling
+
+**Strategy:** [How errors are handled]
+
+**Patterns:**
+- [Pattern: e.g., "try/catch at controller level"]
+- [Pattern: e.g., "Error codes returned to user"]
+
+### Cross-Cutting Concerns
+
+**Logging:** [Approach]
+**Validation:** [Approach]
+**Authentication:** [Approach]
+
+---
+
+*Architecture analysis: [date]*
+*Update when major patterns change*
+```
+
+<good_examples>
+```markdown
+# Architecture
+
+**Analysis Date:** 2025-01-20
+
+## Pattern Overview
+
+**Overall:** CLI Application with Plugin System
+
+**Key Characteristics:**
+- Single executable with subcommands
+- Plugin-based extensibility
+- File-based state (no database)
+- Synchronous execution model
+
+## Layers
+
+**Command Layer:**
+- Purpose: Parse user input and route to appropriate handler
+- Contains: Command definitions, argument parsing, help text
+- Location: `src/commands/*.ts`
+- Depends on: Service layer for business logic
+- Used by: CLI entry point (`src/index.ts`)
+
+**Service Layer:**
+- Purpose: Core business logic
+- Contains: FileService, TemplateService, InstallService
+- Location: `src/services/*.ts`
+- Depends on: File system utilities, external tools
+- Used by: Command handlers
+
+**Utility Layer:**
+- Purpose: Shared helpers and abstractions
+- Contains: File I/O wrappers, path resolution, string formatting
+- Location: `src/utils/*.ts`
+- Depends on: Node.js built-ins only
+- Used by: Service layer
+
+## Data Flow
+
+**CLI Command Execution:**
+
+1. User runs: `pan new-project`
+2. Commander parses args and flags
+3. Command handler invoked (`src/commands/new-project.ts`)
+4. Handler calls service methods (`src/services/project.ts` → `create()`)
+5. Service reads templates, processes files, writes output
+6. Results logged to console
+7. Process exits with status code
+
+**State Management:**
+- File-based: All state lives in `.planning/` directory
+- No persistent in-memory state
+- Each command execution is independent
+
+## Key Abstractions
+
+**Service:**
+- Purpose: Encapsulate business logic for a domain
+- Examples: `src/services/file.ts`, `src/services/template.ts`, `src/services/project.ts`
+- Pattern: Singleton-like (imported as modules, not instantiated)
+
+**Command:**
+- Purpose: CLI command definition
+- Examples: `src/commands/new-project.ts`, `src/commands/plan-phase.ts`
+- Pattern: Commander.js command registration
+
+**Template:**
+- Purpose: Reusable document structures
+- Examples: project.md, plan.md templates
+- Pattern: Markdown files with substitution variables
+
+## Entry Points
+
+**CLI Entry:**
+- Location: `src/index.ts`
+- Triggers: User runs `pan <command>`
+- Responsibilities: Register commands, parse args, display help
+
+**Commands:**
+- Location: `src/commands/*.ts`
+- Triggers: Matched command from CLI
+- Responsibilities: Validate input, call services, format output
+
+## Error Handling
+
+**Strategy:** Throw exceptions, catch at command level, log and exit
+
+**Patterns:**
+- Services throw Error with descriptive messages
+- Command handlers catch, log error to stderr, exit(1)
+- Validation errors shown before execution (fail fast)
+
+## Cross-Cutting Concerns
+
+**Logging:**
+- Console.log for normal output
+- Console.error for errors
+- Chalk for colored output
+
+**Validation:**
+- Zod schemas for config file parsing
+- Manual validation in command handlers
+- Fail fast on invalid input
+
+**File Operations:**
+- FileService abstraction over fs-extra
+- All paths validated before operations
+- Atomic writes (temp file + rename)
+
+---
+
+*Architecture analysis: 2025-01-20*
+*Update when major patterns change*
+```
+</good_examples>
+
+<guidelines>
+**What belongs in ARCHITECTURE.md:**
+- Overall architectural pattern (monolith, microservices, layered, etc.)
+- Conceptual layers and their relationships
+- Data flow / request lifecycle
+- Key abstractions and patterns
+- Entry points
+- Error handling strategy
+- Cross-cutting concerns (logging, auth, validation)
+
+**What does NOT belong here:**
+- Exhaustive file listings (that's STRUCTURE.md)
+- Technology choices (that's STACK.md)
+- Line-by-line code walkthrough (defer to code reading)
+- Implementation details of specific features
+
+**File paths ARE welcome:**
+Include file paths as concrete examples of abstractions. Use backtick formatting: `src/services/user.ts`. This makes the architecture document actionable for Claude when planning.
+
+**When filling this template:**
+- Read main entry points (index, server, main)
+- Identify layers by reading imports/dependencies
+- Trace a typical request/command execution
+- Note recurring patterns (services, controllers, repositories)
+- Keep descriptions conceptual, not mechanical
+
+**Useful for phase planning when:**
+- Adding new features (where does it fit in the layers?)
+- Refactoring (understanding current patterns)
+- Identifying where to add code (which layer handles X?)
+- Understanding dependencies between components
+</guidelines>

package/pan-wizard-core/templates/codebase/best-practices.md

@@ -0,0 +1,133 @@
+# Best Practices Template
+
+Template for `.planning/codebase/best-practices.md` - assesses coding practices across categories.
+
+**Purpose:** Score and document which best practices the codebase follows, with prescriptive recommendations for improvement.
+
+---
+
+## File Template
+
+```markdown
+# Best Practices Assessment
+
+**Analysis Date:** [YYYY-MM-DD]
+**Overall Score:** [N]/10
+
+## Score Summary
+
+| Category | Score | Status |
+|----------|-------|--------|
+| Error Handling | [N]/10 | [Good/Needs Work/Critical] |
+| Testing | [N]/10 | [Good/Needs Work/Critical] |
+| Naming Conventions | [N]/10 | [Good/Needs Work/Critical] |
+| Security | [N]/10 | [Good/Needs Work/Critical] |
+| Performance | [N]/10 | [Good/Needs Work/Critical] |
+
+## Error Handling ([N]/10)
+
+**Detected patterns:**
+- [Pattern description with percentage or count]
+- [Example: "try-catch in async functions: 85% coverage"]
+
+**Code examples:**
+```[language]
+// Pattern found in `[file path]`
+[Show actual pattern from codebase]
+```
+
+**Recommendations:**
+- [Specific, actionable recommendation with file path]
+
+## Testing ([N]/10)
+
+**Detected patterns:**
+- [Test framework and runner]
+- [Test file count and location]
+- [Coverage configuration status]
+- [Test types present: unit, integration, e2e]
+
+**Recommendations:**
+- [Specific, actionable recommendation]
+
+## Naming Conventions ([N]/10)
+
+**Detected patterns:**
+- Files: [Pattern observed — kebab-case, camelCase, PascalCase, snake_case]
+- Functions: [Pattern observed]
+- Variables: [Pattern observed]
+- Constants: [Pattern observed]
+
+**Violations:**
+- `[file path]` — [What's wrong and what it should be]
+
+**Recommendations:**
+- [Standardization suggestion]
+
+## Security ([N]/10)
+
+**Detected patterns:**
+- [.env handling]
+- [Secret management]
+- [Input validation approach]
+- [Dependency security]
+
+**Recommendations:**
+- [Specific security improvement with file path]
+
+## Performance ([N]/10)
+
+**Detected patterns:**
+- [Memoization usage]
+- [Lazy loading patterns]
+- [Bundle optimization]
+- [Caching strategies]
+
+**Recommendations:**
+- [Specific performance improvement with file path]
+
+## Priority Actions
+
+Top 3 improvements ranked by impact:
+
+1. **[Category]:** [Action] — Impact: [High/Medium]
+2. **[Category]:** [Action] — Impact: [High/Medium]
+3. **[Category]:** [Action] — Impact: [High/Medium]
+
+---
+
+*Best practices assessment: [date]*
+*Update after significant codebase changes*
+```
+
+<guidelines>
+**What belongs in best-practices.md:**
+- Scored assessment across 5 categories (0-10 each)
+- Detected patterns with evidence (file paths, counts, percentages)
+- Code examples showing actual patterns found
+- Specific, actionable recommendations
+- Priority actions ranked by impact
+
+**What does NOT belong here:**
+- Detailed code style rules (that's CONVENTIONS.md)
+- Bug reports (that's CONCERNS.md)
+- Architecture decisions (that's ARCHITECTURE.md)
+
+**Scoring guide:**
+- 9-10: Excellent — consistent, well-established practices
+- 7-8: Good — mostly consistent with minor gaps
+- 5-6: Needs Work — inconsistent or missing in areas
+- 3-4: Poor — significant gaps
+- 0-2: Critical — practices largely absent
+
+**Status thresholds:**
+- Good: score >= 7
+- Needs Work: score 4-6
+- Critical: score <= 3
+
+**When filling this template:**
+- Use pre-computed best-practices data if provided in the prompt
+- Always include file paths as evidence
+- Recommendations must be specific ("Add try-catch to X") not vague ("Improve error handling")
+- Priority actions should be the highest-impact, lowest-effort improvements
+</guidelines>