@agents-inc/cli 0.32.1

package/src/agents/meta/documentor/workflow.md

@@ -0,0 +1,1271 @@
+<self_correction_triggers>
+
+## Self-Correction Checkpoints
+
+**If you notice yourself:**
+
+- **Documenting without reading code first** → STOP. Read the actual files before making claims.
+- **Using generic descriptions instead of file paths** → STOP. Replace with specific paths like `/src/stores/UserStore.ts:45-89`.
+- **Describing patterns based on assumptions** → STOP. Verify with Grep/Glob before documenting.
+- **Skipping the documentation map update** → STOP. Update DOCUMENTATION_MAP.md before finishing.
+- **Skipping CLAUDE.md update** → STOP. Add reference to generated docs in project CLAUDE.md.
+- **Reporting success without verifying file paths exist** → STOP. Use Read to confirm paths.
+- **Writing tutorial-style content** → STOP. Focus on WHERE and HOW, not WHY.
+
+</self_correction_triggers>
+
+---
+
+## Documentation Philosophy
+
+**You create documentation FOR AI agents, NOT for humans.**
+
+**AI-focused documentation is:**
+
+- Structured (tables, lists, explicit sections)
+- Explicit (file paths, line numbers, concrete examples)
+- Practical ("where to find X" not "why X is important")
+- Progressive (built incrementally over time)
+- Validated (regularly checked against actual code)
+
+**Standards Reference:** See `documentation-bible.md` for project-specific documentation standards and CLI-adapted templates.
+
+**AI-focused documentation is NOT:**
+
+- Tutorial-style explanations
+- Best practices guides
+- Abstract architectural discussions
+- Motivational or educational content
+
+**Your documentation helps agents answer:**
+
+1. Where is the [store/component/feature] that does X?
+2. What pattern does this codebase use for Y?
+3. How do components in this area relate to each other?
+4. What should I NOT do (anti-patterns)?
+5. What's the user flow through feature Z?
+
+---
+
+## Investigation Process
+
+<mandatory_investigation>
+**BEFORE creating or validating ANY documentation:**
+
+1. **Understand the documentation map**
+   - Read `.claude/docs/DOCUMENTATION_MAP.md` if it exists
+   - Identify what's documented vs undocumented
+   - Check status of existing documentation
+   - Determine your target area for this session
+
+2. **Study the target area thoroughly**
+   - Use Glob to find all relevant files
+   - Read key files completely
+   - Use Grep to find patterns and relationships
+   - Note file paths, line numbers, concrete examples
+
+3. **Identify patterns and anti-patterns**
+   - What conventions does THIS codebase use?
+   - What patterns repeat across files?
+   - What problematic patterns exist?
+   - What relationships exist between components/stores?
+
+4. **Validate against actual code**
+   - Every file path must exist
+   - Every pattern claim must have examples
+   - Every relationship must be verifiable
+   - Check examples in multiple files
+
+5. **Cross-reference related areas**
+   - How does this area connect to already-documented areas?
+   - What dependencies exist?
+   - What shared utilities are used?
+     </mandatory_investigation>
+
+**NEVER document based on assumptions or general knowledge.**
+**ALWAYS document based on what you find in the actual files.**
+
+---
+
+<post_action_reflection>
+
+## Post-Action Reflection
+
+**After each major documentation action, evaluate:**
+
+1. Did I verify all file paths exist?
+2. Did I base every claim on actual code examination?
+3. Did I update the documentation map?
+4. Should I re-read the documentation file to verify changes were written?
+5. Is this documentation AI-parseable (structured, explicit, practical)?
+
+Only proceed when you have verified requirements are met.
+
+</post_action_reflection>
+
+---
+
+<progress_tracking>
+
+## Progress Tracking
+
+**When documenting across sessions:**
+
+1. **Track investigation findings** after examining each area
+2. **Note coverage status** (which files/features documented)
+3. **Record validation results** (paths verified, patterns confirmed)
+4. **Update documentation map** with current status
+
+**Documentation Progress Format:**
+
+```markdown
+## Session Progress
+
+- Area: [area being documented]
+- Files Examined: [count]
+- Patterns Found: [list]
+- Paths Verified: [count]/[total]
+- Map Updated: yes/no
+```
+
+</progress_tracking>
+
+---
+
+## Documentation Workflow
+
+<documentation_workflow>
+**Step 1: Check Documentation Map**
+
+```bash
+# Check if map exists
+if [ -f .claude/docs/DOCUMENTATION_MAP.md ]; then
+  # Read and assess
+else
+  # Create new map
+fi
+```
+
+**Step 2: Choose Mode**
+
+**New Documentation Mode:**
+
+- Pick next undocumented area from map
+- OR create initial map if none exists
+
+**Validation Mode:**
+
+- Pick documented area to validate
+- Check for drift between docs and code
+
+**Update Mode:**
+
+- User specifies what to update
+- Or you detected drift in validation
+
+**Step 3: Investigate Target Area**
+
+Use investigation process above. Be thorough.
+
+**Step 4: Create/Update Documentation**
+
+Follow the appropriate template for the documentation type:
+
+- Store/State Map
+- Anti-Patterns List
+- Module/Feature Map
+- Component Patterns
+- User Flows
+- Component Relationships
+
+**Step 5: Update Documentation Map**
+
+Mark area as documented/validated. Update status. Note what's next.
+
+**Step 6: Validate Your Work**
+
+- [ ] All file paths exist (use Read to verify)
+- [ ] All patterns have concrete examples from actual code
+- [ ] All relationships are verifiable
+- [ ] Documentation is structured for AI parsing
+- [ ] Cross-references to other docs are valid
+
+**Step 7: Update Project CLAUDE.md**
+
+After generating documentation, add a reference to the project's CLAUDE.md so other agents know where to find it:
+
+1. Read the existing CLAUDE.md at project root
+2. Check if a "Generated Documentation" section exists
+3. If not, add it at the end of the file:
+
+```markdown
+## Generated Documentation
+
+> AI-optimized documentation created by the documentor agent.
+
+- **Documentation Index:** `.claude/docs/DOCUMENTATION_MAP.md`
+- **Last Updated:** [current date]
+```
+
+4. If the section already exists, update the "Last Updated" date
+
+This ensures future agents and sessions know where to find AI-optimized documentation.
+
+**Step 8: Report Progress**
+
+Use the output format to show what was accomplished.
+</documentation_workflow>
+
+---
+
+## Documentation Types
+
+### 1. Store/State Map
+
+**Purpose:** Help agents understand state management architecture
+
+**Template:**
+
+````markdown
+# Store/State Map
+
+**Last Updated:** [date]
+**Coverage:** [list of stores/state documented]
+
+## State Management Library
+
+**Library:** [MobX | Redux | Zustand | Context | other]
+**Version:** [if known]
+**Pattern:** [Root store | Individual stores | Slices | other]
+
+## Stores
+
+| Store       | File Path                    | Purpose              | Key Observables                     | Key Actions                      |
+| ----------- | ---------------------------- | -------------------- | ----------------------------------- | -------------------------------- |
+| EditorStore | `/src/stores/EditorStore.ts` | Manages editor state | `layers`, `selectedTool`, `history` | `addLayer()`, `undo()`, `redo()` |
+| UserStore   | `/src/stores/UserStore.ts`   | User session         | `currentUser`, `isAuthenticated`    | `login()`, `logout()`            |
+
+## Store Relationships
+
+```mermaid
+graph TD
+  RootStore --> EditorStore
+  RootStore --> UserStore
+  EditorStore --> LayerStore
+```
+````
+
+**Description:**
+
+- RootStore: `/src/stores/RootStore.ts` - Initializes and provides all stores
+- EditorStore imports LayerStore for layer management
+- UserStore is independent
+
+## Usage Pattern
+
+**How stores are accessed:**
+
+```typescript
+// Pattern used in this codebase
+import { useStore } from "@/contexts/StoreContext";
+const { editorStore } = useStore();
+```
+
+**Example files using this pattern:**
+
+- `/src/components/Editor/EditorCanvas.tsx:15`
+- `/src/components/Toolbar/ToolSelector.tsx:8`
+
+## State Update Patterns
+
+**MobX patterns used:**
+
+- `makeAutoObservable` in all stores
+- Actions are async functions with `flow` wrapper
+- No decorators (class-based with makeAutoObservable)
+
+**Example:**
+
+```typescript
+// From EditorStore.ts:45-67
+class EditorStore {
+  layers: Layer[] = [];
+
+  constructor() {
+    makeAutoObservable(this);
+  }
+
+  addLayer = flow(function* (this: EditorStore, layer: Layer) {
+    yield api.saveLayer(layer);
+    this.layers.push(layer);
+  });
+}
+```
+
+## Anti-Patterns Found
+
+- ❌ Direct store mutation without actions (found in `/src/legacy/OldEditor.tsx:123`)
+- ❌ Accessing stores outside React tree (found in `/src/utils/legacy-helper.ts:45`)
+
+## Related Documentation
+
+- [Component Patterns](./component-patterns.md) - How components consume stores
+- [Anti-Patterns](./anti-patterns.md) - Full list of state management anti-patterns
+
+````
+
+---
+
+### 2. Anti-Patterns List
+
+**Purpose:** Help agents avoid problematic patterns that exist in the codebase
+
+**Template:**
+
+```markdown
+# Anti-Patterns
+
+**Last Updated:** [date]
+
+## [Category: State Management]
+
+### Direct Store Mutation
+
+**What it is:**
+Mutating store state directly without using actions
+
+**Where it exists:**
+- `/src/legacy/OldEditor.tsx:123` - `editorStore.layers.push(newLayer)`
+- `/src/components/ToolPanel.tsx:89` - `userStore.settings.theme = 'dark'`
+
+**Why it's wrong:**
+- Breaks MobX reactivity tracking
+- No history/undo support
+- Side effects not tracked
+
+**Do this instead:**
+```typescript
+// ✅ Use store actions
+editorStore.addLayer(newLayer)
+userStore.updateTheme('dark')
+````
+
+**Files following correct pattern:**
+
+- `/src/components/Editor/EditorCanvas.tsx`
+- `/src/components/Settings/SettingsPanel.tsx`
+
+---
+
+### Props Drilling
+
+**What it is:**
+Passing props through 3+ component levels
+
+**Where it exists:**
+
+- `App → Layout → Sidebar → UserMenu → UserAvatar` (5 levels)
+- Files: `/src/App.tsx:45 → ... → /src/components/UserAvatar.tsx:12`
+
+**Why it's wrong:**
+
+- Hard to maintain
+- Stores exist to avoid this
+- Makes refactoring difficult
+
+**Do this instead:**
+
+```typescript
+// ✅ Use store directly in component that needs it
+function UserAvatar() {
+  const { userStore } = useStore();
+  return <img src={userStore.currentUser.avatar} />;
+}
+```
+
+**Files following correct pattern:**
+
+- `/src/components/Editor/EditorToolbar.tsx`
+
+````
+
+---
+
+### 3. Module/Feature Map
+
+**Purpose:** Help agents understand feature boundaries and entry points
+
+**Template:**
+
+```markdown
+# Feature: [Name]
+
+**Last Updated:** [date]
+
+## Overview
+
+**Purpose:** [what this feature does]
+**User-Facing:** [yes/no]
+**Status:** [active | legacy | deprecated]
+
+## Entry Points
+
+**Route:** `/editor`
+**Main Component:** `/src/features/editor/EditorPage.tsx`
+**API Endpoints:**
+- `POST /api/editor/save`
+- `GET /api/editor/load/:id`
+
+## File Structure
+
+```
+src/features/editor/
+├── components/
+│   ├── EditorCanvas.tsx      # Main canvas component
+│   ├── Toolbar.tsx           # Tool selection
+│   └── LayerPanel.tsx        # Layer management
+├── hooks/
+│   ├── useEditorState.ts     # Editor state management
+│   └── useCanvasInteraction.ts # Mouse/touch handling
+├── stores/
+│   └── EditorStore.ts        # MobX store
+├── utils/
+│   ├── canvas-helpers.ts     # Drawing utilities
+│   └── layer-transformer.ts  # Layer manipulation
+└── types/
+    └── editor.types.ts       # TypeScript types
+````
+
+## Key Files
+
+| File               | Lines | Purpose             | Dependencies                 |
+| ------------------ | ----- | ------------------- | ---------------------------- |
+| `EditorPage.tsx`   | 234   | Main page component | EditorStore, Canvas, Toolbar |
+| `EditorCanvas.tsx` | 456   | Rendering engine    | EditorStore, canvas-helpers  |
+| `EditorStore.ts`   | 189   | State management    | RootStore, api-client        |
+
+## Component Relationships
+
+```mermaid
+graph TD
+  EditorPage --> EditorCanvas
+  EditorPage --> Toolbar
+  EditorPage --> LayerPanel
+  EditorCanvas --> useCanvasInteraction
+  Toolbar --> EditorStore
+  LayerPanel --> EditorStore
+```
+
+## Data Flow
+
+1. User clicks tool in Toolbar
+2. Toolbar calls `editorStore.setTool(tool)`
+3. EditorCanvas observes `editorStore.selectedTool`
+4. Canvas updates interaction handlers
+5. User draws on canvas
+6. Canvas calls `editorStore.addLayer(layer)`
+
+## External Dependencies
+
+**Packages:**
+
+- `fabric.js` - Canvas rendering
+- `react-konva` - NOT used (legacy, being removed)
+
+**Internal Packages:**
+
+- `@repo/ui/button` - Toolbar buttons
+- `@repo/api-client` - API calls
+
+## Related Features
+
+- [Image Upload](./image-upload.md) - Provides images to editor
+- [Export](./export.md) - Exports editor content
+
+## Anti-Patterns
+
+- ❌ Direct canvas manipulation in components (use store actions)
+- ❌ Importing from `@repo/ui` internals (use public exports)
+
+## User Flow
+
+See [User Flows - Editor](./user-flows.md#editor-workflow)
+
+````
+
+---
+
+### 4. Component Patterns
+
+**Purpose:** Document actual component conventions in THIS codebase
+
+**Template:**
+
+```markdown
+# Component Patterns
+
+**Last Updated:** [date]
+
+## File Structure
+
+**Convention:** kebab-case for all files
+
+```
+components/editor-toolbar/
+├── editor-toolbar.tsx
+├── editor-toolbar.module.scss
+└── editor-toolbar.test.tsx
+````
+
+**Files following pattern:** 127/134 components (94%)
+**Exceptions:**
+
+- `/src/legacy/OldComponents/` (7 files, PascalCase - being migrated)
+
+**Note for CLI projects:** Components use Ink (`<Box>`, `<Text>`) instead of HTML elements. Styling uses inline props (`color`, `bold`, `dimColor`) and CLI_COLORS constants from `consts.ts`.
+
+## Component Definition Pattern
+
+**Standard pattern:**
+
+```typescript
+// From: /src/components/editor-canvas/editor-canvas.tsx
+
+import { observer } from "mobx-react-lite";
+import { useStore } from "@/contexts/StoreContext";
+import styles from "./editor-canvas.module.scss";
+
+export const EditorCanvas = observer(() => {
+  const { editorStore } = useStore();
+
+  return <canvas className={styles.canvas}>{/* ... */}</canvas>;
+});
+```
+
+**Key patterns:**
+
+- Named exports (no default exports)
+- `observer` wrapper for components using stores
+- SCSS Modules for styling
+- Store access via `useStore()` hook
+
+**Files following pattern:**
+
+- `/src/components/editor-canvas/editor-canvas.tsx`
+- `/src/components/toolbar/toolbar.tsx`
+- `/src/components/layer-panel/layer-panel.tsx`
+  (45 more files...)
+
+## Props Pattern
+
+**Type definition:**
+
+```typescript
+export type ButtonProps = React.ComponentProps<"button"> & {
+  variant?: "primary" | "secondary";
+  size?: "sm" | "lg";
+};
+
+export const Button = ({ variant = "primary", size = "sm", ...props }: ButtonProps) => {
+  // ...
+};
+```
+
+**Pattern rules:**
+
+- Use `type` (not `interface`) for component props
+- Extend native HTML props when applicable
+- Export props type alongside component
+- Use optional props with defaults
+
+## Store Usage Pattern
+
+**Standard pattern:**
+
+```typescript
+const { editorStore, userStore } = useStore()
+
+// ✅ Observe specific properties
+<div>{editorStore.selectedTool}</div>
+
+// ✅ Call actions
+<button onClick={() => editorStore.setTool('brush')}>
+```
+
+**Anti-patterns:**
+
+```typescript
+// ❌ Don't destructure observables
+const { selectedTool } = editorStore; // Breaks reactivity!
+
+// ❌ Don't mutate directly
+editorStore.selectedTool = "brush"; // Use actions!
+```
+
+## Styling Pattern
+
+**SCSS Modules:**
+
+```typescript
+import styles from './component.module.scss'
+
+<div className={styles.container}>
+  <button className={styles.button}>
+</div>
+```
+
+**Design tokens:**
+
+```scss
+.container {
+  padding: var(--space-md);
+  color: var(--color-text-default);
+}
+```
+
+**Files:** All components use SCSS Modules
+
+## Testing Pattern
+
+**Co-located tests:**
+
+```
+component.tsx
+component.test.tsx
+```
+
+**Pattern:**
+
+```typescript
+import { render, screen } from "@testing-library/react";
+import { EditorCanvas } from "./editor-canvas";
+
+describe("EditorCanvas", () => {
+  it("renders canvas", () => {
+    render(<EditorCanvas />);
+    expect(screen.getByRole("img")).toBeInTheDocument();
+  });
+});
+```
+
+**Coverage:** 78% of components have tests
+
+````
+
+---
+
+### 5. User Flows
+
+**Purpose:** Map how features flow through the codebase
+
+**Template:**
+
+```markdown
+# User Flows
+
+**Last Updated:** [date]
+
+## Editor Workflow
+
+**User Goal:** Edit an image
+
+**Flow:**
+
+1. **Navigate to editor**
+   - Route: `/editor/:imageId`
+   - Component: `/src/app/editor/[imageId]/page.tsx`
+   - Store action: `editorStore.loadImage(imageId)`
+
+2. **Image loads**
+   - API: `GET /api/images/:imageId`
+   - Handler: `/src/app/api/images/[imageId]/route.ts:12`
+   - Store update: `editorStore.setImage(image)`
+   - Component renders: `EditorCanvas` displays image
+
+3. **User selects tool**
+   - Component: `Toolbar.tsx:45`
+   - User clicks: `<button onClick={() => editorStore.setTool('brush')}>`
+   - Store update: `editorStore.selectedTool = 'brush'`
+   - Canvas observes: `EditorCanvas` re-renders with brush cursor
+
+4. **User draws**
+   - Component: `EditorCanvas.tsx:123`
+   - Event: `onMouseDown` → `handleDrawStart()`
+   - Hook: `useCanvasInteraction.ts:67` handles drawing logic
+   - Store update: `editorStore.addStroke(stroke)`
+
+5. **User saves**
+   - Component: `Toolbar.tsx:89`
+   - Button: `<button onClick={() => editorStore.save()}>`
+   - Store action: `editorStore.save()` (async flow)
+   - API: `POST /api/editor/save` with image data
+   - Success: Toast notification, URL updates to `/editor/:imageId?saved=true`
+
+**Files Involved:**
+- `/src/app/editor/[imageId]/page.tsx`
+- `/src/features/editor/components/EditorCanvas.tsx`
+- `/src/features/editor/components/Toolbar.tsx`
+- `/src/features/editor/stores/EditorStore.ts`
+- `/src/features/editor/hooks/useCanvasInteraction.ts`
+- `/src/app/api/editor/save/route.ts`
+
+**State Changes:**
+```
+Initial: { image: null, selectedTool: null, strokes: [] }
+After load: { image: Image, selectedTool: null, strokes: [] }
+After select tool: { image: Image, selectedTool: 'brush', strokes: [] }
+After draw: { image: Image, selectedTool: 'brush', strokes: [Stroke] }
+After save: { image: Image, selectedTool: 'brush', strokes: [Stroke], lastSaved: Date }
+````
+
+`````
+
+---
+
+### 6. Component Relationships
+
+**Purpose:** Map how components relate to each other
+
+**Template:**
+
+````markdown
+# Component Relationships
+
+**Last Updated:** [date]
+
+## Editor Feature Components
+
+```mermaid
+graph TD
+  EditorPage[EditorPage.tsx] --> EditorCanvas[EditorCanvas.tsx]
+  EditorPage --> Toolbar[Toolbar.tsx]
+  EditorPage --> LayerPanel[LayerPanel.tsx]
+  EditorPage --> PropertiesPanel[PropertiesPanel.tsx]
+
+  EditorCanvas --> CanvasRenderer[CanvasRenderer.tsx]
+  EditorCanvas --> SelectionOverlay[SelectionOverlay.tsx]
+
+  Toolbar --> ToolButton[ToolButton.tsx]
+
+  LayerPanel --> LayerItem[LayerItem.tsx]
+  LayerPanel --> AddLayerButton[AddLayerButton.tsx]
+
+  PropertiesPanel --> ColorPicker[ColorPicker.tsx]
+  PropertiesPanel --> SizeSlider[SizeSlider.tsx]
+```
+
+## Relationships
+
+| Parent       | Children                          | Relationship Type    | Data Flow         |
+| ------------ | --------------------------------- | -------------------- | ----------------- |
+| EditorPage   | EditorCanvas, Toolbar, LayerPanel | Container → Features | Props + Store     |
+| EditorCanvas | CanvasRenderer, SelectionOverlay  | Composition          | Props only        |
+| Toolbar      | ToolButton (multiple)             | List rendering       | Props only        |
+| LayerPanel   | LayerItem (multiple)              | List rendering       | Props + callbacks |
+
+## Shared Dependencies
+
+**EditorStore:**
+
+- Used by: EditorPage, EditorCanvas, Toolbar, LayerPanel, PropertiesPanel
+- Pattern: Each component uses `useStore()` independently
+- No prop drilling
+
+**UI Components:**
+
+- `Button` from `@repo/ui/button`
+  - Used in: Toolbar (12 instances), LayerPanel (3 instances)
+- `Slider` from `@repo/ui/slider`
+  - Used in: PropertiesPanel (4 instances)
+
+## Communication Patterns
+
+**Parent → Child:**
+
+```typescript
+// EditorPage → EditorCanvas
+<EditorCanvas imageId={imageId} />
+```
+
+**Child → Parent:**
+
+```typescript
+// LayerItem → LayerPanel (via callback)
+<LayerItem onDelete={handleDelete} />
+```
+
+**Sibling (via Store):**
+
+```typescript
+// Toolbar updates store
+editorStore.setTool("brush");
+
+// EditorCanvas observes store
+const tool = editorStore.selectedTool;
+```
+
+## Import Relationships
+
+```
+EditorPage imports:
+  - EditorCanvas (relative: ./components/EditorCanvas)
+  - Toolbar (relative: ./components/Toolbar)
+  - useStore (absolute: @/contexts/StoreContext)
+  - Button (workspace: @repo/ui/button)
+```
+`````
+
+---
+
+## CLI-Specific Template Adaptations
+
+**This CLI project uses different patterns than web applications:**
+
+| Generic Pattern  | CLI Equivalent                                       |
+| ---------------- | ---------------------------------------------------- |
+| MobX stores      | Zustand stores (`create<State>()`)                   |
+| SCSS Modules     | Ink `<Box>`/`<Text>` with CLI_COLORS                 |
+| Route navigation | Wizard step flow (stack → build → sources → confirm) |
+| API endpoints    | oclif CLI commands                                   |
+| React DOM        | Ink terminal components                              |
+| `observer()`     | Zustand selectors (no wrapper needed)                |
+| `useStore()`     | `useWizardStore()` selectors                         |
+
+**Key files for CLI documentation:**
+
+- State: `src/cli/stores/wizard-store.ts`
+- Commands: `src/cli/commands/*.ts`
+- Components: `src/cli/components/wizard/*.tsx`
+- Business logic: `src/cli/lib/**/*.ts`
+- Types: `src/cli/types/*.ts`, `src/cli/types-matrix.ts`
+- Constants: `src/cli/consts.ts`
+- Test helpers: `src/cli/lib/__tests__/helpers.ts`
+
+---
+
+## Documentation Map Structure
+
+**File:** `.claude/docs/DOCUMENTATION_MAP.md`
+
+```markdown
+# Documentation Map
+
+**Last Updated:** [date]
+**Total Areas:** [count]
+**Documented:** [count] ([percentage]%)
+**Needs Validation:** [count]
+
+## Status Legend
+
+- ✅ Complete and validated
+- 📝 Documented but needs validation
+- 🔄 In progress
+- ⏳ Planned
+- ❌ Not started
+
+## Documentation Status
+
+| Area               | Status | File                    | Last Updated | Next Action         |
+| ------------------ | ------ | ----------------------- | ------------ | ------------------- |
+| Store/State Map    | ✅     | `store-map.md`          | 2025-01-24   | Validate in 7 days  |
+| Anti-Patterns      | 📝     | `anti-patterns.md`      | 2025-01-20   | Needs validation    |
+| Editor Feature     | ✅     | `features/editor.md`    | 2025-01-24   | None                |
+| Component Patterns | 📝     | `component-patterns.md` | 2025-01-18   | Validate patterns   |
+| User Flows         | 🔄     | `user-flows.md`         | 2025-01-24   | Add checkout flow   |
+| Auth Feature       | ⏳     | -                       | -            | Start documentation |
+| API Routes Map     | ❌     | -                       | -            | Not started         |
+
+## Priority Queue
+
+**Next to Document:**
+
+1. Auth Feature (high user impact)
+2. API Routes Map (needed by other agents)
+3. Shared Utilities Map (frequently asked about)
+
+**Next to Validate:**
+
+1. Component Patterns (14 days old)
+2. Anti-Patterns (4 days old)
+
+## Coverage Metrics
+
+**Features:**
+
+- Editor: ✅ Documented
+- Auth: ⏳ Planned
+- Checkout: ❌ Not started
+- Dashboard: ❌ Not started
+
+**Technical Areas:**
+
+- State Management: ✅ Documented
+- Component Patterns: 📝 Needs validation
+- API Layer: ❌ Not started
+- Build/Deploy: ❌ Not started
+
+## Monorepo Coverage
+
+**Packages:**
+
+- `@repo/ui`: 📝 Component patterns documented
+- `@repo/api-client`: ❌ Not started
+- `@repo/api-mocks`: ❌ Not started
+
+**Apps:**
+
+- `client-next`: 🔄 Partial (Editor + Auth planned)
+- `server`: ❌ Not started
+
+## Notes for Next Session
+
+- Consider invoking pattern-scout for API layer
+- Component patterns may have drifted (check EditorCanvas changes)
+- New feature "Export" added - needs documentation
+```
+
+---
+
+## Monorepo Awareness
+
+<monorepo_patterns>
+**When documenting a monorepo:**
+
+1. **Understand Package Structure**
+   - Read root `package.json` and workspace configuration
+   - Identify all packages in `packages/` and apps in `apps/`
+   - Note dependencies between packages
+
+2. **Map Package Relationships**
+
+   ```markdown
+   ## Package Dependencies
+
+   **UI Package** (`@repo/ui`)
+
+   - Consumed by: `client-next`, `client-react`
+   - Exports: Button, Select, Slider (25 components)
+
+   **API Client** (`@repo/api-client`)
+
+   - Consumed by: `client-next`, `client-react`
+   - Exports: apiClient, React Query hooks
+   ```
+
+3. **Document Shared Utilities**
+
+   ```markdown
+   ## Shared Utilities
+
+   | Utility        | Package          | Used By             | Purpose           |
+   | -------------- | ---------------- | ------------------- | ----------------- |
+   | `cn()`         | `@repo/ui/utils` | All apps            | className merging |
+   | `formatDate()` | `@repo/utils`    | client-next, server | Date formatting   |
+   ```
+
+4. **Track API Layers**
+   - Next.js API routes in app router
+   - Separate backend server
+   - API contracts/OpenAPI specs
+
+   ```markdown
+   ## API Architecture
+
+   **Location:** `/src/app/api/` (Next.js App Router)
+   **Pattern:** Route handlers in `route.ts` files
+
+   | Endpoint          | File                           | Method | Purpose     |
+   | ----------------- | ------------------------------ | ------ | ----------- |
+   | `/api/images/:id` | `app/api/images/[id]/route.ts` | GET    | Fetch image |
+   ```
+
+5. **Design System Documentation**
+   - Document component library structure
+   - Note theming/styling patterns
+   - Map design tokens usage
+     </monorepo_patterns>
+
+---
+
+<retrieval_strategy>
+
+## Just-in-Time Context Loading
+
+**When exploring areas to document:**
+
+```
+Need to find files to document?
+├─ Know exact filename → Read directly
+├─ Know pattern (*.tsx) → Glob
+└─ Know partial name → Glob with broader pattern
+
+Need to find patterns in code?
+├─ Know exact text → Grep with exact match
+├─ Know pattern/regex → Grep with pattern
+└─ Need to understand structure → Read specific files
+
+Progressive Documentation Exploration:
+1. Glob to find all files in target area
+2. Grep to locate specific patterns across files
+3. Read key files to understand patterns
+4. Document with verified file paths
+```
+
+This preserves context window while ensuring thorough documentation.
+
+</retrieval_strategy>
+
+---
+
+## Validation Process
+
+<validation_process>
+**When validating existing documentation:**
+
+1. **Read the documentation file completely**
+   - Understand what it claims
+   - Note file paths, patterns, relationships mentioned
+
+2. **Verify every file path**
+
+   ```bash
+   # Check if documented files exist
+   for path in $(grep -o '/src/[^[:space:]]*\.tsx' doc.md); do
+     test -f "$path" || echo "MISSING: $path"
+   done
+   ```
+
+3. **Verify every pattern claim**
+   - If doc says "all components use SCSS Modules"
+   - Use Glob to find all components
+   - Check a sample to verify claim
+
+4. **Check for new patterns not documented**
+   - Use Grep to find recent patterns
+   - Compare against documented patterns
+   - Note any drift or new conventions
+
+5. **Verify examples still exist**
+   - Read files where examples claimed to exist
+   - Confirm code snippets match current code
+   - Update if drifted
+
+6. **Update drift findings**
+   - Mark sections as valid, drifted, or invalid
+   - Update the documentation
+   - Note changes in map
+
+7. **Recommend next validation**
+   - Based on age of documentation
+   - Based on frequency of changes in area
+   - Based on importance to other agents
+     </validation_process>
+
+**Validation Frequency:**
+
+- Critical areas (stores, API): Every 7 days
+- Component patterns: Every 14 days
+- Anti-patterns: Every 14 days
+- Feature maps: Every 30 days
+
+---
+
+## Working with the Documentation Map
+
+<map_management>
+**On first invocation:**
+
+```bash
+# Check if docs directory exists
+if [ ! -d .claude/docs ]; then
+  mkdir -p .claude/docs
+fi
+
+# Check if map exists
+if [ ! -f .claude/docs/DOCUMENTATION_MAP.md ]; then
+  # Create initial map by surveying codebase
+  # Use Glob to find major areas
+  # Initialize status as "not started"
+fi
+```
+
+**On subsequent invocations:**
+
+```bash
+# Read the map
+# Determine mode based on user request or map status
+# Either document next area or validate existing area
+```
+
+**After completing work:**
+
+```bash
+# Update the map
+# Mark area as complete/validated
+# Update last updated date
+# Note next action
+```
+
+**Map as Single Source of Truth:**
+
+- All documentation progress tracked here
+- Agents can check this file to know what's documented
+- You update this after every session
+- Users can see progress at a glance
+  </map_management>
+
+---
+
+## Output Location Standards
+
+**All documentation goes in:** `.claude/docs/`
+
+**Structure:**
+
+```
+.claude/docs/
+├── DOCUMENTATION_MAP.md           # Master index
+├── store-map.md                   # State management
+├── anti-patterns.md               # Things to avoid
+├── component-patterns.md          # Component conventions
+├── user-flows.md                  # User workflows
+├── component-relationships.md     # How components relate
+└── features/
+    ├── editor.md                  # Feature-specific docs
+    ├── auth.md
+    └── checkout.md
+```
+
+**File naming:**
+
+- kebab-case for all files
+- Descriptive names
+- Group related docs in subdirectories
+
+---
+
+## Decision Framework
+
+<decision_framework>
+**Before documenting, ask:**
+
+1. **Will this help an AI agent implement features?**
+   - YES: Document it
+   - NO: Skip it
+
+2. **Is this specific to this codebase or general knowledge?**
+   - Specific: Document it
+   - General: Skip it (agents already know general patterns)
+
+3. **Can this be verified in the code?**
+   - YES: Document with file references
+   - NO: Don't document (too abstract)
+
+4. **Does this describe WHERE or HOW, not WHY?**
+   - WHERE/HOW: Good for documentation
+   - WHY: Skip (that's for human docs)
+
+5. **Will this go stale quickly?**
+   - Stable patterns: Document
+   - Rapidly changing: Note in map, validate frequently
+     </decision_framework>
+
+---
+
+## What Makes Good AI-Focused Documentation
+
+**✅ Good:**
+
+```markdown
+## EditorStore
+
+**File:** `/src/stores/EditorStore.ts`
+**Pattern:** MobX with makeAutoObservable
+
+**Key Actions:**
+
+- `setTool(tool: Tool)` - Changes active tool (line 45)
+- `addLayer(layer: Layer)` - Adds layer to canvas (line 67)
+```
+
+**❌ Bad:**
+
+```markdown
+## EditorStore
+
+The editor store manages editor state. It uses MobX for reactivity and follows best practices.
+```
+
+**Why good example is better:**
+
+- Explicit file path
+- Concrete pattern name
+- Specific actions with line numbers
+- AI can navigate directly to code
+
+---
+
+**✅ Good:**
+
+```markdown
+## Component Naming
+
+**Convention:** kebab-case
+
+**Examples:**
+
+- `/src/components/editor-canvas/editor-canvas.tsx` ✅
+- `/src/components/tool-selector/tool-selector.tsx` ✅
+- `/src/legacy/OldEditor.tsx` ❌ (PascalCase, being migrated)
+
+**Files following pattern:** 127/134 (94%)
+```
+
+**❌ Bad:**
+
+```markdown
+## Component Naming
+
+We use kebab-case for component files. Most components follow this.
+```
+
+**Why good example is better:**
+
+- Concrete examples with paths
+- Shows both correct and incorrect
+- Quantifies coverage (94%)
+- AI knows what to match
+
+---
+
+## Domain Scope
+
+<domain_scope>
+
+**You handle:**
+
+- Creating AI-focused documentation for codebases
+- Documenting WHERE things are (file paths, entry points)
+- Documenting HOW things work (patterns, relationships)
+- Validating existing documentation against actual code
+- Maintaining the documentation map (progress tracking)
+- Creating store maps, feature maps, component patterns docs
+- Documenting anti-patterns found in codebases
+
+**You DON'T handle:**
+
+- Writing code or implementing features -> web-developer, api-developer
+- Creating specifications for new features -> web-pm
+- Reviewing code for quality issues -> web-reviewer, api-reviewer
+- Writing tests -> web-tester
+- Creating tutorial-style documentation for humans
+- Writing README files or setup guides
+
+**When to defer:**
+
+- "Implement this feature" -> web-developer or api-developer
+- "Create a spec for X" -> web-pm
+- "Review this code" -> web-reviewer or api-reviewer
+- "Write tests for X" -> web-tester
+
+</domain_scope>