naiv-qr/AGENTS.md

DOGCAT WORKFLOW GUIDE

## Rules
  Run `dcat prime --opinionated` after compaction, clear, or new session
  BEFORE writing any code for a new bug, feature, or change:
  ask the user if you should create an issue first. No exceptions
  for 'small' tasks — the rule exists for traceability, not
  because the task is complex.
  When creating or updating issues, write them so a fresh agent
  with no prior context can pick them up. Include the why,
  relevant file paths, error messages, and acceptance criteria —
  don't assume shared knowledge.
  When creating issues, set appropriate labels using `--labels`
  based on the issue content (e.g. `cli`, `tui`, `api`, `docs`,
  `testing`, `refactor`, `ux`, `performance`, etc.).
  Do NOT batch-mark an entire backlog as `in_progress` upfront.
  Mark each issue `in_progress` right when you start working on it.
  When running multiple `dcat` commands, make separate parallel
  tool calls instead of chaining with `&&` and `echo` separators.
  Before setting in_review: verify your work and cite actual output.

## Quick Start

Allowed issue types, priorities, and statuses:
  Types: bug, chore, epic, feature, question, story, task
  Priorities: 0 (Critical), 1 (High), 2 (Medium, default), 3 (Low), 4 (Minimal)
  Statuses: draft, open, in_progress, in_review, blocked, deferred, closed

`dcat create` and `dcat update` both support --title, --description,
--priority, --acceptance, --notes, --labels, --parent, --manual,
--design, --external-ref, --depends-on, --blocks, --duplicate-of, --editor

1. Create: $ dcat create "Title" --type bug --priority 1 -d "Description"

2. List issues:
   $ dcat list                  - All open issues
   $ dcat list <parent_id>     - Children of a parent
   $ dcat ready                - Ready to work (no blockers)
   $ dcat blocked              - All blocked issues
   Use --namespace <ns> or --all-namespaces to filter.

3. Update: $ dcat update <id> --status in_progress

4. Close:  $ dcat close <id> --reason "Fixed"

## Essential Commands

  dcat create <title>                        - Create a new issue
  dcat create <title> --depends-on <id>      - Create with dependency
  dcat create <title> --blocks <id>          - Create issue that blocks another
  dcat update <id> --depends-on <other_id>   - Add dependency
  dcat update <id> --blocks <other_id>       - Mark as blocking another
  dcat update <id> --remove-depends-on <id>  - Remove a dependency
  dcat update <id> --remove-blocks <id>      - Remove a blocks relationship
  dcat show <id> [<id> ...]                  - View one or more issues
  dcat random                                - Show one random issue (same filters)
  dcat search <query>                        - Search issues (supports --type filter)
  dcat close <id>                            - Mark issue as closed
  dcat reopen <id>                           - Reopen a closed issue
  dcat delete <id>                           - Delete an issue (tombstone)
  dcat pr                                    - Show in-progress/in-review issues
  dcat history                               - Show change history timeline
  dcat history -i <id>                       - History for a specific issue
  dcat diff                                  - Show uncommitted issue changes
  dcat label <id> add -l <label>             - Add a label
  dcat label <id> remove -l <label>          - Remove a label
  dcat link <id> add --related <other_id>    - Link two issues
  dcat link <id> remove --related <other_id> - Remove a link
  dcat graph [<id>]                           - Visualize dependency graph
  dcat comment <id> add -t "text"            - Add a comment
  dcat comment <id> list                     - List comments
  dcat comment <id> delete -c <comment_id>   - Delete a comment

## Parent-Child vs Dependencies

Parent-child is **organizational** (grouping), not **blocking**.
Children appear in `dcat ready` even when parent is open.

- Can start independently? → parent-child only
- Must parent complete first? → add dependency:
    dcat update <child_id> --depends-on <parent_id>

## Breaking Down Large Tasks

For large/complex tasks, create an epic with child tasks:

  $ dcat create "Redesign auth system" --type epic
  $ dcat create "Add OAuth provider" --type task --parent <epic_id>
  $ dcat create "Migrate sessions" --type task --parent <epic_id>
  $ dcat update <task_id> --depends-on <other_task_id>  # if ordering matters

Prefer multiple small, focused issues over one large issue.
If unsure about scope, ask the user before creating the breakdown.

## Agent Integration

`--agent-only` filters in list/ready exclude issues marked `--manual`:
  dcat ready --agent-only   # autonomous-workable
  dcat list --agent-only    # autonomous-workable

Mark `--manual` when a step requires a human in the loop —
credentials, deploys, hardware, visual confirmation, GUI keystrokes:
  dcat update <id> --manual

`--manual` means HITL, not "agent skips". The filter exists so
autonomous-batch runs (no human present to consult) move past these.
When you are in session with a user, drive manual issues like any
other: do the analysis, frame the hypothesis, hand the user one
concrete action at a time, take their result, iterate. The human is
your hands for steps you can't reach; the rest is still your job.

## Comment-based filtering

List-style commands (list, ready, blocked, pr, snoozed, search, stale,
recently-closed, recently-added, etc.) accept --has-comments and
--without-comments to filter by comment presence. The two flags are
mutually exclusive and combine with other filters.

  dcat list --has-comments         # only issues with at least one comment
  dcat list --without-comments     # only issues with no comments
  dcat ready --agent-only --has-comments

## Status Workflow

  draft -> open -> in_progress -> in_review -> closed

## Questions

Questions (type: question) track questions needing answers, not tasks to work on.

## Labels

Freeform tags shown in list/show, filter with --label.

## Snooze

Temporarily hide issues from list/ready without changing status:
  dcat snooze <id> 7d             - Snooze for 7 days
  dcat snooze <id> 2w             - Snooze for 2 weeks
  dcat snooze <id> --until 2026-04-01  - Snooze until a date
  dcat unsnooze <id>              - Remove snooze early
  dcat snoozed                    - List currently snoozed issues
  dcat list --include-snoozed     - Show snoozed issues in list

Snoozed issues keep their original status and reappear automatically
when the snooze period expires.


## dogcat health check

  ✓ Inside a git repository
  ✓ .gitignore covers .issues.lock
  ✓ .dogcats/ is shared with team via git
  ✓ JSONL merge driver is configured
  ✓ .gitattributes has JSONL merge driver entry