142 lines
3.1 KiB
Markdown
142 lines
3.1 KiB
Markdown
# 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.
|