Rebrand "devlog entry" → "work item" across reorganization docs and add migration guidance

- Add TERMINOLOGY_REBRAND.md with rationale, options, mental model, and migration strategy
- Introduce "work item" as the recommended term and document mapping (DevlogEntry → WorkItem)
- Add guidance to create a type alias: `type WorkItem = DevlogEntry` and export it from core types for backward compatibility
- Update CODEBASE_REORGANIZATION_SUMMARY.md, README.md, REORGANIZATION_PLAN.md, and QUICK_WINS.md to:
  - Promote "work item" terminology in examples, checklists, timelines, and target state visuals
  - Update API/route, UI, and MCP tooling naming (e.g. /work-items, mcp_work_item_create, mcp_work_item_update, etc.)
  - Add notes about preserving backward compatibility, deprecation path, and no immediate DB migrations
- Adjust quick-win tasks and estimated times to include the terminology rebrand and exporting the WorkItem alias
- Clarify UI/UX and code-structure tasks to rename/devise work-item locations (work-items vs devlog-entries) and maintain compatibility during phased migration

Author: tikazyq

CODEBASE_REORGANIZATION_SUMMARY.md

@@ -34,21 +34,26 @@ I've created a comprehensive reorganization plan to help you clean up the codeba
 - Comprehensive design documentation
 
 **⚠️ Clarity Issues:**
-- Mixed terminology creates confusion about product focus
-- Documentation emphasizes "devlog work tracking" over "agent observability"
+- Confusing terminology: "devlog entry" is not intuitive (→ rebrand to "work item")
+- Mixed priorities in documentation (work tracking vs. agent observability)
 - Code not organized by feature domains
 - READMEs don't reflect the new vision
 
 ### The Good News
 
-Most of your "mess" is just **organizational, not technical debt**. You don't need to rewrite code - just reorganize and rebrand to match your new vision.
+Most of your "mess" is just **organizational, not technical debt**. You don't need to rewrite code - just reorganize, rebrand terminology, and restructure to match your new vision.
 
 ## 🚀 Recommended Approach
 
 ### Start with Quick Wins (This Week)
 
 Focus on the high-impact, low-risk changes from [QUICK_WINS.md](./docs/dev/20251021-codebase-reorganization/QUICK_WINS.md):
 
+**Priority 0: Terminology Rebrand (30 minutes)**
+- Add `type WorkItem = DevlogEntry` alias
+- Update documentation to use "work item" instead of "devlog entry"
+- Make terminology industry-standard and intuitive
+
 **Day 1-2: Documentation (2-3 hours)**
 - Update root README.md to lead with AI agent observability
 - Update AGENTS.md with agent observability workflow
@@ -69,22 +74,25 @@ Focus on the high-impact, low-risk changes from [QUICK_WINS.md](./docs/dev/20251
 ### Then Proceed with Full Reorganization (Next 3 Weeks)
 
 Follow the [4-week plan](./docs/dev/20251021-codebase-reorganization/REORGANIZATION_PLAN.md):
-- **Week 2**: Move code to new structure
-- **Week 3**: Reorganize UI/UX  
-- **Week 4**: Finalize APIs and integrations
+- **Week 1**: Documentation & terminology rebrand (work item)
+- **Week 2**: Move code to new structure  
+- **Week 3**: Reorganize UI/UX (rename labels, update navigation)
+- **Week 4**: Finalize APIs and integrations (support both naming conventions)
 
 ## 📋 Immediate Next Actions
 
 ### 1. Review the Plans
+- [ ] Read [TERMINOLOGY_REBRAND.md](./docs/dev/20251021-codebase-reorganization/TERMINOLOGY_REBRAND.md) (5 minutes) - Why "work item"
 - [ ] Read [QUICK_WINS.md](./docs/dev/20251021-codebase-reorganization/QUICK_WINS.md) (10 minutes)
 - [ ] Skim [REORGANIZATION_PLAN.md](./docs/dev/20251021-codebase-reorganization/REORGANIZATION_PLAN.md) (20 minutes)
 - [ ] Decide if you agree with the approach
 
 ### 2. Start Quick Wins
 Pick one and start:
-- **Option A**: Update README.md (1 hour, highest impact)
-- **Option B**: Add service documentation (1 hour, improves code navigation)
-- **Option C**: Create folder structure (1 hour, sets foundation)
+- **Option A**: Add WorkItem type alias (5 minutes, enables gradual migration)
+- **Option B**: Update README.md (1 hour, highest impact)
+- **Option C**: Add service documentation (1 hour, improves code navigation)
+- **Option D**: Create folder structure (1 hour, sets foundation)
 
 ### 3. Track Progress
 Use the checklists in each document to track your progress.
@@ -95,6 +103,7 @@ Use the checklists in each document to track your progress.
 ```
 devlog (work tracking tool)
   └── with some agent observability features
+      └── "devlog entries" (confusing name)
 ```
 
 ### Target State
@@ -108,31 +117,32 @@ AI Agent Observability Platform
   │
   └── Project management (SECONDARY - Supporting)
       ├── Project organization
-      └── Optional devlog entries
+      └── Optional work items (features, bugs, tasks)
+          └── Renamed from "devlog entries"
 ```
 
 ## 💡 Key Insights
 
 ### 1. You Don't Need a Big Rewrite
 Your technical architecture is sound. You mainly need to:
 - **Reorganize** code into logical feature domains
-- **Rebrand** documentation to emphasize agent observability
+- **Rebrand** terminology ("work item" not "devlog entry")
 - **Restructure** UI to make agent features primary
 
 ### 2. Your Database Schema is Already Ready
 The Prisma schema already has:
 - `agent_events` table with proper indexes
 - `agent_sessions` table
 - Relationships to projects
-- No migrations needed!
+- No migrations needed! (table names can stay internal)
 
 ### 3. Services Exist, Just Need Organization
 You have:
 - `AgentEventService` ✅
 - `AgentSessionService` ✅
 - `ProjectService` ✅
 
-Just need to organize them clearly as "agent observability" (primary) vs "project management" (secondary).
+Just need to organize them clearly as "agent observability" (primary) vs "project management" (secondary), and rename devlog-service → work-item-service.
 
 ### 4. The Go Collector is Your Next Big Win
 After reorganization, focus on completing the Go collector (already 20% done). That's where the real value unlock happens.
@@ -155,25 +165,25 @@ packages/core/src/
 │   ├── sessions/
 │   └── analytics/
 ├── project-management/      📁 SECONDARY
-│   ├── devlog-entries/
+│   ├── work-items/          (renamed from devlog-entries)
 │   └── projects/
 └── services/                🔧 CONSOLIDATED
 ```
 
 ## ❓ Questions to Consider
 
 1. **Repository Rename?**
-   - Current: `devlog` (implies work tracking)
-   - Consider: `agent-observatory`, `ai-agent-insights`, or keep `devlog` as brand name
+   - Current: `devlog` (brand name)
+   - Decision: **Keep "devlog" as brand**, just clarify what items inside are called ("work items")
 
 2. **How Aggressive on Deprecation?**
-   - Conservative: Keep everything, just reorganize
+   - Conservative: Keep everything, just add aliases ✅ **Recommended**
    - Moderate: Mark old APIs as deprecated
    - Aggressive: Remove unused code
 
 3. **Timeline Constraints?**
    - Can you dedicate 4 weeks to this?
-   - Or prefer slower, incremental approach?
+   - Or prefer slower, incremental approach? ✅ **Recommended - start with quick wins**
 
 ## 🎓 Learning from This
 

docs/dev/20251021-codebase-reorganization/QUICK_WINS.md

@@ -2,6 +2,51 @@
 
 **Goal**: Start reorganization with high-impact, low-risk changes that immediately improve code clarity.
 
+## 🎯 Priority 0: Terminology Rebrand (30 minutes)
+
+Rename "devlog entry" to "work item" for better clarity and industry alignment.
+
+### Why "Work Item"?
+- ✅ Industry standard (Azure DevOps, GitHub Projects)
+- ✅ Immediately understandable to developers
+- ✅ Versatile - works for features, bugs, tasks, refactors
+- ✅ Aligns with AI observability: "agents help complete work items"
+
+### Quick Implementation
+
+**1. Add Type Alias** (5 minutes)
+
+**File**: `packages/core/src/types/core.ts`
+
+Add at the top:
+```typescript
+/**
+ * Work Item - Industry-standard terminology for trackable work
+ * @deprecated Use WorkItem instead of DevlogEntry in new code
+ */
+export type WorkItem = DevlogEntry;
+```
+
+**2. Update Package Exports** (5 minutes)
+
+**File**: `packages/core/src/types/index.ts`
+
+Add export:
+```typescript
+export type { WorkItem } from './core.js';
+```
+
+**3. Document the Change** (20 minutes)
+
+Add to README files and documentation:
+- "Track **work items** (features, bugs, tasks) alongside agent activities"
+- "Organize **work items** by project"
+- "See which **work items** AI agents are working on"
+
+See [TERMINOLOGY_REBRAND.md](./TERMINOLOGY_REBRAND.md) for detailed migration plan.
+
+---
+
 ## 🎯 Priority 1: Documentation Updates (1-2 hours)
 
 These changes immediately clarify the project vision without breaking any code.
@@ -29,7 +74,8 @@ These changes immediately clarify the project vision without breaking any code.
 mcp_agent_start_session({
   agentId: "github-copilot",
   projectId: 1,
-  objective: "Implement user authentication"
+  objective: "Implement user authentication",
+  workItemId: 123  // Optional: link to work item
 });
 
 // During work - events logged automatically by collector
@@ -46,6 +92,23 @@ mcp_agent_end_session({
   summary: "Implemented JWT-based auth with tests"
 });
 ```
+
+### When Managing Work Items (Optional)
+```
+// Create a work item to organize work
+mcp_work_item_create({
+  title: "Implement user authentication",
+  type: "feature",
+  description: "Add JWT-based authentication system"
+});
+
+// Update progress
+mcp_work_item_update({
+  id: 123,
+  status: "in-progress",
+  note: "Completed login endpoint"
+});
+```
 ```
 
 ### 3. Create Agent Observability Quick Start
@@ -172,9 +235,9 @@ Create `packages/core/src/project-management/index.ts`:
 
 // Re-export from existing locations
 export * from '../services/project-service.js';
-export * from '../services/devlog-service.js';
+export * from '../services/devlog-service.js';  // TODO: rename to work-item-service
 export * from '../types/project.js';
-export * from '../types/devlog.js';
+export * from '../types/core.js';  // Includes WorkItem type alias
 
 // TODO: Move actual files here in next phase
 ```
@@ -247,8 +310,18 @@ export const agentObservabilityTools = [
 
 export const projectManagementTools = [
   {
-    name: 'mcp_devlog_create',
-    description: '[PROJECT MANAGEMENT] Create a new devlog entry for work tracking...',
+    name: 'mcp_work_item_create',
+    description: '[PROJECT MANAGEMENT] Create a new work item (feature, bug, task) for tracking...',
+    // ...
+  },
+  {
+    name: 'mcp_work_item_update',
+    description: '[PROJECT MANAGEMENT] Update a work item with progress, status changes...',
+    // ...
+  },
+  {
+    name: 'mcp_work_item_list',
+    description: '[PROJECT MANAGEMENT] List and search work items with filters...',
     // ...
   },
   // ... more project tools
@@ -284,12 +357,12 @@ PRIMARY FEATURES - Agent Observability:
 • Code quality assessment for AI-generated code
 
 SUPPORTING FEATURES - Project Management:
-• Optional work item tracking (devlog entries)
+• Optional work item tracking (features, bugs, tasks)
 • Project organization and context management
 • Documentation and note-taking
 
 Use agent_* tools for observability features.
-Use devlog_* and project_* tools for project management.
+Use work_item_* and project_* tools for project management.
 `,
   },
   // ...
@@ -318,7 +391,7 @@ Core services and types for the AI Coding Agent Observability Platform.
 
 ### 📊 Project Management (Supporting)
 - **Project Organization**: Organize sessions by project
-- **Work Tracking**: Optional devlog entry system
+- **Work Item Tracking**: Optional system for tracking features, bugs, tasks
 - **Document Management**: Attach files and notes
 
 ## Usage
@@ -343,7 +416,8 @@ await AgentEventService.getInstance().logEvent({
 
 ### Project Management
 ```typescript
-import { ProjectService, DevlogService } from '@codervisor/devlog-core/server';
+import { ProjectService, WorkItem } from '@codervisor/devlog-core/server';
+// Note: WorkItem is an alias for DevlogEntry for backward compatibility
 
 // Manage projects
 const project = await ProjectService.getInstance().create({
@@ -363,6 +437,8 @@ const project = await ProjectService.getInstance().create({
 After completing quick wins:
 
 - [ ] All README files emphasize agent observability as primary feature
+- [ ] "Work item" terminology used instead of "devlog entry"
+- [ ] WorkItem type alias exported from core package
 - [ ] Code comments clearly distinguish primary vs. secondary features  
 - [ ] New folder structure exists (even if files not moved yet)
 - [ ] MCP tools are categorized by feature domain
@@ -382,7 +458,13 @@ After quick wins are complete:
 
 ## 📝 Estimated Time
 
-- **Total**: 6-8 hours of focused work
+- **Total**: 6.5-8.5 hours of focused work
+  - Priority 0 (Terminology): 30 minutes
+  - Priority 1 (Documentation): 2-3 hours
+  - Priority 2 (Code Comments): 1 hour
+  - Priority 3 (File Organization): 2-3 hours
+  - Priority 4 (MCP Tools): 1 hour
+  - Priority 5 (READMEs): 1 hour
 - **Can be done incrementally**: Yes, each priority is independent
 - **Breaking changes**: None
 - **Risk level**: Very low