5fea49b7c0
- Transform tufte-press from reference guide to conversation-aware generator - Add JSON generation from conversation context following strict schema - Create build automation scripts with Nix environment handling - Integrate CUPS printing with duplex support - Add comprehensive workflow documentation Scripts added: - skills/tufte-press/scripts/generate-and-build.sh (242 lines) - skills/tufte-press/scripts/build-card.sh (23 lines) Documentation: - Updated SKILL.md with complete workflow instructions (370 lines) - Updated README.md with usage examples (340 lines) - Created SKILL-DEVELOPMENT-STRATEGY-tufte-press.md (450 lines) - Added worklog: 2025-11-10-tufte-press-skill-evolution.org Features: - Agent generates valid JSON from conversation - Schema validation before build (catches errors early) - Automatic Nix shell entry for dependencies - PDF build via tufte-press toolchain - Optional print with duplex support - Self-contained margin notes enforced - Complete end-to-end testing Workflow: Conversation → JSON → Validate → Build → Print Related: niri-window-capture, screenshot-latest, worklog skills
332 lines
14 KiB
Markdown
332 lines
14 KiB
Markdown
# Tasks: Screenshot Analysis Skill
|
|
|
|
**Input**: Design documents from `/specs/001-screenshot-analysis/`
|
|
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/
|
|
|
|
**Tests**: Tests are included for this feature per quickstart.md guidance (bats-core unit tests for each script)
|
|
|
|
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
|
|
|
|
## Format: `[ID] [P?] [Story] Description`
|
|
|
|
- **[P]**: Can run in parallel (different files, no dependencies)
|
|
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
|
|
- Include exact file paths in descriptions
|
|
|
|
## Path Conventions
|
|
|
|
This is a skill project following the repository structure:
|
|
- **Skill**: `skills/screenshot-analysis/`
|
|
- **Tests**: `tests/skills/screenshot-analysis/`
|
|
- **Fixtures**: `tests/skills/screenshot-analysis/fixtures/`
|
|
|
|
---
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Create basic skill structure following repository conventions
|
|
|
|
- [ ] T001 Create skill directory structure at skills/screenshot-analysis/ with subdirs: scripts/, templates/, examples/
|
|
- [ ] T002 [P] Create test directory structure at tests/skills/screenshot-analysis/ with subdirs: unit/, integration/, fixtures/
|
|
- [ ] T003 [P] Create example config template at skills/screenshot-analysis/templates/config.json
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Core helper script that ALL user stories depend on
|
|
|
|
**⚠️ CRITICAL**: This script must be complete before ANY user story implementation
|
|
|
|
- [ ] T004 Implement load-config.sh in skills/screenshot-analysis/scripts/load-config.sh (config loader for all scripts)
|
|
- [ ] T005 Create test fixtures: sample config.json files in tests/skills/screenshot-analysis/fixtures/configs/
|
|
- [ ] T006 Create bats test for load-config.sh in tests/skills/screenshot-analysis/unit/test-load-config.bats
|
|
- [ ] T007 Verify load-config.sh passes all tests and handles edge cases (missing config, malformed JSON, missing jq)
|
|
|
|
**Checkpoint**: Config loading verified - user story scripts can now use it
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Quick Screenshot Analysis (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Enable users to analyze the most recent screenshot without typing file paths
|
|
|
|
**Independent Test**: Take a screenshot, ask agent "look at my last screenshot", verify file found and analyzed without path input
|
|
|
|
### Tests for User Story 1
|
|
|
|
> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
|
|
|
|
- [ ] T008 [P] [US1] Create test fixture: sample screenshot files in tests/skills/screenshot-analysis/fixtures/screenshots/
|
|
- [ ] T009 [US1] Create bats test for find-latest-screenshot.sh in tests/skills/screenshot-analysis/unit/test-find-latest.bats
|
|
- [ ] T010 [US1] Add test case: finds latest screenshot by modification time
|
|
- [ ] T011 [US1] Add test case: excludes symlinks (finds regular files only)
|
|
- [ ] T012 [US1] Add test case: handles empty directory gracefully
|
|
- [ ] T013 [US1] Add test case: applies lexicographic tiebreaker for same timestamp
|
|
- [ ] T014 [US1] Add test case: directory not found error handling
|
|
- [ ] T015 [US1] Add test case: permission denied error handling
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [ ] T016 [US1] Implement find-latest-screenshot.sh in skills/screenshot-analysis/scripts/find-latest-screenshot.sh
|
|
- [ ] T017 [US1] Add shebang, set -euo pipefail, and help flag support
|
|
- [ ] T018 [US1] Implement directory validation (exists, readable)
|
|
- [ ] T019 [US1] Implement find command with -type f filter (excludes symlinks per FR-002a)
|
|
- [ ] T020 [US1] Implement format filtering (.png, .jpg, .jpeg case-insensitive per FR-003)
|
|
- [ ] T021 [US1] Implement stat for modification time extraction
|
|
- [ ] T022 [US1] Implement sort with timestamp + lexicographic tiebreaker (per FR-002)
|
|
- [ ] T023 [US1] Implement error messages for directory not found, permission denied
|
|
- [ ] T024 [US1] Make script executable (chmod +x)
|
|
- [ ] T025 [US1] Run bats tests and verify all pass
|
|
- [ ] T026 [US1] Create SKILL.md in skills/screenshot-analysis/SKILL.md with US1 functionality only
|
|
- [ ] T027 [US1] Add frontmatter metadata (name: screenshot-analysis, description per FR-005)
|
|
- [ ] T028 [US1] Add "When to Use" section with natural language triggers from FR-005
|
|
- [ ] T029 [US1] Add "Process" section showing load-config.sh and find-latest-screenshot.sh invocation
|
|
- [ ] T030 [US1] Add error handling instructions for empty directory case
|
|
- [ ] T031 [US1] Add requirements section (bash, find, stat, sort, jq)
|
|
- [ ] T032 [P] [US1] Create README.md in skills/screenshot-analysis/README.md for users
|
|
- [ ] T033 [P] [US1] Create example-usage.md in skills/screenshot-analysis/examples/example-usage.md
|
|
|
|
**Checkpoint**: US1 complete - user can analyze latest screenshot without typing paths
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Reference Previous Screenshots (Priority: P2)
|
|
|
|
**Goal**: Enable users to reference Nth-recent screenshots and filter by time
|
|
|
|
**Independent Test**: Take 3 screenshots, ask "show me the previous screenshot", verify 2nd-most-recent is found
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [ ] T034 [P] [US2] Create bats test for find-nth-screenshot.sh in tests/skills/screenshot-analysis/unit/test-find-nth.bats
|
|
- [ ] T035 [US2] Add test case: finds Nth most recent screenshot (N=2, N=3)
|
|
- [ ] T036 [US2] Add test case: handles N exceeding available count
|
|
- [ ] T037 [US2] Add test case: validates N is positive integer
|
|
- [ ] T038 [P] [US2] Create bats test for filter-by-time.sh in tests/skills/screenshot-analysis/unit/test-filter-time.bats
|
|
- [ ] T039 [US2] Add test case: filters screenshots from today
|
|
- [ ] T040 [US2] Add test case: filters screenshots from last N minutes
|
|
- [ ] T041 [US2] Add test case: validates time specification format
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [ ] T042 [P] [US2] Implement find-nth-screenshot.sh in skills/screenshot-analysis/scripts/find-nth-screenshot.sh
|
|
- [ ] T043 [US2] Add N parameter validation (positive integer check)
|
|
- [ ] T044 [US2] Reuse find-latest-screenshot.sh logic with sed -n for Nth selection
|
|
- [ ] T045 [US2] Implement error for N exceeding count
|
|
- [ ] T046 [US2] Make script executable
|
|
- [ ] T047 [US2] Run bats tests and verify all pass
|
|
- [ ] T048 [P] [US2] Implement filter-by-time.sh in skills/screenshot-analysis/scripts/filter-by-time.sh
|
|
- [ ] T049 [US2] Implement TIME_SPEC parsing (today, Nm, Nh, Nd)
|
|
- [ ] T050 [US2] Implement find -newermt for "today" filter
|
|
- [ ] T051 [US2] Implement find -mmin for minute-based filtering
|
|
- [ ] T052 [US2] Implement validation for invalid time specs
|
|
- [ ] T053 [US2] Make script executable
|
|
- [ ] T054 [US2] Run bats tests and verify all pass
|
|
- [ ] T055 [US2] Update SKILL.md to add US2 natural language triggers ("previous screenshot", "from today")
|
|
- [ ] T056 [US2] Add find-nth-screenshot.sh invocation examples to SKILL.md
|
|
- [ ] T057 [US2] Add filter-by-time.sh invocation examples to SKILL.md
|
|
- [ ] T058 [P] [US2] Update README.md with US2 usage examples
|
|
- [ ] T059 [P] [US2] Update example-usage.md with Nth screenshot and time filtering examples
|
|
|
|
**Checkpoint**: US1 + US2 complete - users can reference any recent screenshot or filter by time
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Custom Screenshot Directory Support (Priority: P3)
|
|
|
|
**Goal**: Allow users to configure custom screenshot directories
|
|
|
|
**Independent Test**: Create config.json with custom directory, take screenshot there, verify skill finds it
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [ ] T060 [US3] Extend test-load-config.bats with custom directory path tests
|
|
- [ ] T061 [US3] Add test case: loads custom directory from config.json
|
|
- [ ] T062 [US3] Add test case: expands tilde in config path
|
|
- [ ] T063 [US3] Add test case: validates custom directory exists
|
|
- [ ] T064 [US3] Extend test-find-latest.bats to test with custom config directory
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [ ] T065 [US3] Verify load-config.sh already handles custom directories (implemented in T004)
|
|
- [ ] T066 [US3] Update SKILL.md to document custom config file usage
|
|
- [ ] T067 [US3] Add configuration section to SKILL.md with config.json location and format
|
|
- [ ] T068 [US3] Add error handling instructions for invalid custom directory
|
|
- [ ] T069 [P] [US3] Update README.md with configuration instructions
|
|
- [ ] T070 [P] [US3] Update templates/config.json with comments and examples
|
|
- [ ] T071 [US3] Run all bats tests with custom config scenarios
|
|
- [ ] T072 [P] [US3] Add configuration examples to example-usage.md
|
|
|
|
**Checkpoint**: US1 + US2 + US3 complete - all user stories functional independently
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final validation and documentation across all user stories
|
|
|
|
- [ ] T073 [P] Create integration test script in tests/skills/screenshot-analysis/integration/test-skill-invocation.sh
|
|
- [ ] T074 Add manual test checklist: deploy to agent, test natural language triggers, verify image analysis
|
|
- [ ] T075 [P] Add installation section to README.md (for Claude Code and OpenCode)
|
|
- [ ] T076 [P] Add troubleshooting section to README.md (jq not found, empty directory, permissions)
|
|
- [ ] T077 Verify all scripts have correct shebang and execute permissions
|
|
- [ ] T078 [P] Verify all bats tests pass in clean environment
|
|
- [ ] T079 Run performance validation: 1000 files in <1 second (SC-002)
|
|
- [ ] T080 [P] Add skill to main repository README.md in skills section
|
|
- [ ] T081 Validate against quickstart.md success criteria checklist
|
|
- [ ] T082 Final review: SKILL.md follows template structure from skills/template/
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies - can start immediately
|
|
- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
|
|
- **User Stories (Phase 3-5)**: All depend on Foundational phase completion
|
|
- User stories can then proceed in parallel (if staffed)
|
|
- Or sequentially in priority order (P1 → P2 → P3)
|
|
- **Polish (Phase 6)**: Depends on all desired user stories being complete
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: Depends only on Foundational (Phase 2) - No dependencies on other stories
|
|
- **User Story 2 (P2)**: Depends only on Foundational (Phase 2) - Independent of US1 (own scripts)
|
|
- **User Story 3 (P3)**: Depends only on Foundational (Phase 2) - Independent of US1/US2 (config already in load-config.sh)
|
|
|
|
### Within Each User Story
|
|
|
|
- Tests MUST be written and FAIL before implementation
|
|
- Scripts before SKILL.md updates
|
|
- SKILL.md before README.md/examples
|
|
- Bats tests pass before moving to next story
|
|
|
|
### Parallel Opportunities
|
|
|
|
**Phase 1 (Setup)**:
|
|
- T002 and T003 can run in parallel with T001
|
|
|
|
**Phase 2 (Foundational)**:
|
|
- T005 and T006 can run in parallel (after T004)
|
|
|
|
**Phase 3 (US1)**:
|
|
- T008 can run in parallel (test fixtures)
|
|
- T032 and T033 can run in parallel (after SKILL.md complete)
|
|
|
|
**Phase 4 (US2)**:
|
|
- T034 and T038 can run in parallel (different test files)
|
|
- T042 and T048 can run in parallel (different script files)
|
|
- T058 and T059 can run in parallel (after SKILL.md updates)
|
|
|
|
**Phase 5 (US3)**:
|
|
- T069, T070, T072 can run in parallel (different documentation files)
|
|
|
|
**Phase 6 (Polish)**:
|
|
- T073, T075, T076, T078, T080 can all run in parallel
|
|
|
|
**Across User Stories** (if team capacity allows):
|
|
- Once Phase 2 completes, US1, US2, US3 can all start in parallel by different developers
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Launch tests together (after fixtures created):
|
|
Task: "Add test case: finds latest screenshot by modification time"
|
|
Task: "Add test case: excludes symlinks"
|
|
Task: "Add test case: handles empty directory gracefully"
|
|
|
|
# Launch documentation together (after SKILL.md complete):
|
|
Task: "Create README.md for users"
|
|
Task: "Create example-usage.md"
|
|
```
|
|
|
|
---
|
|
|
|
## Parallel Example: Multiple User Stories
|
|
|
|
```bash
|
|
# After Foundational (Phase 2) completes, launch in parallel:
|
|
|
|
Developer A: Focus on User Story 1 (T008-T033)
|
|
Developer B: Focus on User Story 2 (T034-T059)
|
|
Developer C: Focus on User Story 3 (T060-T072)
|
|
|
|
# Each developer can work independently on their story's scripts
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (User Story 1 Only)
|
|
|
|
1. Complete Phase 1: Setup (T001-T003)
|
|
2. Complete Phase 2: Foundational (T004-T007) - CRITICAL
|
|
3. Complete Phase 3: User Story 1 (T008-T033)
|
|
4. **STOP and VALIDATE**: Test US1 independently with real agent
|
|
5. Deploy/demo basic screenshot analysis capability
|
|
|
|
**Result**: Core value delivered - users can analyze latest screenshot without typing paths
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Complete Setup + Foundational → Config loading works
|
|
2. Add User Story 1 → Test independently → **Deploy MVP** ✅
|
|
3. Add User Story 2 → Test independently → Deploy enhanced version (Nth, time filtering)
|
|
4. Add User Story 3 → Test independently → Deploy full feature (custom directories)
|
|
5. Polish → Final validation → Production ready
|
|
|
|
Each story adds value without breaking previous stories.
|
|
|
|
### Parallel Team Strategy
|
|
|
|
With multiple developers:
|
|
|
|
1. Team completes Setup + Foundational together (T001-T007)
|
|
2. Once Foundational is done:
|
|
- Developer A: User Story 1 (T008-T033) - Core functionality
|
|
- Developer B: User Story 2 (T034-T059) - Enhanced referencing
|
|
- Developer C: User Story 3 (T060-T072) - Custom config
|
|
3. Stories complete independently, integrate via shared load-config.sh
|
|
4. Team converges on Polish (T073-T082)
|
|
|
|
---
|
|
|
|
## Task Summary
|
|
|
|
**Total Tasks**: 82
|
|
|
|
**By Phase**:
|
|
- Phase 1 (Setup): 3 tasks
|
|
- Phase 2 (Foundational): 4 tasks (BLOCKING)
|
|
- Phase 3 (US1 - P1): 26 tasks (MVP)
|
|
- Phase 4 (US2 - P2): 26 tasks
|
|
- Phase 5 (US3 - P3): 13 tasks
|
|
- Phase 6 (Polish): 10 tasks
|
|
|
|
**By User Story**:
|
|
- US1 (P1): 26 tasks - Core screenshot analysis
|
|
- US2 (P2): 26 tasks - Nth screenshot + time filtering
|
|
- US3 (P3): 13 tasks - Custom directory configuration
|
|
|
|
**Parallel Opportunities**: 21 tasks marked [P] (25% can run in parallel)
|
|
|
|
**MVP Scope** (Recommended): Phase 1 + 2 + 3 (33 tasks) delivers core value
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- [P] tasks = different files, no dependencies on incomplete tasks
|
|
- [Story] label maps task to specific user story (US1, US2, US3)
|
|
- Each user story is independently testable
|
|
- Tests use bats-core framework per research.md decisions
|
|
- Scripts follow contract specifications from contracts/script-interface.md
|
|
- All scripts use `set -euo pipefail` error handling per research.md
|
|
- Performance target: <1s for 1000 files (validated in T079)
|
|
- Skill structure follows repository conventions (skills/template/)
|