From 3e2bd9cdb0efd4b59692b9e5d795042c7a2bf6f5 Mon Sep 17 00:00:00 2001
From: imfozilbek <fozilbek.samiyev@gmail.com>
Date: Mon, 22 Dec 2025 00:42:17 +0500
Subject: [PATCH] docs: add package-level ROADMAP template

---
 CLAUDE.md          | 37 +++++++++++++----------
 README.md          | 18 +++++++----
 ROADMAP.package.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 108 insertions(+), 22 deletions(-)
 create mode 100644 ROADMAP.package.md

diff --git a/CLAUDE.md b/CLAUDE.md
index f452a84..1f0c12f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -291,24 +291,29 @@ git push origin main --tags
 
 ## ROADMAP.md Rules (MANDATORY)
 
-**⛔ Every monorepo MUST have `ROADMAP.md` in root.**
+**⛔ Every monorepo MUST have ROADMAP.md files:**
 
-| Rule | Requirement |
-|------|-------------|
-| **Structure** | Phases → Milestones → Tasks with checkboxes |
-| **Versioning** | Each package has independent semver (v0.1.0) |
-| **Dependencies** | Show "Depends on: package vX.X.X" |
-| **Status table** | Current version + next milestone per package |
-| **Architecture** | ASCII diagram of package relationships |
+| Location | Purpose |
+|----------|---------|
+| `/ROADMAP.md` | Master roadmap: phases, architecture, status table |
+| `/packages/*/ROADMAP.md` | Package roadmap: detailed milestones, tasks |
+| `/apps/*/ROADMAP.md` | App roadmap: features, UI/UX tasks |
 
-**Milestone format:**
+**Root ROADMAP.md:**
 ```markdown
-#### 1.1 @project/core v0.1.0 - Feature Name
-> **Depends on:** `@project/other v0.1.0`
+## Current Status
+| Package | Version | Next Milestone |
+|---------|---------|----------------|
+| @project/core | v0.2.0 ✅ | v0.3.0 - Feature |
+```
 
+**Package ROADMAP.md:**
+```markdown
+## v0.3.0 - Feature Name
 | Task | Status |
 |------|--------|
-| Task description | [x] or [ ] |
+| Entity: Name | [x] |
+| Use case | [ ] |
 ```
 
 **Status indicators:**
@@ -317,11 +322,11 @@ git push origin main --tags
 ```
 
 **⛔ RULES:**
-- Update ROADMAP.md BEFORE starting new milestone
+- Root ROADMAP = bird's eye view (phases, dependencies)
+- Package ROADMAP = detailed tasks (checkboxes)
+- Update BEFORE starting new milestone
 - Mark tasks `[x]` immediately when done
-- Update "Current Status" table after each release
-- Never skip dependency order (core → api → clients)
-- One package version = one atomic milestone
+- Never skip dependency order
 
 **Dependency order (always):**
 ```
diff --git a/README.md b/README.md
index 9f2f50d..5d9aadf 100644
--- a/README.md
+++ b/README.md
@@ -7,18 +7,24 @@ Standard templates for Claude Code configuration across all projects.
 | File | Description |
 |------|-------------|
 | `CLAUDE.md` | Claude Code configuration with all mandatory rules |
-| `ROADMAP.md` | Monorepo roadmap template with phases and milestones |
+| `ROADMAP.md` | Root roadmap: phases, architecture, status table |
+| `ROADMAP.package.md` | Package roadmap: detailed milestones per package |
 
 ## Usage
 
-1. Copy `CLAUDE.md` and `ROADMAP.md` to your new project root
-2. Replace placeholders:
+1. Copy to project root:
+   - `CLAUDE.md` → `/CLAUDE.md`
+   - `ROADMAP.md` → `/ROADMAP.md`
+2. Copy to each package/app:
+   - `ROADMAP.package.md` → `/packages/*/ROADMAP.md`
+   - `ROADMAP.package.md` → `/apps/*/ROADMAP.md`
+3. Replace placeholders:
    - `PROJECT_NAME` → your project name
    - `@project/*` → your package prefix (e.g., `@myapp/*`)
    - `/path/to/project` → actual project path
-3. Update package table with your packages
-4. Add project-specific sections if needed
-5. Remove "Template Usage" section
+4. Update package table with your packages
+5. Add project-specific sections if needed
+6. Remove "Template Usage" sections
 
 ## What's Included
 
diff --git a/ROADMAP.package.md b/ROADMAP.package.md
new file mode 100644
index 0000000..5bf474d
--- /dev/null
+++ b/ROADMAP.package.md
@@ -0,0 +1,75 @@
+# @project/package Roadmap
+
+## Current Version: v0.0.0
+
+## v0.1.0 - Foundation
+
+**Status:** ⏳ Planned
+
+**Goal:** Brief description of what this version achieves.
+
+| Task | Status |
+|------|--------|
+| Setup package structure | [ ] |
+| Add base types/interfaces | [ ] |
+| Write unit tests | [ ] |
+| Build & verify | [ ] |
+
+---
+
+## v0.2.0 - Core Features
+
+**Status:** ⏳ Planned
+
+**Depends on:** v0.1.0
+
+| Task | Status |
+|------|--------|
+| Feature 1 | [ ] |
+| Feature 2 | [ ] |
+| Tests | [ ] |
+| Build & verify | [ ] |
+
+---
+
+## v0.3.0 - Enhanced Features
+
+**Status:** ⏳ Planned
+
+**Depends on:** v0.2.0
+
+| Task | Status |
+|------|--------|
+| Enhancement 1 | [ ] |
+| Enhancement 2 | [ ] |
+| Tests | [ ] |
+| Build & verify | [ ] |
+
+---
+
+## v1.0.0 - Stable Release
+
+**Status:** ⏳ Planned
+
+**Criteria:**
+- [ ] All planned features implemented
+- [ ] 90% test coverage
+- [ ] Documentation complete
+- [ ] No known bugs
+
+---
+
+## Version History
+
+| Version | Date | Description |
+|---------|------|-------------|
+| v0.0.0 | TBD | Initial setup |
+
+---
+
+## Template Usage
+
+1. Replace `@project/package` with actual package name
+2. Define milestones based on root ROADMAP.md
+3. Add specific tasks for this package
+4. Remove this section