# 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.