project-root/
├── .claude/
│   └── CLAUDE.md              # Project context (always loaded)
├── docs/
│   ├── PROJECT.md             # Project overview and goals
│   ├── ROADMAP.md             # Project roadmap and milestones
│   ├── DECISIONS.md           # Architecture and design decisions
│   ├── MEETINGS.md            # Meeting notes log
│   ├── CHANGELOG.md           # Project changelog
│   └── architecture/          # Architecture diagrams and docs
├── tasks/
│   ├── BACKLOG.md             # Feature backlog
│   ├── TODO.md                # Current tasks and priorities
│   └── DONE.md                # Completed tasks archive
├── sprints/                   # Sprint-specific planning (if using sprints)
│   ├── sprint-01.md
│   └── sprint-02.md
└── README.md                  # Project README

# Project Name

## Overview
Brief description of what this project does and why it exists.

## Goals
1. Primary goal
2. Secondary goal
3. Success metrics

## Scope

### In Scope
- Feature A
- Feature B
- Integration with X

### Out of Scope
- Feature C (future consideration)
- Platform Y support (not planned)

## Stakeholders
- **Owner**: Name/Role
- **Contributors**: Names
- **Users**: Target audience

## Tech Stack
- Language: Python 3.11
- Framework: FastAPI
- Database: PostgreSQL
- Deployment: Docker/K8s

## Timeline
- **Start Date**: 2026-01-02
- **Target Beta**: 2026-03-15
- **Target Release**: 2026-05-01

## Resources
- Repository: https://github.com/user/project
- Documentation: https://docs.project.com
- Issue Tracker: GitHub Issues

## Current Status
**Status**: 🟢 On Track | 🟡 At Risk | 🔴 Blocked

Last Updated: 2026-01-02

Current Phase: Planning / Development / Testing / Deployed

Recent Progress:
- Completed initial setup
- Database schema designed
- API endpoints scaffolded

Next Steps:
- Implement authentication
- Add unit tests
- Deploy to staging

# Project Roadmap

## Vision
Long-term vision for the project (1-2 years)

## Milestones

### Q1 2026: Foundation
**Goal**: Core functionality working
- [x] Project setup and infrastructure
- [x] Database design
- [ ] Authentication system
- [ ] Core API endpoints
- [ ] Basic frontend

**Success Criteria**:
- Users can sign up and log in
- Basic CRUD operations work
- Deployment pipeline functional

### Q2 2026: Feature Development
**Goal**: Key features implemented
- [ ] Advanced feature A
- [ ] Integration with service B
- [ ] Mobile-responsive UI
- [ ] Performance optimization

**Success Criteria**:
- All core features functional
- Performance targets met (< 200ms API response)
- 80%+ test coverage

### Q3 2026: Polish & Launch
**Goal**: Production-ready release
- [ ] Security audit
- [ ] User testing
- [ ] Documentation complete
- [ ] Marketing materials
- [ ] Public launch

**Success Criteria**:
- Zero critical bugs
- Documentation complete
- 100 active users in first month

## Features Backlog

### High Priority
1. User authentication (Q1)
2. Data export functionality (Q1)
3. Real-time notifications (Q2)

### Medium Priority
4. Advanced search (Q2)
5. Team collaboration features (Q2)
6. API v2 (Q3)

### Low Priority / Future
7. Mobile app (Q4)
8. Third-party integrations (2027)
9. Enterprise features (2027)

## Dependencies
- Dependency on external API (blocking Q2 features)
- Designer availability (needed for Q2)

## Risks
- **High**: External API stability unknown
- **Medium**: Limited team resources
- **Low**: Technology choice may need revision

# Decision Log

## How to Use This Log
Document all significant architectural and design decisions.

**Format**:
- **Date**: When decision was made
- **Decision**: What was decided
- **Context**: Why this decision was needed
- **Options Considered**: Alternatives evaluated
- **Rationale**: Why this option was chosen
- **Consequences**: Expected impact and trade-offs
- **Status**: Proposed / Accepted / Deprecated / Superseded

---

## [2026-01-02] Database Choice: PostgreSQL

**Context**: Need to choose a database for the project. Requirements include:
- ACID compliance
- Good performance with relational data
- JSON support for flexible schemas
- Mature ecosystem

**Options Considered**:
1. **PostgreSQL** - Relational, ACID, JSON support
2. **MySQL** - Relational, widely used
3. **MongoDB** - Document store, flexible schema
4. **SQLite** - Simple, file-based

**Decision**: Use PostgreSQL

**Rationale**:
- Best balance of features for our needs
- Excellent JSON/JSONB support (flexibility + structure)
- Strong ACID guarantees
- Team has PostgreSQL experience
- Great tooling and extension ecosystem
- Better for complex queries than MongoDB
- More robust than SQLite for multi-user

**Consequences**:
- ✅ Strong data consistency
- ✅ Complex queries well-supported
- ✅ Can evolve schema as needed (JSONB)
- ⚠️ Requires proper hosting (not embedded like SQLite)
- ⚠️ Learning curve for advanced features

**Status**: ✅ Accepted

---

## [2026-01-05] API Framework: FastAPI vs Flask

**Context**: Choose Python web framework for REST API

**Options Considered**:
1. **FastAPI** - Modern, async, type hints, auto docs
2. **Flask** - Mature, simple, flexible
3. **Django REST** - Full-featured, batteries included

**Decision**: Use FastAPI

**Rationale**:
- Built-in async support (better performance)
- Automatic API documentation (OpenAPI/Swagger)
- Type hints reduce bugs
- Modern Python practices
- Excellent for APIs (not general web apps)

**Consequences**:
- ✅ Better performance with async
- ✅ Type safety catches errors early
- ✅ Self-documenting API
- ⚠️ Smaller ecosystem than Flask
- ⚠️ Team needs to learn async patterns

**Status**: ✅ Accepted

---

## Template for New Decisions

## [YYYY-MM-DD] Decision Title

**Context**: Why this decision is needed

**Options Considered**:
1. Option A
2. Option B
3. Option C

**Decision**: Chosen option

**Rationale**: Why this option was chosen

**Consequences**:
- Positive impacts
- Negative impacts
- Trade-offs

**Status**: Proposed / Accepted / Deprecated

# Current Tasks

Last Updated: 2026-01-02

## In Progress

### High Priority 🔴
- [ ] **Implement user authentication** (John, Due: 2026-01-10)
  - [x] Set up JWT tokens
  - [ ] Password hashing
  - [ ] Login endpoint
  - [ ] Registration endpoint
  - Blocked by: None

### Medium Priority 🟡
- [ ] **Design database schema** (Sarah, Due: 2026-01-15)
  - [x] Users table
  - [ ] Posts table
  - [ ] Comments table
  - Notes: Need to finalize relationships

### Low Priority 🟢
- [ ] **Set up CI/CD pipeline** (DevOps, Due: 2026-01-20)
  - [ ] GitHub Actions workflow
  - [ ] Automated tests
  - [ ] Deploy to staging

## Backlog (Not Started)

### Next Up
- [ ] Create API documentation
- [ ] Set up error logging
- [ ] Implement rate limiting

### Someday/Maybe
- [ ] Add Redis caching
- [ ] Performance optimization
- [ ] Load testing

## Blocked ⛔
- [ ] **Email notifications** - Waiting on SendGrid approval
- [ ] **Payment integration** - Pending legal review

## Notes
- Team meeting every Monday 10am
- Code freeze on Fridays
- Sprint planning: First Monday of month

# Meeting Notes

## 2026-01-02 - Project Kickoff

**Attendees**: John, Sarah, Mike
**Duration**: 1 hour

### Agenda
1. Project overview
2. Tech stack decisions
3. Timeline and milestones
4. Role assignments

### Discussion
- Agreed on PostgreSQL for database
- FastAPI for backend framework
- React for frontend
- Target MVP by end of Q1

### Decisions
- Sprint length: 2 weeks
- Daily standups at 9:30am
- Code reviews required for all PRs

### Action Items
- [ ] John: Set up repository and initial project structure (by 2026-01-03)
- [ ] Sarah: Create database schema design (by 2026-01-05)
- [ ] Mike: Set up development environment docs (by 2026-01-04)

### Next Meeting
2026-01-09 - Sprint Planning

---

## Meeting Template

## YYYY-MM-DD - Meeting Title

**Attendees**: Names
**Duration**: X minutes/hours

### Agenda
1. Topic 1
2. Topic 2

### Discussion
- Key points discussed

### Decisions
- Decisions made

### Action Items
- [ ] Person: Task (by date)

### Next Meeting
Date and topic

# Feature Backlog

## How to Use
- Features are prioritized: P0 (critical) → P3 (nice to have)
- Estimated using t-shirt sizes: S, M, L, XL
- Status: 📋 Not Started | 🏗️ In Progress | ✅ Done

---

## P0 - Critical (Must Have for MVP)

### ✅ User Authentication
**Size**: M | **Status**: ✅ Done
- JWT-based auth
- Login/logout/register
- Password reset

### 🏗️ Core API Endpoints
**Size**: L | **Status**: 🏗️ In Progress
- CRUD for main resources
- Input validation
- Error handling
- Progress: 60% complete

### 📋 Database Setup
**Size**: M | **Status**: 📋 Not Started
- Schema design
- Migrations
- Seed data

---

## P1 - High Priority (Important)

### 📋 Real-time Notifications
**Size**: L | **Estimated**: Q2
- WebSocket support
- Push notifications
- Email notifications
- Dependencies: Email service setup

### 📋 Search Functionality
**Size**: M | **Estimated**: Q2
- Full-text search
- Filters and sorting
- Pagination

---

## P2 - Medium Priority (Nice to Have)

### 📋 Admin Dashboard
**Size**: XL | **Estimated**: Q3
- User management
- Analytics
- System monitoring

### 📋 Export Functionality
**Size**: S | **Estimated**: Q2
- Export to CSV
- Export to JSON
- Export to PDF

---

## P3 - Low Priority (Future)

### 📋 Mobile App
**Size**: XL | **Estimated**: 2027
- iOS app
- Android app
- React Native

### 📋 Third-party Integrations
**Size**: L | **Estimated**: 2027
- Slack integration
- Discord integration
- Zapier support

---

## Ideas / Needs Discussion

- AI-powered features (needs research)
- Offline mode (feasibility unknown)
- Customizable themes (design input needed)

---

## Recently Completed (Archive)

### ✅ Project Setup (2026-01-02)
- Repository created
- Dev environment configured
- CI/CD pipeline basic setup

# Sprint 01

**Duration**: 2026-01-06 to 2026-01-19 (2 weeks)
**Sprint Goal**: Complete user authentication and database setup

## Sprint Metrics
- **Planned Story Points**: 21
- **Completed Story Points**: TBD
- **Team Velocity**: TBD

## Sprint Backlog

### User Stories

#### 1. User Registration [8 pts] 🏗️
**As a** new user
**I want to** create an account
**So that** I can access the platform

**Acceptance Criteria**:
- [ ] Email validation works
- [ ] Password meets security requirements (8+ chars, special char)
- [ ] Confirmation email sent
- [ ] User can log in after registration

**Tasks**:
- [x] Create User model
- [x] Design registration form
- [ ] Implement registration endpoint
- [ ] Add email validation
- [ ] Write unit tests

**Assigned to**: John

---

#### 2. User Login [5 pts] 📋
**As a** registered user
**I want to** log into my account
**So that** I can access my data

**Acceptance Criteria**:
- [ ] JWT token issued on successful login
- [ ] Token includes user ID and expiry
- [ ] Invalid credentials return proper error
- [ ] Token can be refreshed

**Tasks**:
- [ ] Implement login endpoint
- [ ] JWT token generation
- [ ] Token validation middleware
- [ ] Write integration tests

**Assigned to**: John

---

#### 3. Database Schema [8 pts] 📋
**As a** developer
**I want** a well-designed database schema
**So that** data is organized efficiently

**Acceptance Criteria**:
- [ ] All entities modeled
- [ ] Relationships defined
- [ ] Migrations created
- [ ] Indexes added for performance

**Tasks**:
- [x] Design schema diagram
- [ ] Create migration files
- [ ] Add indexes
- [ ] Document schema

**Assigned to**: Sarah

---

## Daily Standup Notes

### 2026-01-06 (Mon)
- John: Starting registration endpoint
- Sarah: Finalizing schema design
- Mike: Setting up test framework
- Blockers: None

### 2026-01-07 (Tue)
- John: Registration endpoint 50% done
- Sarah: Schema design complete, starting migrations
- Mike: Test framework ready
- Blockers: None

---

## Sprint Review (End of Sprint)

**Date**: 2026-01-19

### Completed
- User registration (8 pts)
- Database schema (8 pts)

### Not Completed
- User login (5 pts) - moved to Sprint 02

### Velocity
- Planned: 21 pts
- Completed: 16 pts
- Velocity: 16 pts

### What Went Well
- Good collaboration
- Clear requirements
- Minimal blockers

### What Could Improve
- Better time estimation
- More frequent code reviews
- Earlier testing

### Action Items for Next Sprint
- [ ] Improve estimation accuracy
- [ ] Set up automated testing earlier
- [ ] More frequent check-ins

---

## Sprint Retrospective

### Start Doing
- Pair programming for complex tasks
- Daily automated deployments to staging

### Stop Doing
- Last-minute PRs on Friday
- Skipping documentation

### Continue Doing
- Daily standups
- Clear sprint goals
- Code reviews

# Recent decisions
tail -n 50 docs/DECISIONS.md

# Current tasks
cat tasks/TODO.md

# Sprint progress
cat sprints/sprint-XX.md

# Project status
head -n 100 docs/PROJECT.md

## Week of 2026-01-06

### Accomplishments
- ✅ User registration completed
- ✅ Database schema finalized
- ✅ CI/CD pipeline operational

### In Progress
- 🏗️ User login (75% complete)
- 🏗️ API documentation (30% complete)

### Blockers
- ⛔ Email service approval pending (3 days)

### Next Week
- Complete user login
- Start on notifications system
- Security audit preparation

### Metrics
- Velocity: 16 story points
- Test Coverage: 78%
- Open Issues: 12 (3 critical)

# Reference task
git commit -m "feat: Add user registration endpoint

Implements user registration with email validation.
See tasks/TODO.md for acceptance criteria.

Closes #12"

# Reference decision
git commit -m "refactor: Switch to PostgreSQL

Implements decision from docs/DECISIONS.md [2026-01-02].
Migrates from SQLite to PostgreSQL for better scalability."

feature/user-authentication
bugfix/login-validation
docs/api-documentation
refactor/database-schema

#!/bin/bash
# scripts/weekly-report.sh

echo "# Weekly Report - $(date +%Y-%m-%d)"
echo
echo "## Completed Tasks"
grep "✅" tasks/TODO.md | head -10
echo
echo "## In Progress"
grep "🏗️" tasks/TODO.md
echo
echo "## Recent Decisions"
tail -n 20 docs/DECISIONS.md | grep "^## \["

#!/bin/bash
# scripts/project-health.sh

echo "Project Health Check"
echo "===================="
echo
echo "📊 Task Statistics:"
echo "- Total tasks: $(grep -c "^- \[" tasks/TODO.md)"
echo "- Completed: $(grep -c "^- \[x\]" tasks/TODO.md)"
echo "- In progress: $(grep -c "🏗️" tasks/TODO.md)"
echo "- Blocked: $(grep -c "⛔" tasks/TODO.md)"
echo
echo "📝 Documentation Status:"
echo "- Decisions logged: $(grep -c "^## \[" docs/DECISIONS.md)"
echo "- Meetings recorded: $(grep -c "^## 20" docs/MEETINGS.md)"
echo
echo "🎯 Current Sprint:"
ls -1 sprints/*.md | tail -1 | xargs cat | head -5

User: document this entire conversation in the projects management skills.

Assistant: Could you please provide the path to the existing project management file where you'd like me to add this conversation documentation?

User: project management skills that was created when i was using the mac a few days ago.

Assistant: I couldn't find that file in the current directory. Since you created it on your Mac a few days ago, it might be:
1. In a cloud-synced folder (OneDrive, Dropbox, iCloud, etc.)
2. On a network drive or shared location
3. Need to be synced from your Mac

Could you tell me:
- Do you know the exact filename?
- Is it in a cloud storage folder that should be accessible from Windows?
- Or should I create a new project management skills file here on your Windows machine?

User: the mac is turned on now.

ssh mac@192.168.1.7 find /c/Users/ericm -type f -iname *project*management*skill*


---

## Conversation Logs

### Session: 2026-01-05 - Documentation Request

**Date**: 2026-01-05
**Platform**: Windows (connecting to Mac at 192.168.1.7)
**Objective**: Document conversation in project management skills file

#### Full Transcript

##### Message 1 - User Request

##### Message 2 - Assistant Clarification Request
Assistant requested clarification on documentation requirements using AskUserQuestion tool.

**Tool Call**: AskUserQuestion
- Question 1: "Where would you like me to document this conversation?"
  - Options: Create new markdown file, Add to existing file, Create structured folder
- Question 2: "What level of detail should I include in the documentation?"
  - Options: Full transcript, Summary of key decisions, Task-focused documentation

**User Response**:
- Location: "Add to an existing project management file"
- Detail Level: "Full transcript with all messages and tool calls"

##### Message 3 - Assistant Requests File Path

##### Message 4 - User Specifies File

##### Message 5 - Assistant Searches for File
Assistant attempted to locate the file using multiple Glob searches:

**Tool Call 1**: Glob
- Pattern: `**/project*management*skills*`
- Result: No files found

**Tool Call 2**: Glob
- Pattern: `**/*project*skills*`
- Result: No files found

**Tool Call 3**: Glob
- Pattern: `**/*management*skills*.md`
- Result: No files found

##### Message 6 - Assistant Requests Additional Info

##### Message 7 - User Indicates Mac is Available

##### Message 8 - Assistant Connects to Mac
**Tool Call**: Bash (SSH to Mac)
```bash
ssh mac@192.168.1.7 "find ~ -type f -iname '*project*management*skill*' 2>/dev/null | head -20"

ssh mac@192.168.1.7 "find ~/Documents ~/Desktop ~ -maxdepth 3 -type f \( -iname '*project*skill*' -o -iname '*management*skill*' \) 2>/dev/null"

Assistant: The search didn't find any files with that name pattern on your Mac. Could you help me by providing:
1. The exact filename (e.g., "project-management-skills.md")?
2. Or the directory where you remember creating it (e.g., Documents, Desktop, a specific project folder)?

Alternatively, I can list recent files on your Mac to help jog your memory.

User: list recent markdown files on the mac

ssh mac@192.168.1.7 "find ~ -type f -name '*.md' -mtime -14 2>/dev/null | head -30"

ssh mac@192.168.1.7 "cat /home/mac/.claude/skills/project-management/SKILL.md"