Initial commit

commands/pp-init-assets/templates/root/INDEX.md

@@ -0,0 +1,65 @@
+# {{PROJECT_NAME}} - Project Index
+
+**Project**: {{PROJECT_DESCRIPTION}}
+**Created**: {{DATE}}
+**Last Updated**: {{DATE}}
+
+---
+
+## Active Subproject
+
+**{{ACTIVE_SUBPROJECT}}**
+
+See `{{ACTIVE_SUBPROJECT}}/STATUS.md` for detailed status.
+
+---
+
+## Quick Start (New Session)
+
+1. Read this INDEX.md (root overview + current state)
+2. Read WORKFLOW.md (understand the system)
+3. Go to active subproject folder: `{{ACTIVE_SUBPROJECT}}/`
+4. Read subproject's STATUS.md, TODO.md, and other files
+
+---
+
+## Project-Level TODO (High-Level)
+
+**Major Milestones & Cross-Subproject Tasks:**
+
+- [ ] {{TODO_ITEM_1}}
+- [ ] {{TODO_ITEM_2}}
+- [ ] {{TODO_ITEM_3}}
+
+*For detailed tasks, see subproject TODO.md files*
+
+---
+
+## Subprojects
+
+| Subproject | Status | Phase | Description |
+|------------|--------|-------|-------------|
+{{SUBPROJECT_TABLE}}
+
+---
+
+## Subproject Status Summary
+
+{{SUBPROJECT_STATUS_TABLE}}
+
+---
+
+## File Inheritance
+
+Root files (WORKFLOW.md, PRINCIPLES.md) apply to all subprojects.
+Subproject files extend/override root when needed.
+
+**Reading order:**
+1. Root level files (WORKFLOW, PRINCIPLES)
+2. Subproject files (STATUS, TODO, CODEBASE, etc.)
+
+---
+
+## Environment
+
+{{ENVIRONMENT}}

commands/pp-init-assets/templates/root/LESSONS.md

@@ -0,0 +1,22 @@
+# Lessons Learned (Root)
+
+Shared learnings applicable to all subprojects. Subprojects have their own LESSONS.md.
+
+---
+
+## Format
+
+```
+### [TAG] Short Title
+**Problem**: What went wrong
+**Investigation**: What was tried
+**Root Cause**: Why it happened
+**Solution**: How it was fixed
+**Keywords**: searchable terms
+```
+
+Tags: [BUG], [CONFIG], [API], [LOGIC], [INTEGRATION]
+
+---
+
+<!-- Add lessons that apply to multiple subprojects below -->

commands/pp-init-assets/templates/root/PRINCIPLES.md

@@ -0,0 +1,154 @@
+# Principles & Rules (Root)
+
+Base methodology and rules for all subprojects. Subprojects can extend/override.
+
+---
+
+## Core Philosophy
+
+**Small, Smart, Strong**
+- Small changes, well-tested
+- Smart solutions, not over-engineered
+- Strong foundations before features
+
+---
+
+## Debugging Methodology
+
+### Inverted Confidence Rule
+
+**Code I wrote this session**: 20% confidence it's correct
+- Assume I made a mistake
+- Prove it works before moving on
+- Test thoroughly
+
+**Existing code**: 80% confidence it's correct
+- Assume it works as intended
+- Prove it's broken before touching it
+- Respect that it was tested/debugged
+
+### Debugging Decision Tree
+
+```
+Bug appears
+├─ Is there NEW code involved?
+│  └─ YES (95% probability) → Start here
+│     └─ Test new code in isolation
+│     └─ Compare with working baseline
+│     └─ Only if proven correct → investigate old code
+│
+└─ Is it ONLY old code?
+   └─ Verify nothing changed
+   └─ Check environment, dependencies, inputs
+```
+
+### Before Blaming Existing Code
+
+1. Why would this have worked before if it's broken?
+2. What changed between working and not working?
+3. Is there any NEW code in the path?
+
+If answer to #3 is YES → investigate new code FIRST.
+
+---
+
+## Feature Addition Approach
+
+1. **Understand first** - Read existing code, understand patterns
+2. **Plan before coding** - Explain changes, get confirmation
+3. **Minimal changes** - Don't refactor unrelated code
+4. **Test incrementally** - Small steps, verify each
+5. **Document** - Update TODO, CHANGELOG, relevant docs
+
+---
+
+## Code Change Rules
+
+1. **Focus on explicit request** - Don't add unrequested changes
+2. **Root cause analysis** - For non-trivial bugs, explain before fixing
+3. **Explain fundamental changes** - Before implementing, discuss
+4. **Don't over-commit** - Test before suggesting commit
+5. **Stay doubtful** - Don't assume it works, verify
+
+---
+
+## Error Handling
+
+- Technical issues → Inform user, explain what's being checked
+- Unexpected inputs → Handle gracefully or escalate
+- Escalate early if uncertain
+
+---
+
+## Testing Approach
+
+1. Unit test new functions
+2. Integration test with mocked APIs
+3. End-to-end test with real systems
+4. Log everything during testing
+5. Verify before marking task complete
+
+---
+
+# Rules (Dos & Don'ts)
+
+Hard rules for Claude behavior. Added by user based on observed issues.
+
+**Never remove rules. Only add.**
+
+Format: `R###: Rule description` + Context
+
+---
+
+## General Behavior
+
+**R001**: Do not add "co-author" or Claude Code references in commit messages
+Context: User preference, keep commits clean
+
+**R002**: Do not say "you're absolutely right" or similar excessive validation
+Context: Maintain objectivity, don't sugar coat
+
+**R003**: Do not assume task is done and suggest commit without testing
+Context: Stay doubtful, verify before declaring success
+
+**R004**: Do not start implementation without confirmation when user explains feature
+Context: User wants to see proposed changes first, then approve
+
+**R005**: When explaining changes, wait for confirmation before coding
+Context: Avoid wasted work on wrong approach
+
+**R006**: Always show major file content for review before writing
+Context: User is system designer, needs to approve before files are created
+
+**R007**: Commit after completing each small, logical change
+Context: Git history becomes a book telling the story of how the app was built. Each commit is a chapter. Keeps history clean and reviewable.
+
+---
+
+## Code & Architecture
+
+**R010**: Do not create new files unless absolutely necessary
+Context: Prefer editing existing files
+
+**R011**: Do not refactor unrelated code when fixing a bug
+Context: Focus on explicit request only
+
+**R012**: Do not introduce security vulnerabilities (injection, XSS, etc.)
+Context: Standard security practice
+
+---
+
+## Documentation
+
+**R020**: Update project docs (TODO, CHANGELOG, STATUS) after changes
+Context: Maintain context for future sessions
+
+**R021**: Log debugging experiences in LESSONS.md
+Context: Don't repeat past debugging efforts
+
+---
+
+<!--
+Add new rules below. Use next available R### number.
+Subproject-specific rules go in subproject's PRINCIPLES.md
+-->

commands/pp-init-assets/templates/root/WORKFLOW.md

@@ -0,0 +1,141 @@
+# Project Workflow
+
+How to work with this project management system.
+
+---
+
+## For New Chat Session
+
+```
+1. Read INDEX.md → understand project, current state, active subproject
+2. Read WORKFLOW.md → understand system (this file)
+3. Read PRINCIPLES.md → understand project principles
+4. Go to active subproject folder (listed in INDEX.md)
+5. Read subproject's STATUS.md, TODO.md, CODEBASE.md, CHANGELOG.md
+6. Read subproject PRINCIPLES.md (if exists, overrides root)
+7. Read LESSONS.md → avoid past mistakes
+```
+
+---
+
+## After Making Changes
+
+*All updates happen in the active subproject folder:*
+
+1. **Update TODO.md** - Mark tasks done/in-progress
+2. **Update CHANGELOG.md** - Log what changed with usage examples
+3. **Update STATUS.md** - If system state changed
+4. **Update LESSONS.md** - If debugging insight gained
+5. **Update CODEBASE.md** - If files added/modified
+6. **Update root INDEX.md** - If switching active subproject or adding high-level TODOs
+7. **Commit** - Message references TODO ID
+
+---
+
+## File Update Guidelines
+
+### TODO.md
+- `[ ]` pending
+- `[>]` in progress
+- `[x]` completed
+- `[-]` cancelled
+- Format: `[status] T###: Description`
+- Group by phase/PRD
+
+### CHANGELOG.md
+- Newest first (reverse chronological)
+- Format: `## YYYY-MM-DD | Commit: <hash>`
+- Include: Changes, Usage (examples/commands), Context
+- Archive when >50 entries
+
+### STATUS.md
+- Keep current, not historical
+- Sections: Working, Blocked, Current Focus, Recent Decisions
+- Short bullet points
+
+### LESSONS.md
+- Format: Problem → Investigation → Root Cause → Solution
+- Tag by category: [BUG], [CONFIG], [API], [LOGIC]
+- Include searchable keywords
+
+### CODEBASE.md
+- Update after adding/modifying files
+- One-line descriptions
+- Group by component/purpose
+
+---
+
+## When to Create New PRD
+
+- New phase starting
+- Significant new feature
+- Major refactor
+
+PRD naming: `###_short_name.md` (e.g., `001_initial_setup.md`)
+
+---
+
+## When to Archive
+
+**CHANGELOG.md**:
+- When >50 entries or file getting very long
+- Move older entries to `archive/CHANGELOG_YYYY_MM.md`
+- Update archive index table in CHANGELOG.md with:
+  - Archive filename
+  - Date range
+  - Topic summary
+- Keep index in main file for reference
+
+**PRDs**:
+- Completed PRDs → move to archive/
+- Keep reference in INDEX.md
+
+**Outdated docs**:
+- Move to archive/ with date suffix
+
+---
+
+## Commit Message Format
+
+```
+<type>: <short description>
+
+[T###] <todo item completed>
+[T###] <another if multiple>
+
+<optional details>
+```
+
+Types: feat, fix, docs, refactor, test
+
+Example:
+```
+feat: Add user authentication
+
+[T010] Create auth service
+[T011] Add login endpoint
+
+Using JWT with 24h expiry
+```
+
+---
+
+## File Inheritance
+
+Root files apply to all subprojects. Subproject files extend/override.
+
+**Reading order:**
+1. Root level files (base)
+2. Subproject files (extends/overrides)
+
+Example: Root PRINCIPLES.md has base rules, subproject PRINCIPLES.md adds specific rules.
+
+---
+
+## Principles Reference
+
+Before debugging or adding features, check:
+1. PRINCIPLES.md - methodology (root + subproject)
+2. LESSONS.md - past solutions (root + subproject)
+
+Don't repeat past mistakes.

commands/pp-init-assets/templates/subproject/CHANGELOG.md

@@ -0,0 +1,44 @@
+# {{SUBPROJECT_NAME}} Changelog
+
+{{SUBPROJECT_NAME}}-specific changes. See root CHANGELOG for cross-project changes.
+
+Reverse chronological. Newest first.
+
+---
+
+## Archived Changelogs
+
+| Archive | Period | Topics |
+|---------|--------|--------|
+| (none yet) | - | - |
+
+---
+
+## {{DATE}} | Subproject Created
+
+**Changes**:
+- Created {{SUBPROJECT_NAME}}/ subproject structure
+- Initial files added
+
+**Context**:
+- {{CREATION_CONTEXT}}
+
+---
+
+<!--
+Template:
+
+## YYYY-MM-DD | Commit: <hash>
+
+**Tasks Completed**:
+- [T###] Description
+
+**Changes**:
+- What was added/modified/removed
+
+**Usage**:
+- How to use what was added
+
+**Context**:
+- Why, decisions made
+-->

commands/pp-init-assets/templates/subproject/CODEBASE.md

@@ -0,0 +1,33 @@
+# {{SUBPROJECT_NAME}} Codebase Map
+
+{{SUBPROJECT_NAME}}-specific files. See root CODEBASE.md for shared files.
+
+---
+
+## Existing Files
+
+| File | Description |
+|------|-------------|
+{{EXISTING_FILES}}
+
+---
+
+## To Be Created
+
+| File | Description |
+|------|-------------|
+{{TO_CREATE_FILES}}
+
+---
+
+## Dependencies
+
+| File | Source | Description |
+|------|--------|-------------|
+{{FILE_DEPENDENCIES}}
+
+---
+
+<!--
+Update after creating/modifying subproject-specific files
+-->

commands/pp-init-assets/templates/subproject/INDEX.md

@@ -0,0 +1,45 @@
+# {{SUBPROJECT_NAME}} - {{SUBPROJECT_TITLE}}
+
+**Subproject**: {{SUBPROJECT_DESCRIPTION}}
+**Status**: {{SUBPROJECT_STATUS}}
+**Created**: {{DATE}}
+
+---
+
+## Quick Start
+
+1. Read root INDEX.md and PRINCIPLES.md first (base context)
+2. Read this INDEX.md
+3. Read STATUS.md (current state)
+4. Read TODO.md (pending tasks)
+5. Read PRINCIPLES.md (subproject-specific rules)
+
+---
+
+## Scope
+
+{{SCOPE}}
+
+---
+
+## File Map
+
+| File | Purpose |
+|------|---------|
+| INDEX.md | This overview |
+| STATUS.md | Current state |
+| TODO.md | Task tracking |
+| CHANGELOG.md | Subproject changes |
+| PRINCIPLES.md | Subproject-specific rules |
+| CODEBASE.md | Subproject-specific files |
+| LESSONS.md | Subproject-specific lessons |
+
+---
+
+## Dependencies
+
+{{DEPENDENCIES}}
+
+---
+
+<!-- Expand as work begins -->

commands/pp-init-assets/templates/subproject/LESSONS.md

@@ -0,0 +1,22 @@
+# {{SUBPROJECT_NAME}} Lessons Learned
+
+{{SUBPROJECT_NAME}}-specific debugging experiences. See root LESSONS.md for shared lessons.
+
+---
+
+## Format
+
+```
+### [TAG] Short Title
+**Problem**: What went wrong
+**Investigation**: What was tried
+**Root Cause**: Why it happened
+**Solution**: How it was fixed
+**Keywords**: searchable terms
+```
+
+Tags: [BUG], [CONFIG], [API], [LOGIC], [INTEGRATION]
+
+---
+
+<!-- Add subproject-specific lessons below -->

commands/pp-init-assets/templates/subproject/PRINCIPLES.md

@@ -0,0 +1,22 @@
+# {{SUBPROJECT_NAME}} Principles & Rules
+
+{{SUBPROJECT_NAME}}-specific methodology and rules. Extends root PRINCIPLES.md.
+
+---
+
+## {{SUBPROJECT_NAME}}-Specific Principles
+
+{{PRINCIPLES}}
+
+---
+
+## {{SUBPROJECT_NAME}}-Specific Rules
+
+{{RULES}}
+
+---
+
+<!--
+Add subproject-specific rules below.
+Use R### numbering in reserved range for this subproject
+-->

commands/pp-init-assets/templates/subproject/STATUS.md

@@ -0,0 +1,34 @@
+# {{SUBPROJECT_NAME}} Status
+
+**Last Updated**: {{DATE}}
+**Status**: {{SUBPROJECT_STATUS}}
+
+---
+
+## What's Working
+
+{{WORKING}}
+
+---
+
+## What's Not Working / Blocked
+
+{{BLOCKED}}
+
+---
+
+## Current Focus
+
+{{FOCUS}}
+
+---
+
+## Environment
+
+{{ENVIRONMENT}}
+
+---
+
+## Next Actions
+
+{{NEXT_ACTIONS}}

commands/pp-init-assets/templates/subproject/TODO.md

@@ -0,0 +1,26 @@
+# {{SUBPROJECT_NAME}} TODO
+
+**Format**: `[status] T###: Description`
+- `[ ]` pending
+- `[>]` in progress
+- `[x]` completed
+- `[-]` cancelled
+
+---
+
+## Phase 1
+
+{{PHASE_1_TASKS}}
+
+---
+
+## Future Phases
+
+{{FUTURE_TASKS}}
+
+---
+
+## Notes
+
+- T### IDs are permanent, never reuse
+- Reference T### in commit messages and CHANGELOG