diff --git a/.llm/README.md b/.llm/README.md new file mode 100644 index 0000000..c374b12 --- /dev/null +++ b/.llm/README.md @@ -0,0 +1,20 @@ +# LLM Workflow Documentation + +Documentation for AI assistants working on this project. + +## Structure + +- **procedure/** - Reusable workflows +- **features/** - Completed: `done_F-{n}.md`, `done_ISSUE-{n}.md` +- **tasks/todo/** - Planned: `plan_F-{n}.md`, `plan_ISSUE-{n}.md` + +## Workflows + +Two separate workflows that never mix: + +**F-n (Manual):** `plan_F-6.md` → `done_F-6.md` +**ISSUE-n (GitHub):** `plan_ISSUE-42.md` → `done_ISSUE-42.md` + +- Numbers stay forever (F-6 never becomes F-5 or ISSUE-42) +- Gaps in numbering expected +- ISSUE-n imported via `procedure{source_github}` (label: `ready_for_dev`) diff --git a/.llm/bootstrap-llm-wow.md b/.llm/bootstrap-llm-wow.md new file mode 100644 index 0000000..3627743 --- /dev/null +++ b/.llm/bootstrap-llm-wow.md @@ -0,0 +1,135 @@ +# Bootstrap: LLM Ways of Working + +**Invocation:** `bootstrap ways of working from bootstrap-llm-wow.md` + +## Creates + +``` +.llm/ +├── README.md +├── bootstrap-llm-wow.md (self-copy) +├── procedure/import-tasks-github.md +├── features/ (empty) +└── tasks/todo/ (empty) +CLAUDE.md (root) +``` + +## Steps + +### 1. Check Existing +`ls -la .llm/` → if exists, ask: Merge | Override | Cancel + +### 2. Create Structure +```bash +mkdir -p .llm/{procedure,features,tasks/todo} +``` + +### 3. Create .llm/README.md +```markdown +# LLM Workflow Documentation + +## Structure +- **procedure/** - Reusable workflows +- **features/** - Completed: `done_F-{n}.md`, `done_ISSUE-{n}.md` +- **tasks/todo/** - Planned: `plan_F-{n}.md`, `plan_ISSUE-{n}.md` + +## Workflows +**F-n (Manual):** `plan_F-6.md` → `done_F-6.md` +**ISSUE-n (GitHub):** `plan_ISSUE-42.md` → `done_ISSUE-42.md` + +Numbers stay forever. Gaps expected. ISSUE-n via `procedure{source_github}` (label: `ready_for_dev`). +``` + +### 4. Self-Replicate +Copy this file to `.llm/bootstrap-llm-wow.md` + +### 5. Create .llm/procedure/import-tasks-github.md +```markdown +# Procedure: Import GitHub Issues as Tasks + +**Invocation:** `procedure{source_github}` + +## Steps +1. Get repo: `git remote get-url origin` → parse owner/name +2. Fetch: `gh issue list --label "ready_for_dev" --state open --json number,title,body,labels` +3. Create: `.llm/tasks/todo/plan_ISSUE-{n}.md` for each + +## Template +# ISSUE-{n}: {Title} +**GitHub:** #{n} | {url} +**Created:** {date} +## Problem/Solution/Steps/Notes +{from issue or TBD} + +## Rules +- `plan_ISSUE-42.md` → `done_ISSUE-42.md` +- Skip if exists +- ISSUE-n ≠ F-n +- Report: count, files, skipped +``` + +### 6. CLAUDE.md + +**If missing:** Create with template below + `[PROJECT-SPECIFIC]` placeholders +**If exists:** Check for "Feature Documentation Process" → add if missing, preserve rest + +```markdown +# CLAUDE.md + +## Project Overview +[PROJECT-SPECIFIC] + +## Feature Documentation Process + +### Completed Features +1. Document in `.llm/features/done_F-{n}.md` (same n as plan) +2. Include: overview, files changed, tests, commits, migrations +3. Delete plan from `.llm/tasks/todo/` + +### Planned Features +1. Create `.llm/tasks/todo/plan_F-{n}.md` +2. Include: problem, solution, steps, benefits, effort +3. Move to `done_F-{n}.md` when done (KEEP NUMBER) + +**Plan mode:** Write to `.llm/tasks/todo/plan_F-{n}.md` (NOT `~/.claude/plans/`) + +### Feature Numbering +- Numbers = plan date, not implement date +- `plan_F-6.md` → `done_F-6.md` (never renumber) +- Gaps expected + +### GitHub Integration +- ISSUE-n: `plan_ISSUE-42.md` → `done_ISSUE-42.md` +- Invoke: `procedure{source_github}` (label: `ready_for_dev`) +- F-n ≠ ISSUE-n (never mix) + +## LLM Procedures +See `.llm/procedure/` for workflows (e.g., `import-tasks-github.md`) + +## [PROJECT-SPECIFIC SECTIONS] +[Add: Best Practices, Commands, Structure, Architecture, Patterns] +``` + +### 7. Optional .gitignore +Ask user to add: +``` +# .claude/ +# .agents/ +``` +(`.llm/` stays tracked) + +### 8. Report +``` +✅ Bootstrap Complete! + +Created: .llm/{README,bootstrap,procedure/import-tasks-github,features/,tasks/todo/} +Updated: CLAUDE.md [new/merged] + +Next: +- Customize CLAUDE.md +- Create plan_F-1.md or run procedure{source_github} +- Commit .llm/ +``` + +## Replication +Copy this file to new repo → run invocation → done diff --git a/docs/features/done_F-1.md b/.llm/features/done_F-1.md similarity index 100% rename from docs/features/done_F-1.md rename to .llm/features/done_F-1.md diff --git a/docs/features/done_F-6.md b/.llm/features/done_F-6.md similarity index 100% rename from docs/features/done_F-6.md rename to .llm/features/done_F-6.md diff --git a/.llm/procedure/import-tasks-github.md b/.llm/procedure/import-tasks-github.md new file mode 100644 index 0000000..53756d6 --- /dev/null +++ b/.llm/procedure/import-tasks-github.md @@ -0,0 +1,42 @@ +# Procedure: Import GitHub Issues as Tasks + +**Invocation:** `procedure{source_github}` + +## Steps + +1. **Get repo info:** `git remote get-url origin` → parse owner/name +2. **Fetch issues:** `gh issue list --label "ready_for_dev" --state open --json number,title,body,labels` +3. **Create plans:** For each issue → `.llm/tasks/todo/plan_ISSUE-{n}.md` + +## Plan Template + +```markdown +# ISSUE-{n}: {Title} + +**GitHub:** #{n} | https://github.com/{owner}/{repo}/issues/{n} +**Created:** {date} + +## Problem +{from issue body or TBD} + +## Solution +{from issue body or TBD} + +## Steps +{from issue body or TBD} + +## Notes +{additional context} +``` + +## Rules + +- Naming: `plan_ISSUE-42.md` → `done_ISSUE-42.md` +- Skip if plan exists +- ISSUE-n separate from F-n (never mix) +- Report: count, titles, files created, skipped + +## Edge Cases +- No `gh` CLI: provide install instructions +- Not authenticated: run `gh auth login` +- Empty issue body: use TBD placeholders \ No newline at end of file diff --git a/docs/tasks/todo/plan_F-2.md b/.llm/tasks/todo/plan_F-2.md similarity index 100% rename from docs/tasks/todo/plan_F-2.md rename to .llm/tasks/todo/plan_F-2.md diff --git a/docs/tasks/todo/plan_F-3.md b/.llm/tasks/todo/plan_F-3.md similarity index 100% rename from docs/tasks/todo/plan_F-3.md rename to .llm/tasks/todo/plan_F-3.md diff --git a/docs/tasks/todo/plan_F-4.md b/.llm/tasks/todo/plan_F-4.md similarity index 100% rename from docs/tasks/todo/plan_F-4.md rename to .llm/tasks/todo/plan_F-4.md diff --git a/docs/tasks/todo/plan_F-5.md b/.llm/tasks/todo/plan_F-5.md similarity index 100% rename from docs/tasks/todo/plan_F-5.md rename to .llm/tasks/todo/plan_F-5.md diff --git a/CLAUDE.md b/CLAUDE.md index 65ebee6..836a0a5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,483 +1,218 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +Guidance for Claude Code working on this repository. ## Project Overview -Film Photography Tracker is a Progressive Web App (PWA) for tracking film photography metadata. Built with React 18, TypeScript, Vite, and Material-UI, it helps photographers record and organize shots with exposure details, location data, and camera information. +Film Photography Tracker - PWA for tracking film photography metadata. React 18, TypeScript, Vite, Material-UI. Records shots with exposure details, location, camera info. ## Feature Documentation Process -When completing work on a feature or making significant changes: - ### Completed Features -1. **Document the feature** in `docs/features/done_F-{n}.md` where `n` matches the original plan number -2. **Include in the documentation:** - - Feature overview and key components - - Technical details (files changed, new APIs, data models) - - User benefits and use cases - - Testing coverage - - Commits included - - Migration notes (if applicable) - - Future enhancement ideas -3. **Naming convention:** `done_F-1.md`, `done_F-6.md`, etc. (keeps original plan number) -4. **Delete task plans** from `docs/tasks/todo/` once implemented +1. Document in `.llm/features/done_F-{n}.md` (same n as plan) +2. Include: overview, files changed, APIs, tests, commits, migrations +3. Delete plan from `.llm/tasks/todo/` ### Planned Features -1. **Create plan** in `docs/tasks/todo/plan_F-{n}.md` for future features -2. **Include in the plan:** - - Problem statement - - Proposed solution - - Implementation steps - - Benefits and trade-offs - - Effort estimate -3. **Naming convention:** `plan_F-5.md`, `plan_F-6.md`, etc. -4. **Move to done_F-{n}.md** once implemented (KEEP THE SAME NUMBER) - -**IMPORTANT for Claude Code plan mode:** When entering plan mode, ALWAYS write the final plan to `docs/tasks/todo/plan_F-{n}.md` (NOT to `~/.claude/plans/`). This ensures plans are tracked in the repository. +1. Create `.llm/tasks/todo/plan_F-{n}.md` +2. Include: problem, solution, steps, benefits, effort +3. Move to `done_F-{n}.md` when done (KEEP NUMBER) + +**Plan mode:** Write to `.llm/tasks/todo/plan_F-{n}.md` (NOT `~/.claude/plans/`) ### Feature Numbering -**IMPORTANT:** Feature numbers are assigned when planned and stay with the feature forever: -- Numbers reflect when features were **planned**, not when they were **implemented** -- `plan_F-6.md` becomes `done_F-6.md` (NOT `done_F-2.md`) -- Features can be implemented in any order -- Gaps in numbering are expected (e.g., `done_F-1.md`, `done_F-6.md`, `plan_F-2.md`, `plan_F-5.md`) -- Never renumber features - each feature keeps its original plan number -- Completed features use `done_` prefix -- Planned features use `plan_` prefix - -**Example:** -- `plan_F-2.md` → implemented later → becomes `done_F-2.md` -- `plan_F-6.md` → implemented first → becomes `done_F-6.md` -- Result: `docs/features/` has `done_F-1.md`, `done_F-6.md` (F-2 through F-5 still planned or not yet created) +- Numbers = plan date, not implement date +- `plan_F-6.md` → `done_F-6.md` (never renumber) +- Gaps expected (e.g., `done_F-1.md`, `done_F-6.md`, `plan_F-2.md`, `plan_F-5.md`) -## Coding Best Practices +### GitHub Integration +- ISSUE-n: `plan_ISSUE-42.md` → `done_ISSUE-42.md` +- Invoke: `procedure{source_github}` (label: `ready_for_dev`) +- F-n ≠ ISSUE-n (never mix) -### Component Composition +## LLM Procedures +See `.llm/procedure/` for workflows (e.g., `import-tasks-github.md`) -**DO:** -- ✅ Use shared components from `src/components/common/` for repeated patterns -- ✅ Check if a shared component exists before creating duplicate UI (DialogHeader, EmptyStateDisplay, ConfirmationDialog, etc.) -- ✅ Use selector components (LensSelector, ApertureSelector, ShutterSpeedSelector) instead of TextField with select prop -- ✅ Extract components when the same pattern appears 2+ times - -**DON'T:** -- ❌ Copy-paste dialog headers, empty states, or confirmation dialogs -- ❌ Use window.confirm() or window.alert() - use ConfirmationDialog instead -- ❌ Create new selector components without checking common/ directory first -- ❌ Over-engineer - don't extract components for patterns that appear only 1-2 times and not very common, or can't be easily extracted +## Coding Best Practices -### MUI Component Accessibility +### Component Composition +**DO:** Use shared from `src/components/common/` (DialogHeader, EmptyStateDisplay, ConfirmationDialog, EntityContextMenu, LensSelector, ApertureSelector, ShutterSpeedSelector). Extract when pattern appears 2+ times. -When creating new MUI Select components: +**DON'T:** Copy-paste dialog headers, empty states, confirmation dialogs. Use window.confirm/alert. Over-engineer for 1-2 instances. -**ALWAYS:** +### MUI Select Accessibility +Always use `useId()` to connect InputLabel/Select: ```typescript -import { useId } from 'react'; - -const MySelector = () => { - const id = useId(); // Generate unique ID for accessibility - - return ( - - My Label - - - ); -}; +const id = useId(); +Label +