Spec Kitty

---

description: "Work package task list for Auto-protect Agent Directories implementation"

---

Path: kitty-specs/003-auto-protect-agent/tasks.md

Work Packages: Auto-protect Agent Directories

Inputs: Design documents from /kitty-specs/003-auto-protect-agent/ Prerequisites: plan.md (required), spec.md (user stories), research.md, data-model.md, contracts/, quickstart.md

Organization: Fine-grained subtasks (Txxx) roll up into work packages (WPxx). Each work package must be independently deliverable and testable.

Prompt Files: Each work package references a matching prompt file in /tasks/planned/ generated by /spec-kitty.tasks.

Subtask Format: [Txxx] [P?] Description

• [P] indicates the subtask can proceed in parallel (different files/components).
• Include precise file paths or modules.

Path Conventions

• Single project: src/, tests/
• Adjust paths to match the implementation plan.

---

Work Package WP01: Create GitignoreManager Module (Priority: P0)

Goal: Create the new GitignoreManager class with core functionality and agent registry. Independent Test: GitignoreManager can be imported and instantiated with a project path. Prompt: /tasks/WP01-create-gitignore-manager.md

Included Subtasks

• □ T001 Create src/specify_cli/gitignore_manager.py file with class skeleton
• □ T002 Define AGENT_DIRECTORIES registry with all 12 agent directories
• □ T003 Implement GitignoreManager.__init__ with project path validation
• □ T004 Create data classes: AgentDirectory, ProtectionResult
• □ T005 [P] Migrate ensure_gitignore_entries logic into GitignoreManager.ensure_entries
• □ T006 [P] Add line ending detection and preservation logic
• □ T007 Implement get_agent_directories class method

Implementation Notes

• Start with class structure and data models
• Migrate existing logic from ensure_gitignore_entries function
• Ensure proper path handling for cross-platform support

Parallel Opportunities

• T005 and T006 can proceed in parallel once class structure exists

Dependencies

• None (starting package)

Risks & Mitigations

• Path handling differences across OS → Use pathlib exclusively
• Line ending preservation → Detect and maintain existing style

---

Work Package WP02: Core Protection Methods (Priority: P1) 🎯 MVP

Goal: Implement the core protection methods that add agent directories to .gitignore. Independent Test: Can successfully protect all agent directories in a test project. Prompt: /tasks/WP02-core-protection-methods.md

Included Subtasks

• □ T008 Implement protect_all_agents() method to add all directories
• □ T009 Implement protect_selected_agents(agents) method for specific agents
• □ T010 Add duplicate detection logic to avoid repeated entries
• □ T011 Implement marker comment system for auto-managed sections
• □ T012 Add .gitignore file creation for non-existent files
• □ T013 Implement result reporting via ProtectionResult
• □ T014 [P] Add special handling for .github/ directory with warning comment
• □ T015 [P] Add file permission error handling with user guidance

Implementation Notes

• Build on T005's migrated ensure_entries logic
• Ensure atomic file operations (read-modify-write)
• Special case: .github/ needs warning about dual use

Parallel Opportunities

• T014 and T015 can be done in parallel after core logic

Dependencies

• Depends on WP01

Risks & Mitigations

• File corruption during write → Write to temp file first, then rename
• Permission errors → Catch and provide clear instructions

---

Work Package WP03: Replace Existing Implementation (Priority: P1) 🎯 MVP

Goal: Replace the old handle_codex_security and integrate GitignoreManager into init flow. Independent Test: Running spec-kitty init successfully protects all agent directories. Prompt: /tasks/WP03-replace-existing-implementation.md

Included Subtasks

• □ T016 Import GitignoreManager in src/specify_cli/__init__.py
• □ T017 Replace handle_codex_security call with GitignoreManager.protect_all_agents
• □ T018 Update console output to show all protected directories
• □ T019 Remove handle_codex_security function entirely
• □ T020 Remove old ensure_gitignore_entries function after verification
• □ T021 Update any remaining references to old functions
• □ T022 Verify init flow works end-to-end with new implementation

Implementation Notes

• Make changes incrementally, testing after each step
• Keep console output format consistent with existing style
• Ensure all agent directories are protected, not just selected ones

Parallel Opportunities

• Sequential work required for safe refactoring

Dependencies

• Depends on WP02

Risks & Mitigations

• Breaking init flow → Test thoroughly before removing old functions
• Missing references → Search entire codebase for function usage

---

Work Package WP04: Testing Infrastructure (Priority: P2)

Goal: Create comprehensive test coverage for GitignoreManager. Independent Test: All tests pass with >90% coverage of new module. Prompt: /tasks/WP04-testing-infrastructure.md

Included Subtasks

• □ T023 [P] Create tests/unit/test_gitignore_manager.py with test class structure
• □ T024 [P] Write unit tests for GitignoreManager.__init__ and validation
• □ T025 [P] Write unit tests for protect_all_agents method
• □ T026 [P] Write unit tests for protect_selected_agents method
• □ T027 [P] Write unit tests for duplicate detection logic
• □ T028 [P] Write unit tests for line ending preservation
• □ T029 [P] Write unit tests for error handling scenarios
• □ T030 Update tests/test_gitignore_management.py for new implementation
• □ T031 Add integration tests for complete init flow
• □ T032 Add edge case tests (permissions, corrupt files, special characters)

Implementation Notes

• Use pytest fixtures for test file system setup
• Mock file operations for unit tests
• Use real files for integration tests

Parallel Opportunities

• T023-T029 can all proceed in parallel (different test methods)

Dependencies

• Depends on WP02

Risks & Mitigations

• Test flakiness → Use temp directories, clean up properly
• Platform differences → Test on multiple OS in CI

---

Work Package WP05: Documentation and Polish (Priority: P3)

Goal: Update documentation and finalize the feature. Independent Test: Documentation is accurate and examples work as described. Prompt: /tasks/WP05-documentation-polish.md

Included Subtasks

• □ T033 Update CHANGELOG.md with feature description
• □ T034 [P] Update CLI help text if needed
• □ T035 [P] Add docstrings to all GitignoreManager methods
• □ T036 [P] Update any existing documentation about gitignore handling
• □ T037 Verify quickstart.md examples work correctly
• □ T038 Code cleanup and formatting consistency
• □ T039 Performance verification (<1 second execution)
• □ T040 Final manual testing on all platforms

Implementation Notes

• Follow existing documentation style
• Ensure examples in quickstart.md are runnable
• Check performance with large .gitignore files

Parallel Opportunities

• T034, T035, T036 can proceed in parallel (different files)

Dependencies

• Depends on WP03

Risks & Mitigations

• Documentation drift → Test all examples before finalizing
• Performance regression → Profile if needed

---

Dependency & Execution Summary

• Sequence: WP01 → WP02 → WP03 → (WP04 parallel) → WP05
• Parallelization: WP04 (testing) can run alongside WP03 completion
• MVP Scope: WP01 + WP02 + WP03 constitute the minimal working feature

---

Subtask Index (Reference)

Subtask ID	Summary	Work Package	Priority	Parallel?
T001	Create gitignore_manager.py skeleton	WP01	P0	No
T002	Define AGENT_DIRECTORIES registry	WP01	P0	No
T003	Implement __init__ method	WP01	P0	No
T004	Create data classes	WP01	P0	No
T005	Migrate ensure_gitignore_entries	WP01	P0	Yes
T006	Add line ending detection	WP01	P0	Yes
T007	Implement get_agent_directories	WP01	P0	No
T008	Implement protect_all_agents	WP02	P1	No
T009	Implement protect_selected_agents	WP02	P1	No
T010	Add duplicate detection	WP02	P1	No
T011	Implement marker comments	WP02	P1	No
T012	Add .gitignore creation	WP02	P1	No
T013	Implement result reporting	WP02	P1	No
T014	Special .github/ handling	WP02	P1	Yes
T015	Permission error handling	WP02	P1	Yes
T016	Import GitignoreManager	WP03	P1	No
T017	Replace handle_codex_security call	WP03	P1	No
T018	Update console output	WP03	P1	No
T019	Remove handle_codex_security	WP03	P1	No
T020	Remove ensure_gitignore_entries	WP03	P1	No
T021	Update remaining references	WP03	P1	No
T022	Verify init flow end-to-end	WP03	P1	No
T023	Create test file structure	WP04	P2	Yes
T024	Test __init__ validation	WP04	P2	Yes
T025	Test protect_all_agents	WP04	P2	Yes
T026	Test protect_selected_agents	WP04	P2	Yes
T027	Test duplicate detection	WP04	P2	Yes
T028	Test line ending preservation	WP04	P2	Yes
T029	Test error handling	WP04	P2	Yes
T030	Update existing tests	WP04	P2	No
T031	Add integration tests	WP04	P2	No
T032	Add edge case tests	WP04	P2	No
T033	Update CHANGELOG.md	WP05	P3	No
T034	Update CLI help text	WP05	P3	Yes
T035	Add docstrings	WP05	P3	Yes
T036	Update documentation	WP05	P3	Yes
T037	Verify quickstart examples	WP05	P3	No
T038	Code cleanup	WP05	P3	No
T039	Performance verification	WP05	P3	No
T040	Final platform testing	WP05	P3	No

---

> Work packages generated for Auto-protect Agent Directories feature implementation.

<!-- status-model:start -->

Canonical Status (Generated)

<!-- status-model:end -->

• WP01: done
• WP02: done
• WP03: done
• WP04: done
• WP05: done