docs: add CHANGELOG and TODO templates, update rules

CHANGELOG.package.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- Initial setup
+
+---
+
+## [0.1.0] - YYYY-MM-DD
+
+### Added
+- Feature 1
+- Feature 2
+
+### Changed
+- Change 1
+
+### Fixed
+- Bug fix 1
+
+---
+
+## Template Usage
+
+1. Replace `YYYY-MM-DD` with actual date
+2. Update sections for each release
+3. Move [Unreleased] items to new version on release
+4. Remove this section

CLAUDE.md

@@ -289,44 +289,68 @@ git push origin main --tags
 
 **⛔ MUST read `./ROADMAP.md` first** to understand current status.
 
-## ROADMAP.md Rules (MANDATORY)
+## Package Documentation (MANDATORY)
 
-**⛔ Every monorepo MUST have ROADMAP.md files:**
+**⛔ Every package/app MUST have these files:**
 
-| Location | Purpose |
+| File | Purpose |
-|----------|---------|
+|------|---------|
-| `/ROADMAP.md` | Master roadmap: phases, architecture, status table |
+| `ROADMAP.md` | Milestones, tasks with checkboxes |
-| `/packages/*/ROADMAP.md` | Package roadmap: detailed milestones, tasks |
+| `CHANGELOG.md` | Version history, what changed |
-| `/apps/*/ROADMAP.md` | App roadmap: features, UI/UX tasks |
+| `TODO.md` | Technical debt, known issues |
+
+**Root level:**
+
+| File | Purpose |
+|------|---------|
+| `/ROADMAP.md` | Master: phases, architecture, status table |
+| `/CHANGELOG.md` | Optional: root-level changes only |
+
+## ROADMAP.md Rules
+
+| Rule | Requirement |
+|------|-------------|
+| Structure | Phases → Milestones → Tasks with `[x]`/`[ ]` |
+| Versioning | Independent semver per package (v0.1.0) |
+| Dependencies | Show "Depends on: package vX.X.X" |
+| Status | ✅ Completed, 🔄 In Progress, ⏳ Planned |
+
+## CHANGELOG.md Rules
+
+**Format:** [Keep a Changelog](https://keepachangelog.com/)
 
-**Root ROADMAP.md:**
 ```markdown
-## Current Status
+## [0.2.0] - 2025-01-15
-| Package | Version | Next Milestone |
+### Added
-|---------|---------|----------------|
+- New feature X
-| @project/core | v0.2.0 ✅ | v0.3.0 - Feature |
+### Fixed
-```
+- Bug in Y
-
+### Changed
-**Package ROADMAP.md:**
+- Refactored Z
-```markdown
-## v0.3.0 - Feature Name
-| Task | Status |
-|------|--------|
-| Entity: Name | [x] |
-| Use case | [ ] |
-```
-
-**Status indicators:**
-```
-✅ Completed | 🔄 In Progress | ⏳ Planned
 ```
 
 **⛔ RULES:**
-- Root ROADMAP = bird's eye view (phases, dependencies)
+- Update BEFORE release (not after)
-- Package ROADMAP = detailed tasks (checkboxes)
+- Group by: Added, Changed, Fixed, Removed
-- Update BEFORE starting new milestone
+- Link to issues/PRs when relevant
-- Mark tasks `[x]` immediately when done
+
-- Never skip dependency order
+## TODO.md Rules (Technical Debt)
+
+**Format:**
+```markdown
+## High Priority
+- [ ] Fix memory leak in X (#123)
+- [x] ~~Refactor auth module~~ (done in v0.2.0)
+
+## Low Priority
+- [ ] Add caching to Y
+```
+
+**⛔ RULES:**
+- Add items when you notice shortcuts/hacks
+- Mark `[x]` when resolved
+- Reference in commits: `fix(api): resolve issue (TODO #3)`
+- Review before each release
 
 **Dependency order (always):**
 ```

README.md

@@ -8,7 +8,9 @@ Standard templates for Claude Code configuration across all projects.
 |------|-------------|
 | `CLAUDE.md` | Claude Code configuration with all mandatory rules |
 | `ROADMAP.md` | Root roadmap: phases, architecture, status table |
-| `ROADMAP.package.md` | Package roadmap: detailed milestones per package |
+| `ROADMAP.package.md` | Package roadmap: detailed milestones |
+| `CHANGELOG.package.md` | Package changelog: version history |
+| `TODO.package.md` | Package TODO: technical debt tracker |
 
 ## Usage
 
@@ -17,7 +19,8 @@ Standard templates for Claude Code configuration across all projects.
    - `ROADMAP.md` → `/ROADMAP.md`
 2. Copy to each package/app:
    - `ROADMAP.package.md` → `/packages/*/ROADMAP.md`
-   - `ROADMAP.package.md` → `/apps/*/ROADMAP.md`
+   - `CHANGELOG.package.md` → `/packages/*/CHANGELOG.md`
+   - `TODO.package.md` → `/packages/*/TODO.md`
 3. Replace placeholders:
    - `PROJECT_NAME` → your project name
    - `@project/*` → your package prefix (e.g., `@myapp/*`)

TODO.package.md

@@ -0,0 +1,39 @@
+# TODO - Technical Debt
+
+Track known issues, shortcuts, and improvements needed.
+
+## High Priority
+
+> Critical issues that should be fixed soon.
+
+- [ ] Example: Fix memory leak in X component
+
+## Medium Priority
+
+> Important but not urgent.
+
+- [ ] Example: Add proper error handling to Y
+- [ ] Example: Refactor Z for better performance
+
+## Low Priority
+
+> Nice to have, can wait.
+
+- [ ] Example: Add more unit tests
+- [ ] Example: Improve documentation
+
+## Completed
+
+> Resolved items (keep for history).
+
+- [x] ~~Example task~~ (resolved in v0.1.0)
+
+---
+
+## Template Usage
+
+1. Add items when you notice issues during development
+2. Mark `[x]` and move to Completed when resolved
+3. Reference in commits: `fix(pkg): resolve issue (TODO #3)`
+4. Review before each release
+5. Remove this section