DOGCAT WORKFLOW GUIDE ## Rules Run `dcat prime` 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 - Children of a parent $ dcat ready - Ready to work (no blockers) $ dcat blocked - All blocked issues Use --namespace or --all-namespaces to filter. 3. Update: $ dcat update --status in_progress 4. Close: $ dcat close --reason "Fixed" ## Essential Commands dcat create - 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