worktrees 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7c0973aeb2135810ab165544d4bdb82a16b234fba3a3c17504d9650ac964a069
+  data.tar.gz: e98633f2e3c2eb6952fe1bbe811398cc5a34d33edb0b8f6dd9ddb7dfa51ad2b6
+SHA512:
+  metadata.gz: 692b7d2cbb11df4e8707c8bd6dfd397908d5e5f41b161ab44e90aa521e07afbf80a3eab9dd6b25bc711a4db4b18f4c46fac906fab01722a2e510ea55b178da3c
+  data.tar.gz: a8b6939c381effd8dd72ad59caa41ff0d59d2022bbf1aa2dd40080b3365ea83650e7e4708e6e24b613ac92dceb25311e98b9c6a3d4b550cbcf1cbac57a5adefe

data/.claude/commands/plan.md

@@ -0,0 +1,42 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+---
+
+Given the implementation details provided as an argument, do this:
+
+1. Run `.specify/scripts/bash/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
+2. Read and analyze the feature specification to understand:
+   - The feature requirements and user stories
+   - Functional and non-functional requirements
+   - Success criteria and acceptance criteria
+   - Any technical constraints or dependencies mentioned
+
+3. Read my personal principles at `.specify/memory/constitution.md` to understand my approach:
+   - Ruby First: Choose Ruby because it makes me productive and happy
+   - Simple Over Clever: Code I can understand in six months
+   - Test-Driven Development is Fundamental: Write tests first, always
+
+4. Execute the implementation plan template:
+   - Load `.specify/templates/plan-template.md` (already copied to IMPL_PLAN path)
+   - Set Input path to FEATURE_SPEC
+   - Run the Execution Flow (main) function steps 1-10
+   - The template is self-contained and executable
+   - Follow error handling and gate checks as specified
+   - Let the template guide artifact generation in $SPECS_DIR:
+     * Phase 0 generates research.md
+     * Phase 1 generates data-model.md, contracts/, quickstart.md
+     * Phase 2 generates tasks.md
+   - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS
+   - **IMPORTANT**: Validate against personal principles in Development Principles Check
+   - For CLIs: Start with Ruby + dry-cli unless there's a specific reason not to
+   - Remember: "Life's too short for verbose languages when building personal tools"
+   - Update Progress Tracking as you complete each phase
+
+5. Verify execution completed:
+   - Check Progress Tracking shows all phases complete
+   - Ensure all required artifacts were generated
+   - Confirm no ERROR states in execution
+
+6. Report results with branch name, file paths, and generated artifacts.
+
+Use absolute paths with the repository root for all file operations to avoid path issues.

data/.claude/commands/specify.md

@@ -0,0 +1,12 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+---
+
+Given the feature description provided as an argument, do this:
+
+1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
+2. Load `.specify/templates/spec-template.md` to understand required sections.
+3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+4. Report completion with branch name, spec file path, and readiness for the next phase.
+
+Note: The script creates and checks out the new branch and initializes the spec file before writing.

data/.claude/commands/tasks.md

@@ -0,0 +1,60 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+---
+
+Given the context provided as an argument, do this:
+
+1. Run `.specify/scripts/bash/check-task-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+2. Load and analyze available design documents:
+   - Always read plan.md for tech stack and libraries
+   - IF EXISTS: Read data-model.md for entities
+   - IF EXISTS: Read contracts/ for API endpoints
+   - IF EXISTS: Read research.md for technical decisions
+   - IF EXISTS: Read quickstart.md for test scenarios
+
+   Note: Not all projects have all documents. For example:
+   - CLI tools might not have contracts/
+   - Simple libraries might not need data-model.md
+   - Generate tasks based on what's available
+
+3. Generate tasks following the template:
+   - Use `.specify/templates/tasks-template.md` as the base
+   - Replace example tasks with actual tasks based on:
+     * **Setup tasks**: Project init, dependencies, linting
+     * **Ruby CLI Setup**: Gemfile, RSpec config, dry-cli setup (if Ruby detected)
+     * **Test tasks [P]**: Aruba feature tests, RSpec unit tests (Ruby), contract tests
+     * **Core tasks**: CLI commands, business logic modules (Simple Over Clever approach)
+     * **Integration tasks**: Real git operations, error handling, logging
+     * **Polish tasks [P]**: Unit tests, performance, docs
+
+4. Task generation rules:
+   - Each contract file → contract test task marked [P]
+   - Each entity in data-model → model creation task marked [P]
+   - Each CLI command → dry-cli command class task marked [P] (Ruby)
+   - Each user story → Aruba integration test marked [P] (Ruby)
+   - Different files = can be parallel [P]
+   - Same file = sequential (no [P])
+   - **IMPORTANT**: Tests MUST be created before implementation (Test-Driven Development is Fundamental)
+
+5. Order tasks by dependencies:
+   - Setup before everything
+   - Tests before implementation (TDD)
+   - Models before services
+   - Services before endpoints
+   - Core before integration
+   - Everything before polish
+
+6. Include parallel execution examples:
+   - Group [P] tasks that can run together
+   - Show actual Task agent commands
+
+7. Create FEATURE_DIR/tasks.md with:
+   - Correct feature name from implementation plan
+   - Numbered tasks (T001, T002, etc.)
+   - Clear file paths for each task
+   - Dependency notes
+   - Parallel execution guidance
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.

data/.cursor/commands/plan.md

@@ -0,0 +1,42 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+---
+
+Given the implementation details provided as an argument, do this:
+
+1. Run `.specify/scripts/bash/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
+2. Read and analyze the feature specification to understand:
+   - The feature requirements and user stories
+   - Functional and non-functional requirements
+   - Success criteria and acceptance criteria
+   - Any technical constraints or dependencies mentioned
+
+3. Read my personal principles at `.specify/memory/constitution.md` to understand my approach:
+   - Ruby First: Choose Ruby because it makes me productive and happy
+   - Simple Over Clever: Code I can understand in six months
+   - Test-Driven Development is Fundamental: Write tests first, always
+
+4. Execute the implementation plan template:
+   - Load `.specify/templates/plan-template.md` (already copied to IMPL_PLAN path)
+   - Set Input path to FEATURE_SPEC
+   - Run the Execution Flow (main) function steps 1-10
+   - The template is self-contained and executable
+   - Follow error handling and gate checks as specified
+   - Let the template guide artifact generation in $SPECS_DIR:
+     * Phase 0 generates research.md
+     * Phase 1 generates data-model.md, contracts/, quickstart.md
+     * Phase 2 generates tasks.md
+   - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS
+   - **IMPORTANT**: Validate against personal principles in Development Principles Check
+   - For CLIs: Start with Ruby + dry-cli unless there's a specific reason not to
+   - Remember: "Life's too short for verbose languages when building personal tools"
+   - Update Progress Tracking as you complete each phase
+
+5. Verify execution completed:
+   - Check Progress Tracking shows all phases complete
+   - Ensure all required artifacts were generated
+   - Confirm no ERROR states in execution
+
+6. Report results with branch name, file paths, and generated artifacts.
+
+Use absolute paths with the repository root for all file operations to avoid path issues.

data/.cursor/commands/specify.md

@@ -0,0 +1,12 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+---
+
+Given the feature description provided as an argument, do this:
+
+1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
+2. Load `.specify/templates/spec-template.md` to understand required sections.
+3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+4. Report completion with branch name, spec file path, and readiness for the next phase.
+
+Note: The script creates and checks out the new branch and initializes the spec file before writing.

data/.cursor/commands/tasks.md

@@ -0,0 +1,60 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+---
+
+Given the context provided as an argument, do this:
+
+1. Run `.specify/scripts/bash/check-task-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+2. Load and analyze available design documents:
+   - Always read plan.md for tech stack and libraries
+   - IF EXISTS: Read data-model.md for entities
+   - IF EXISTS: Read contracts/ for API endpoints
+   - IF EXISTS: Read research.md for technical decisions
+   - IF EXISTS: Read quickstart.md for test scenarios
+
+   Note: Not all projects have all documents. For example:
+   - CLI tools might not have contracts/
+   - Simple libraries might not need data-model.md
+   - Generate tasks based on what's available
+
+3. Generate tasks following the template:
+   - Use `.specify/templates/tasks-template.md` as the base
+   - Replace example tasks with actual tasks based on:
+     * **Setup tasks**: Project init, dependencies, linting
+     * **Ruby CLI Setup**: Gemfile, RSpec config, dry-cli setup (if Ruby detected)
+     * **Test tasks [P]**: Aruba feature tests, RSpec unit tests (Ruby), contract tests
+     * **Core tasks**: CLI commands, business logic modules (Simple Over Clever approach)
+     * **Integration tasks**: Real git operations, error handling, logging
+     * **Polish tasks [P]**: Unit tests, performance, docs
+
+4. Task generation rules:
+   - Each contract file → contract test task marked [P]
+   - Each entity in data-model → model creation task marked [P]
+   - Each CLI command → dry-cli command class task marked [P] (Ruby)
+   - Each user story → Aruba integration test marked [P] (Ruby)
+   - Different files = can be parallel [P]
+   - Same file = sequential (no [P])
+   - **IMPORTANT**: Tests MUST be created before implementation (Test-Driven Development is Fundamental)
+
+5. Order tasks by dependencies:
+   - Setup before everything
+   - Tests before implementation (TDD)
+   - Models before services
+   - Services before endpoints
+   - Core before integration
+   - Everything before polish
+
+6. Include parallel execution examples:
+   - Group [P] tasks that can run together
+   - Show actual Task agent commands
+
+7. Create FEATURE_DIR/tasks.md with:
+   - Correct feature name from implementation plan
+   - Numbered tasks (T001, T002, etc.)
+   - Clear file paths for each task
+   - Dependency notes
+   - Parallel execution guidance
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.

data/.cursor/rules

@@ -0,0 +1,81 @@
+# Cursor IDE Development Guidelines - Worktrees Project
+
+This project follows my personal development principles defined in `.specify/memory/constitution.md` for Ruby CLI development.
+
+## My Technology Choices
+- Ruby 3.2+ with dry-cli framework (Ruby First principle)
+- RSpec + Aruba for testing (no mocks - use real git repositories)
+- lib/ + exe/ structure (Simple Over Clever)
+- Focus on clear, maintainable code I can understand in six months
+
+## File Structure
+```
+lib/worktrees/           # Business logic modules
+├── cli.rb              # Main CLI application
+├── commands/           # Command classes (dry-cli)
+└── git_operations.rb   # Core business logic
+
+exe/worktrees           # CLI entry point
+spec/                   # Tests
+├── lib/                # Unit tests (RSpec)
+└── features/           # Integration tests (Aruba)
+```
+
+## My Development Approach
+
+### Test-Driven Development is Fundamental
+- Write failing test FIRST (Red-Green-Refactor cycle)
+- Make it pass with minimal code (Simple Over Clever)
+- Refactor only when tests are green (Write It Like I'll Maintain It)
+- Use real git repositories, never mocks (test real behavior)
+- Aruba for CLI integration tests, RSpec for unit tests
+
+### What I've Learned to Avoid
+- Service layers in CLI tools (unnecessary complexity)
+- Auto-initialization on require (causes side effects)
+- Global state mutations (pass data explicitly)
+- Clever abstractions I won't understand later
+
+### User Experience That Actually Helps
+- Clear error messages with actionable guidance
+- Consistent exit codes: 0=success, 1=error, 2=validation, 3=precondition
+- Support --help, --version, --format json/text on all commands
+- Show progress for long operations, handle Ctrl+C gracefully
+
+## What I Learned from the Bash Attempt
+This project started in bash but I discovered service layers don't belong in CLI tools. Ruby gives me:
+- Natural module system (no source conflicts)
+- Explicit initialization (no auto-magic side effects)
+- Clear testing boundaries with RSpec and Aruba
+- Code I can actually maintain
+
+The bash attempt taught me to Start Simple and choose tools that make me productive rather than fighting the language.
+
+## Current Implementation Status ✅
+
+### Planning Complete (2025-09-15)
+1. ✅ **Implementation plan** - Ruby CLI architecture designed
+2. ✅ **Task breakdown** - 35 TDD tasks ready (T001-T035 in specs/001-build-a-tool/tasks.md)
+3. **Ready for execution** - Start with T001 (project structure setup)
+
+### Recent Technology Decisions
+- **Git Integration**: Shell out to git commands (canonical interface, no library abstractions)
+- **Worktree Storage**: Global `~/.worktrees/` directory (separate from main repositories)
+- **Error Handling**: Structured exit codes (0=success, 1=general, 2=validation, 3=precondition)
+- **Configuration**: Command args override environment vars override config files
+- **Naming Convention**: Enforce NNN-kebab-feature format with validation
+- **Safety**: Conservative dirty-state policies (allow switch with warning, block unsafe removal)
+
+### Architecture Overview
+**Core Models**: FeatureWorktree, Repository, WorktreeManager, GitOperations
+**CLI Commands**: create, list, switch, remove, status (5 commands total)
+**Testing Strategy**: Aruba integration tests + RSpec unit tests (real git repos, no mocks)
+
+### Next Steps
+Execute tasks T001-T035 following Red-Green-Refactor methodology:
+- T001-T007: Project setup (Ruby structure, Gemfile, RSpec+Aruba config)
+- T008-T023: Test-first development (write failing tests)
+- T024-T035: Implementation (make tests pass)
+
+---
+*Based on Personal Principles v2.0.0*

data/.specify/memory/constitution-v1.0.1-formal.md

@@ -0,0 +1,90 @@
+# Worktrees Constitution
+
+## Core Principles
+
+### I. Technology Appropriateness
+Choose implementation language based on tool complexity and maintenance needs:
+- Simple scripts (<100 lines): Bash with minimal structure
+- Multi-command CLIs: Ruby (dry-cli), Python (Click), or Go (Cobra)
+- Service layers only when multiple consumers exist (API + CLI + Web)
+- Study similar successful tools (git, docker, rbenv) for patterns
+
+### II. Library-First Architecture
+Every feature must be implemented as a standalone library first:
+- Libraries must be self-contained and independently testable
+- CLI layer only handles argument parsing and output formatting
+- Business logic lives in libraries, not CLI layer
+- Clear separation between presentation and logic
+
+### III. Test-First Development (NON-NEGOTIABLE)
+Strict TDD Red-Green-Refactor cycle:
+- Tests written first and must fail before implementation
+- Ruby: RSpec for unit tests, Aruba for CLI integration tests
+- Use real dependencies (actual git repos, not mocks)
+- Test order: Contract → Integration → Unit
+- No implementation without failing test first
+
+### IV. Simplicity and Maintainability
+Start with simplest architecture that could possibly work:
+- Maximum 2 architectural layers for CLI tools (commands + libraries)
+- No design patterns without demonstrated need
+- Avoid premature abstraction
+- YAGNI (You Aren't Gonna Need It) principle applies
+- Refactor only when tests are green
+
+### V. Observability and Debugging
+All tools must be observable and debuggable:
+- Structured logging to stderr
+- Verbose mode (-v, --verbose) for debugging
+- Clear error messages with actionable next steps
+- JSON output for programmatic consumption
+
+### VI. Consistent User Experience
+All CLI tools in our ecosystem follow same patterns:
+- --help and --version flags on all commands
+- --format json/text for output control
+- Consistent exit codes (0=success, 1=general, 2=validation, 3=precondition)
+- Predictable command structure: noun-verb or verb-noun
+
+## Implementation Standards
+
+### For Ruby CLI Tools
+- Framework: dry-cli (consistent, well-tested, minimal magic)
+- Testing: RSpec + Aruba (standard in Ruby ecosystem)
+- Structure: lib/ for logic, exe/ for CLI entry point
+- Dependencies: Bundler for management, minimal external gems
+
+### Anti-Patterns to Avoid
+- Service layers in CLI tools (unnecessary abstraction)
+- Auto-initialization on require/source (causes side effects)
+- Mock-heavy tests (use real dependencies instead)
+- Deep inheritance hierarchies (composition over inheritance)
+- Global state mutations (pass data explicitly)
+
+## Development Workflow
+
+### Planning Process
+- Constitution defines technology choices and architectural principles
+- /plan command reads constitution to generate appropriate architecture
+- /tasks command reads plan to generate implementation tasks
+- Implementation follows tasks in TDD order
+
+### Quality Gates
+- All tests must pass before merging
+- Code review must verify constitutional compliance
+- No implementation without failing test first
+- Complexity must be justified in plan documentation
+
+## Governance
+- Constitution supersedes all design decisions
+- Amendments require documentation of rationale
+- Each project must reference this constitution in its README
+- Plan and task generation must comply with these principles
+
+**Version**: 1.0.1 | **Ratified**: 2025-01-15 | **Last Amended**: 2025-01-15
+
+## Amendment History
+- v1.0.1 (2025-01-15): Added template synchronization for Ruby CLI implementation
+  - Updated all templates to enforce constitutional principles
+  - Added Ruby-specific guidance and anti-patterns
+  - Synchronized command files across AI assistants

data/.specify/memory/constitution.md

@@ -0,0 +1,153 @@
+# Personal CLI Tools Development Principles
+
+## My Philosophy
+
+These are my core principles for building CLI tools that I actually want to use and maintain. They help me create tools that solve real problems without becoming problems themselves.
+
+---
+
+## Core Values
+
+### Ruby First
+**I choose Ruby because it makes me productive and happy.** Life's too short for verbose languages when I'm building personal tools. Ruby lets me focus on solving problems instead of fighting syntax.
+
+### Simple Over Clever
+**I prefer code I can understand in six months.** Clever one-liners are fun, but clear, readable code is a gift to my future self. When I need to debug at 2 AM, I'll thank myself for writing obvious code.
+
+### Libraries Over NIH Syndrome
+**I use proven libraries instead of reinventing wheels.** The Ruby ecosystem has solved most problems better than I could in an evening. My time is better spent on the unique parts of my problem.
+
+---
+
+## Building Principles
+
+### Start Simple, Grow Thoughtfully
+**Every tool starts as a simple script.** I only add complexity when I actually need it, not when I think I might. Features that aren't used are just maintenance burden.
+
+### Test-Driven Development is Fundamental
+**I write tests first, always.** TDD isn't academic ceremony - it's the fastest way to build CLI tools that actually work. Starting with tests forces me to think about the interface before getting lost in implementation details.
+
+**I test real behavior over mocked abstractions.** CLI tools live at integration boundaries - file systems, networks, databases. Testing against real dependencies catches the problems that actually break tools in production use.
+
+**I prioritize integration testing for CLI tools.** Unit tests verify logic; integration tests verify that my tool works in the real world with real files, real services, and real edge cases.
+
+### Fail Gracefully
+**Things go wrong, so I plan for it.** Good error messages help me debug faster. Reasonable defaults mean my tools work without fiddling. Validation catches problems early.
+
+---
+
+## Security Basics
+
+### Trust Nothing External
+**I validate all inputs and avoid shell injection.** Using `system('ls', user_input)` instead of `system("ls #{user_input}")` prevents nasty surprises. It's a simple habit that prevents major headaches.
+
+### Keep Secrets Secret
+**No passwords or API keys in code.** Environment variables or config files that stay out of git. My future self will thank me when I don't accidentally leak credentials.
+
+### Stay Updated
+**I keep dependencies current and use tools like `bundle audit`.** Security vulnerabilities are real, and staying patched is easier than dealing with breaches.
+
+---
+
+## User Experience (Even When the User Is Me)
+
+### Help That Actually Helps
+**My tools explain themselves clearly.** Good help text, clear error messages, and examples for common usage. If I can't remember how to use my own tool, it needs better help.
+
+### Consistent and Predictable
+**I follow CLI conventions people expect.** Standard flags, consistent output formats, and behavior that matches other tools. Fighting muscle memory is annoying.
+
+### Show Progress, Handle Interruption
+**Long operations show progress and handle Ctrl+C gracefully.** Nothing worse than wondering if a tool hung or is just slow.
+
+---
+
+## Quality Habits
+
+### Red-Green-Refactor is My Default Workflow
+**I start every feature with a failing test.** Write the test, watch it fail (red), make it pass with minimal code (green), then clean up (refactor). This cycle keeps me focused and prevents over-engineering.
+
+**I test the CLI interface, not just the internals.** Aruba tests how users actually interact with my tool. Unit tests for complex logic, Aruba scenarios for user workflows, test-containers for integration points.
+
+### Write It Like I'll Maintain It
+**Because I will.** Clear naming, reasonable comments, and structure that makes sense. Code is communication with my future self.
+
+### Measure What Matters
+**I know how my tools perform on real data.** If it's slow, I measure before optimizing. Premature optimization is the root of all evil, but so is ignoring real performance problems.
+
+### Document the Why
+**I capture decisions and trade-offs.** A simple README with examples and any non-obvious choices. Six months later, I'll have forgotten why I did things a certain way.
+
+### Test Coverage That Actually Matters
+**I focus on testing behavior that users care about.** High line coverage of trivial code is meaningless. Testing that my tool correctly handles malformed input and provides helpful errors is essential.
+
+**Integration tests catch the bugs that matter most.** CLI tools fail at boundaries - file handling, external APIs, system integration. I test these integration points with real dependencies, not simulation.
+
+---
+
+## Practical Guidelines
+
+### Testing Philosophy Guides Tool Choice
+**I choose testing tools that validate real CLI behavior.** Tools that test actual command execution and real dependencies reveal problems that matter. Mocking frameworks have their place, but CLI testing demands reality-based validation.
+
+**I test happy paths AND edge cases.** What happens when files don't exist? When network calls fail? When users pass malformed input? Edge case testing prevents 2 AM debugging sessions.
+
+### Configuration That Works
+**Command-line args override environment variables override config files.** This gives me flexibility without confusion. Reasonable defaults mean most tools work out of the box.
+
+### One Thing Well
+**Each tool has a clear, focused purpose.** If I'm tempted to add unrelated features, maybe I need a separate tool. Unix philosophy scales down to personal tools too.
+
+### Build for Change
+**I assume requirements will evolve.** Modular design and clear interfaces make adaptation easier. Today's quick script might become tomorrow's essential tool.
+
+---
+
+## Personal Development Rules
+
+### Learn by Building
+**I try new patterns and libraries in personal tools.** It's a safe place to experiment before using techniques in important projects. Mistakes here are learning opportunities.
+
+### Share What Works
+**If I build something useful, I consider sharing it.** Open source gives back to the community that provides the libraries I depend on. Plus, external users find bugs I miss.
+
+### Evolve Standards
+**These principles change as I learn.** What works for me now might not work forever. I update my approach based on what I learn from successes and failures.
+
+---
+
+## Implementation Freedom
+
+**These are principles, not rules.** They guide decisions but don't replace thinking. Sometimes the right choice breaks a principle - that's fine if I understand why.
+
+**Context matters.** A quick one-off script has different needs than a tool I'll use daily. I scale my effort to match the tool's importance and lifespan.
+
+**Done is better than perfect.** These principles help me build better tools, not perfect ones. The goal is solving problems, not following rules.
+
+---
+
+## Why This Matters
+
+Building personal tools with TDD and sound principles means:
+- **Faster development** - tests catch mistakes immediately instead of during late-night debugging sessions
+- **Fearless refactoring** - comprehensive tests enable confident code improvement
+- **Real confidence** - tools tested against actual behavior work reliably in real conditions
+- **Better learning** - TDD develops design skills that transfer to every project
+- **Genuine productivity** - tools that work correctly under real conditions
+
+**TDD for personal tools isn't overkill - it's self-respect.** My time is valuable, and spending it debugging preventable issues is wasteful. Testing first means tools work correctly from day one.
+
+**Testing real behavior prevents surprises.** CLI tools live at integration boundaries. Testing with real files, real services, and real edge cases catches the problems that actually matter.
+
+Good habits in small projects build the muscle memory for larger ones. Plus, life's more enjoyable when my tools work reliably and I can trust them completely.
+
+---
+
+**Version**: 2.0.0 | **Adopted**: 2025-01-15
+
+## Version History
+- v2.0.0 (2025-01-15): Replaced formal constitution with personal principles
+  - Shifted from enterprise patterns to personal development philosophy
+  - Simplified language and removed unnecessary formality
+  - Focused on Ruby-first, TDD, and practical simplicity
+- v1.0.1 (2025-01-15): [Archived] Formal constitution with enterprise patterns

data/.specify/memory/constitution_update_checklist.md

@@ -0,0 +1,88 @@
+# Constitution Update Checklist
+
+When amending the constitution (`/memory/constitution.md`), ensure all dependent documents are updated to maintain consistency.
+
+## Templates to Update
+
+### When adding/modifying ANY article:
+- [ ] `/templates/plan-template.md` - Update Constitution Check section
+- [ ] `/templates/spec-template.md` - Update if requirements/scope affected
+- [ ] `/templates/tasks-template.md` - Update if new task types needed
+- [ ] `/.claude/commands/plan.md` - Update if planning process changes
+- [ ] `/.claude/commands/tasks.md` - Update if task generation affected
+- [ ] `/CLAUDE.md` - Update runtime development guidelines
+- [ ] `/.cursor/commands/plan.md` - Update if planning process changes
+- [ ] `/.cursor/commands/tasks.md` - Update if task generation affected
+- [ ] `/.cursor/rules` - Update runtime development guidelines
+
+### Article-specific updates:
+
+#### Article I (Library-First):
+- [ ] Ensure templates emphasize library creation
+- [ ] Update CLI command examples
+- [ ] Add llms.txt documentation requirements
+
+#### Article II (CLI Interface):
+- [ ] Update CLI flag requirements in templates
+- [ ] Add text I/O protocol reminders
+
+#### Article III (Test-First):
+- [ ] Update test order in all templates
+- [ ] Emphasize TDD requirements
+- [ ] Add test approval gates
+
+#### Article IV (Integration Testing):
+- [ ] List integration test triggers
+- [ ] Update test type priorities
+- [ ] Add real dependency requirements
+
+#### Article V (Observability):
+- [ ] Add logging requirements to templates
+- [ ] Include multi-tier log streaming
+- [ ] Update performance monitoring sections
+
+#### Article VI (Versioning):
+- [ ] Add version increment reminders
+- [ ] Include breaking change procedures
+- [ ] Update migration requirements
+
+#### Article VII (Simplicity):
+- [ ] Update project count limits
+- [ ] Add pattern prohibition examples
+- [ ] Include YAGNI reminders
+
+## Validation Steps
+
+1. **Before committing constitution changes:**
+   - [ ] All templates reference new requirements
+   - [ ] Examples updated to match new rules
+   - [ ] No contradictions between documents
+
+2. **After updating templates:**
+   - [ ] Run through a sample implementation plan
+   - [ ] Verify all constitution requirements addressed
+   - [ ] Check that templates are self-contained (readable without constitution)
+
+3. **Version tracking:**
+   - [ ] Update constitution version number
+   - [ ] Note version in template footers
+   - [ ] Add amendment to constitution history
+
+## Common Misses
+
+Watch for these often-forgotten updates:
+- Command documentation (`/commands/*.md`)
+- Checklist items in templates
+- Example code/commands
+- Domain-specific variations (web vs mobile vs CLI)
+- Cross-references between documents
+
+## Template Sync Status
+
+Last sync check: 2025-07-16
+- Constitution version: 2.1.1
+- Templates aligned: ❌ (missing versioning, observability details)
+
+---
+
+*This checklist ensures the constitution's principles are consistently applied across all project documentation.*