--- name: ticket-manager description: SQLite-based ticket tracking for structured development workflows. Use this skill when the user asks to initialize a ticket database, import requirements, list tickets, get the next ticket to work on, mark tickets as done, or check ticket status. Essential for managing epics, user stories, and acceptance criteria. --- # Ticket Manager Skill **For Claude Code AI Assistant** This skill provides SQLite-based ticket tracking for structured development workflows. ## Purpose The ticket-manager skill enables systematic ticket-based development by: - Storing tickets (epics and stories) in a local SQLite database - Tracking ticket status (TO_DO, IN_PROGRESS, DONE, SHELVED) - Managing acceptance criteria and technical notes - Providing workflow commands for ticket progression ## Database Location - Default: `./.artifex/tickets.db` in the project's Artifex directory - Can be overridden with `TICKET_DB` environment variable ## Available Commands ### 1. Initialize Database ```bash ticket-manager.sh init ``` Creates a new `.artifex/tickets.db` file with the schema. Use `init force` to recreate an existing database. **When to use**: At project start, before importing requirements ### 2. Import Requirements ```bash ticket-manager.sh import [--no-validate] requirements.json ``` Imports tickets from a requirements JSON file. For each story, both `acceptance_criteria` and `technical_notes` arrays are persisted into their respective tables; stories without a `technical_notes` field (or with an empty array) are imported cleanly with no warning, preserving backward compatibility with pre-10.8 requirements files. By default, each story is validated before insertion: acceptance criteria must be in Gherkin form (`Given ... When ... Then ...`), every story must have a non-empty title and id, and empty descriptions emit an informational note. Warnings and errors are written to stderr; a single summary line (`imported N epics, M stories, K technical notes, E errors, W warnings`) is written to stdout. Stories with errors are skipped; warnings do not block insertion. Pass `--no-validate` to disable all validation (useful when migrating a project whose tickets predate the Gherkin convention). The expected JSON structure: ```json { "epics": [ { "id": "1", "title": "Epic Title", "description": "Epic description", "user_stories": [ { "id": "1.1", "title": "Story Title", "description": "Story description", "complexity": "Medium", "implementation_order": 1, "acceptance_criteria": [ "Given... When... Then..." ], "technical_notes": [ "Optional implementation hint or constraint" ] } ] } ] } ``` **When to use**: After database initialization, to load project tickets ### 3. Get Next Ticket ```bash ticket-manager.sh next ``` Returns the next TO_DO story ordered by implementation_order and ID. **Output includes**: - Story ID, title, epic, complexity - Full description - Acceptance criteria **When to use**: When ready to start implementing a new ticket ### 4. Update Ticket Status ```bash ticket-manager.sh update [note] ``` Valid statuses: `TO_DO`, `IN_PROGRESS`, `DONE`, `SHELVED` `SHELVED` is a terminal state for deliberately-parked tickets. Shelved stories: - Are excluded from `next-ticket` selection (they won't be picked up as the next unit of work) - Are excluded from epic progress denominators (a shelved ticket doesn't drag a phase's completion percentage down forever) - Still appear in `show ` and `status` summaries so you can see why they were parked - Use the tool's regular `update SHELVED ""` path with a note explaining the trigger that would revive them **Examples**: ```bash # Mark ticket as in progress ticket-manager.sh update 2.4 IN_PROGRESS "Starting implementation" # Mark ticket as done ticket-manager.sh update 2.4 DONE "Completed with tests" ``` **When to use**: - When starting work (TO_DO → IN_PROGRESS) - When completing work (IN_PROGRESS → DONE) - When reverting status changes ### 5. Mark Ticket Done ```bash ticket-manager.sh done [note] ``` Shortcut for updating status to DONE. **Example**: ```bash ticket-manager.sh done 2.4 "Implemented with 95% test coverage" ``` **When to use**: At the end of ticket implementation workflow (Step 15-16) ### 6. Show Ticket Details ```bash ticket-manager.sh show ``` Displays complete ticket information: - Title, epic, status, complexity - Description - Acceptance criteria - Technical notes - Implementation notes - Status history with timestamps **When to use**: When you need complete context about a specific ticket ### 7. Show Overall Status ```bash ticket-manager.sh status ``` Shows summary statistics: - Total stories count - Breakdown by status (TO_DO, IN_PROGRESS, DONE, SHELVED) with percentages - Progress per epic **When to use**: To check project progress, report status ### 8. Export to JSON ```bash ticket-manager.sh export [output.json] ``` Exports all tickets back to JSON format (default: `requirements-export.json`). **When to use**: - Creating backups - Sharing ticket state - Migrating to other systems ## Database Schema ### Tables 1. **epics** - Epic-level tickets - id (TEXT PRIMARY KEY) - title (TEXT) - description (TEXT) - created_at, updated_at (TIMESTAMP) 2. **stories** - User story tickets - id (TEXT PRIMARY KEY) - epic_id (TEXT, foreign key) - title (TEXT) - description (TEXT) - status (TEXT: TO_DO, IN_PROGRESS, DONE, SHELVED) - complexity (TEXT: Low, Medium, High, Very High) - implementation_order (INTEGER) - notes (TEXT) - created_at, updated_at (TIMESTAMP) 3. **acceptance_criteria** - Story acceptance criteria - id (INTEGER PRIMARY KEY) - story_id (TEXT, foreign key) - criterion (TEXT) - created_at (TIMESTAMP) 4. **technical_notes** - Technical implementation notes - id (INTEGER PRIMARY KEY) - story_id (TEXT, foreign key) - note (TEXT) - created_at (TIMESTAMP) 5. **status_history** - Audit trail of status changes - id (INTEGER PRIMARY KEY) - story_id (TEXT, foreign key) - old_status (TEXT) - new_status (TEXT) - note (TEXT) - changed_at (TIMESTAMP) ## Typical Workflow 1. **Project Setup**: ```bash ticket-manager.sh init ticket-manager.sh import requirements.json ticket-manager.sh status # Verify import ``` 2. **Start New Ticket**: ```bash ticket-manager.sh next # Get ticket to work on ticket-manager.sh update IN_PROGRESS "Starting work" ``` 3. **During Implementation**: ```bash ticket-manager.sh show # Reference details as needed ``` 4. **Complete Ticket**: ```bash ticket-manager.sh done "Implementation note" ticket-manager.sh status # Check progress ``` 5. **Export/Backup**: ```bash ticket-manager.sh export backup.json ``` ## Integration with ticket-implementation Agent The ticket-manager skill is designed to work seamlessly with the ticket-implementation agent workflow: - **Step 1** (Validation): Use `status` to verify clean state - **Step 2** (Select Ticket): Use `next` to get ticket ID - **Step 2** (Mark In Progress): Use `update IN_PROGRESS` - **Step 3-14** (Implementation): Reference `show ` for context - **Step 15** (Mark Done): Use `done ` with implementation notes - **Step 16** (Progress Check): Use `status` to see overall progress ## Error Handling The skill exits with non-zero status on errors: - Database not initialized - Ticket not found - Invalid status value - Missing required dependencies (sqlite3, jq) Always check for error messages before proceeding. ## Dependencies - **Required**: sqlite3, bash 4.0+ - **Recommended**: jq (for JSON import/export) ## Best Practices 1. **Always initialize first**: Run `init` before any other commands 2. **Import once**: Import requirements at project start, manage via commands thereafter 3. **Track status changes**: Include meaningful notes when updating status 4. **Regular exports**: Periodically export to JSON for backup 5. **Check status**: Use `status` command to monitor overall progress 6. **Reference details**: Use `show` to get complete ticket context during implementation ## Version 1.0.0