Initial commit

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.