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

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

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:

{
  "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

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

ticket-manager.sh update <ticket_id> <status> [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 <id> and status summaries so you can see why they were parked
• Use the tool's regular update <id> SHELVED "<reason>" path with a note explaining the trigger that would revive them

Examples:

# 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

ticket-manager.sh done <ticket_id> [note]

Shortcut for updating status to DONE.

Example:

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

ticket-manager.sh show <ticket_id>

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

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

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:

   ticket-manager.sh init
   ticket-manager.sh import requirements.json
   ticket-manager.sh status  # Verify import
   

2. Start New Ticket:

   ticket-manager.sh next  # Get ticket to work on
   ticket-manager.sh update <ID> IN_PROGRESS "Starting work"
   

3. During Implementation:

   ticket-manager.sh show <ID>  # Reference details as needed
   

4. Complete Ticket:

   ticket-manager.sh done <ID> "Implementation note"
   ticket-manager.sh status  # Check progress
   

5. Export/Backup:

   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 <ID> IN_PROGRESS
• Step 3-14 (Implementation): Reference show <ID> for context
• Step 15 (Mark Done): Use done <ID> 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