Git commit after every implementation or documentation

## Planning Repo Access

This repo uses Strategy 3 multi-repo planning. The planning repo is available at `_planning/`.

- System PRD: `_planning/docs/planning-artifacts/2-planning/system-prd.md`
- Service PRD: `_planning/docs/services/textiq-doc-extraction/prd.md`
- Architecture: `_planning/docs/services/textiq-doc-extraction/architecture.md`
- System integration: `_planning/docs/planning-artifacts/3-solutioning/system-integration-map.md`
- ID registry: `_planning/docs/planning-artifacts/3-solutioning/id-registry.csv`

**Do NOT edit files in `_planning/` from this repo.** Planning changes go through textiq-blueprint.

# Project CLAUDE.md — Jira + BMAD Integration Guide

## Jira Skill (`.jira/`)

All Jira operations go through the CLI. **Never call the Jira REST API directly.**

```
uv run --project .jira .jira/jira_cli.py <command> [args]
```

### Quick Reference

| Action | Command |
|--------|---------|
| Create ticket | `create --title "..." [--type Story\|Task\|Bug\|Epic] [--assignee USER] [--component NAME] [--sprint NAME] [--epic KEY] [--due-date YYYY-MM-DD] [--story-points N]` |
| Update ticket | `update TICKET-ID [--title "..." --assignee USER --component NAME --sprint NAME --story-points N --product NAME]` |
| Get details | `get TICKET-ID` |
| Search | `search "keywords or JQL" [--max 15]` |
| Transition status | `transition TICKET-ID "STATUS" [--field key=value]` |
| Log work | `log-work TICKET-ID --time "2h" [--comment "..." --date YYYY-MM-DD]` |
| Comment | `comment TICKET-ID "message"` |
| Add subtask | `add-subtask PARENT-ID --title "..." [--assignee USER --due-date YYYY-MM-DD --story-points N]` |
| My tasks | `my-tasks [--assignee USERNAME]` |
| Show config | `config` |
| Setup/refresh | `setup all --save` |

### Workflow Automation Rules

**When starting work on a task:**
1. Transition the ticket to "In Progress": `transition TICKET-ID "In Progress"`
2. If needed, log time at the end: `log-work TICKET-ID --time "2h" --comment "description"`

**When submitting for review/testing:**
1. Transition to appropriate status: `transition TICKET-ID "In Review"` or `"Testing"`
2. Add a comment summarizing changes: `comment TICKET-ID "Implemented X, Y, Z"`

**When completing a task:**
1. Transition to "Done": `transition TICKET-ID "Done" [--field customfield_XXXXX=today]`
   - Some Jira instances require extra fields (e.g., Closed Date). Check `transition_fields` in `agent_config.json` or run `setup transitions TICKET-ID` to discover required fields.

**Status change shorthand — if the user says:**
- "start TICKET-ID" → transition to "In Progress"
- "review TICKET-ID" → transition to "In Review"
- "testing TICKET-ID" → transition to "Testing"
- "done TICKET-ID" → transition to "Done"
- "reopen TICKET-ID" → transition to "Open" or "To Do"

### Important Rules

- **Always confirm before creating or modifying tickets.**
- Output is JSON — parse it and present readable summaries.
- Assignee names are case-sensitive usernames from config (run `config` to check).
- For status changes, use `transition` (not `update --status`).
- For Jira descriptions, use wiki markup: `{panel}`, `*bold*`, `_italic_`, `h3.` headers.
- Show ticket URL after create/update: `{jira_server}/browse/TICKET-KEY`

## BMAD Workflow → Jira Integration

When BMAD workflows produce artifacts (epics, stories, specs), sync them to Jira:

### Auto-create from BMAD output

When the `create-epics-and-stories` or similar workflow produces epic/story markdown files:

1. **Scan output files** for epic and story definitions
2. **Create Epic first**: `create --type Epic --title "Epic Name" --description "..."`
3. **Create Stories under the Epic**: `create --type Story --title "Story Name" --epic EPIC-KEY --description "..."`
4. **Create Subtasks if defined**: `add-subtask STORY-KEY --title "Subtask Name"`
5. **Write back `jira_id`** to the source markdown file so tickets aren't recreated

### Recognizing BMAD artifacts

- Epic files: typically in `docs/epics/` or `_bmad-output/`, contain `## Epic:` headers
- Story files: in `docs/stories/` or similar, contain `## Story:`, acceptance criteria, tasks
- If a file already has `jira_id: PROJ-123`, skip creation — it's already synced

### Bulk creation flow

When creating 5+ tickets:
1. List all tickets to be created with title, type, and assignee
2. Ask user: "Create these N tickets in Jira?"
3. On confirmation, create sequentially with 2s delay between calls (avoid 429 rate limits)
4. Show summary table at the end

## Troubleshooting

- **ModuleNotFoundError**: Run `cd .jira && uv sync`
- **429 Rate Limit**: The CLI handles retries, but for bulk ops add delays between calls
- **Transition fails**: Run `setup transitions TICKET-ID` to discover required fields, then configure in `agent_config.json` under `transition_fields`
- **Config empty**: Run `setup all --save` to auto-populate from Jira