feat: update docs for token efficient usage

.claude/CLAUDE.md

@@ -1,4 +1,16 @@
-# .claude/ Index
+# .claude/
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `role-agents/` | Developer, TW, QR, Debugger agents | Delegating execution |
+| `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work |
+| `skills/` | Reusable skills | Complex multi-step workflows |
+| `output-styles/` | Output formatting templates | Customizing agent output |
+| `tdd-guard/` | TDD enforcement utilities | Test-driven development |
+
+## Quick Reference
 
 | Path | What | When |
 |------|------|------|
@@ -10,5 +22,6 @@
 | `skills/codebase-analysis/` | Systematic investigation | Unfamiliar areas |
 | `skills/doc-sync/` | Documentation sync | After refactors |
 | `skills/incoherence/` | Detect doc/code drift | Periodic audits |
+| `skills/prompt-engineer/` | Prompt optimization | Improving AI prompts |
 | `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work |
 | `.ai/workflow-contract.json` | Sprint process, skill integration | Issue workflow |

.claude/agents/CLAUDE.md

@@ -0,0 +1,11 @@
+# agents/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Agent team overview and coordination | Understanding agent workflow |
+| `feature-agent.md` | Backend feature development agent | Backend feature work |
+| `frontend-agent.md` | React/mobile-first UI agent | Frontend component work |
+| `platform-agent.md` | Platform services agent | Platform microservice work |
+| `quality-agent.md` | Final validation agent | Pre-merge quality checks |

.claude/role-agents/CLAUDE.md

@@ -0,0 +1,10 @@
+# role-agents/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `developer.md` | Developer role agent | Code implementation tasks |
+| `technical-writer.md` | Technical writer agent | Documentation tasks |
+| `quality-reviewer.md` | Quality reviewer with RULE 0/1/2 | Code review, quality gates |
+| `debugger.md` | Debugging specialist agent | Bug investigation, troubleshooting |

.claude/skills/CLAUDE.md

@@ -0,0 +1,13 @@
+# skills/
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `planner/` | Planning workflow with resource sync | Complex features (3+ files) |
+| `problem-analysis/` | Structured problem decomposition | Uncertain approach, debugging |
+| `decision-critic/` | Decision stress-testing | Architectural choices, tradeoffs |
+| `codebase-analysis/` | Systematic codebase investigation | Unfamiliar areas, audits |
+| `doc-sync/` | CLAUDE.md/README.md synchronization | After refactors, periodic audits |
+| `incoherence/` | Detect doc/code drift | Documentation inconsistencies |
+| `prompt-engineer/` | Prompt optimization techniques | Improving AI prompts |

.claude/skills/doc-sync/CLAUDE.md

@@ -0,0 +1,14 @@
+# skills/doc-sync/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Skill overview and usage examples | Understanding when to use doc-sync |
+| `SKILL.md` | Complete skill workflow definition | Executing the doc-sync skill |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `references/` | Trigger pattern examples | Writing good CLAUDE.md triggers |