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
140 lines
6.7 KiB
Markdown
140 lines
6.7 KiB
Markdown
# Implementation Plan: Screenshot Analysis Skill
|
|
|
|
**Branch**: `001-screenshot-analysis` | **Date**: 2025-11-08 | **Spec**: [spec.md](./spec.md)
|
|
**Input**: Feature specification from `/specs/001-screenshot-analysis/spec.md`
|
|
|
|
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
|
|
|
## Summary
|
|
|
|
Create a skill that automatically finds and analyzes the most recent screenshot from a configured directory (default: ~/Pictures/Screenshots), eliminating the need for users to type file paths repeatedly. The skill uses bash scripts to locate files by modification time, applies lexicographic ordering as a tiebreaker, and passes the discovered file path to the agent's image analysis capability. Configuration is stored in a skill-specific JSON file.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: Bash 4.0+ (for helper scripts), Markdown (for skill definition)
|
|
**Primary Dependencies**: Standard Unix utilities (ls, find, stat, test), jq (for JSON config parsing)
|
|
**Storage**: JSON configuration file (optional, skill-specific: ~/.config/opencode/skills/screenshot-analysis/config.json or ~/.claude/skills/screenshot-analysis/config.json)
|
|
**Testing**: Bash test framework (bats-core) for script unit tests, manual integration testing with Claude Code/OpenCode agents
|
|
**Target Platform**: Linux (Ubuntu, NixOS, Fedora), Bash-compatible shells
|
|
**Project Type**: Skill (agent capability extension) - follows skills/ directory structure from repository
|
|
**Performance Goals**: <1 second file discovery for directories with up to 1000 files (SC-002)
|
|
**Constraints**: Read-only filesystem access, no external network dependencies, must work with both Claude Code and OpenCode
|
|
**Scale/Scope**: Single skill with 3-5 helper scripts, SKILL.md definition, config template, examples
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
**Note**: No project-specific constitution file exists (template only). Applying general skill development principles from repository:
|
|
|
|
✅ **Self-Contained**: Skill includes all necessary scripts, templates, and documentation
|
|
✅ **Testable**: Each helper script can be tested independently; integration tests via agent invocation
|
|
✅ **Technology-Agnostic**: Bash scripts are portable; skill works with both Claude Code and OpenCode
|
|
✅ **Clear Purpose**: Eliminates repetitive path typing for screenshot analysis
|
|
✅ **No Implementation Leakage**: SKILL.md focuses on WHAT (find screenshots) not HOW (specific bash commands)
|
|
|
|
**Status**: PASS - No violations detected
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/[###-feature]/
|
|
├── plan.md # This file (/speckit.plan command output)
|
|
├── research.md # Phase 0 output (/speckit.plan command)
|
|
├── data-model.md # Phase 1 output (/speckit.plan command)
|
|
├── quickstart.md # Phase 1 output (/speckit.plan command)
|
|
├── contracts/ # Phase 1 output (/speckit.plan command)
|
|
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
skills/screenshot-analysis/
|
|
├── SKILL.md # Agent instructions (primary interface)
|
|
├── README.md # User documentation
|
|
├── scripts/
|
|
│ ├── find-latest-screenshot.sh # Core: locate most recent screenshot
|
|
│ ├── find-nth-screenshot.sh # Support Nth-recent (P2: "previous")
|
|
│ ├── filter-by-time.sh # Support time filtering (P2: "from today")
|
|
│ └── load-config.sh # Parse JSON config, return screenshot_dir
|
|
├── templates/
|
|
│ └── config.json # Example configuration file
|
|
└── examples/
|
|
└── example-usage.md # Example agent interactions
|
|
|
|
tests/
|
|
└── skills/
|
|
└── screenshot-analysis/
|
|
├── unit/
|
|
│ ├── test-find-latest.bats # Test find-latest-screenshot.sh
|
|
│ ├── test-find-nth.bats # Test find-nth-screenshot.sh
|
|
│ ├── test-filter-time.bats # Test filter-by-time.sh
|
|
│ └── test-load-config.bats # Test load-config.sh
|
|
├── integration/
|
|
│ └── test-skill-invocation.sh # Manual: test with real agent
|
|
└── fixtures/
|
|
├── screenshots/ # Test screenshot files
|
|
└── configs/ # Test config.json variants
|
|
```
|
|
|
|
**Structure Decision**: Follows repository's established skill structure (see skills/template/, skills/worklog/, skills/update-spec-kit/). Each skill is self-contained with SKILL.md, README.md, scripts/, templates/, and examples/. Tests live in a parallel tests/ directory structure.
|
|
|
|
## Complexity Tracking
|
|
|
|
**Status**: No violations - Constitution Check passed
|
|
|
|
No complexity justifications needed. The skill adheres to all principles:
|
|
- Self-contained design (scripts, templates, docs in one directory)
|
|
- Clear interface contracts (documented in contracts/)
|
|
- Test-first compatible (bats tests defined)
|
|
- Simple technology stack (bash, jq, standard tools)
|
|
|
|
---
|
|
|
|
## Phase 0: Research ✅ COMPLETE
|
|
|
|
**Output**: [research.md](./research.md)
|
|
|
|
**Key Decisions**:
|
|
- File discovery: `find -type f` with `stat` and `sort` (<1s for 1000 files)
|
|
- JSON parsing: `jq` with graceful fallback
|
|
- Timestamp tiebreaker: Lexicographic filename ordering
|
|
- Testing: bats-core framework
|
|
- Error handling: `set -euo pipefail` with descriptive messages
|
|
|
|
**Status**: All technical unknowns resolved
|
|
|
|
---
|
|
|
|
## Phase 1: Design & Contracts ✅ COMPLETE
|
|
|
|
**Outputs**:
|
|
- [data-model.md](./data-model.md) - Entities, validation rules, data flow
|
|
- [contracts/script-interface.md](./contracts/script-interface.md) - Script CLI contracts
|
|
- [quickstart.md](./quickstart.md) - 5-minute setup guide
|
|
- [AGENTS.md](../../AGENTS.md) - Updated with skill tech stack
|
|
|
|
**Key Artifacts**:
|
|
1. **Data Model**: Screenshot File, Screenshot Directory, Skill Configuration entities
|
|
2. **Script Contracts**: 4 helper scripts with defined inputs/outputs/errors
|
|
3. **Integration Flow**: SKILL.md → scripts → agent image analysis
|
|
|
|
**Post-Design Constitution Check**: ✅ PASS
|
|
- Scripts follow single-responsibility principle
|
|
- Clear separation: file discovery (bash) vs. image analysis (agent)
|
|
- No unnecessary complexity added
|
|
- Test contracts defined for all scripts
|
|
|
|
**Status**: Design complete, ready for implementation
|
|
|
|
---
|
|
|
|
## Next Phase
|
|
|
|
**Phase 2: Task Breakdown** - Use `/speckit.tasks` to generate implementation tasks
|
|
|
|
This will create `tasks.md` with prioritized implementation tasks based on user stories P1-P3.
|