task

---
name: task
description: >-
  Manage this repository's GitHub Issues work items with the issue-first workflow. Use when creating,
  searching, claiming, planning, updating, or finishing a maintainer task in urikanonov/ai-marketplace,
  starting work (worktree + branch stamp), keeping a heartbeat on an in-progress issue, or finding
  abandoned/stale work to take over. Wraps `gh` with the repo conventions (the `task` label,
  plain-ASCII bodies, the Task issue-form sections, and the In Progress status). Trigger on: task,
  issue, work item, backlog, track work, file an issue, claim, start work, worktree, branch stamp,
  heartbeat, stale issue, abandoned work, acceptance criteria, plan, gh issue.
---

# Task (issue-first work items)

This repo tracks work as GitHub Issues (see AGENTS.md, "GitHub Issues workflow"). An issue exists the
moment you create it, decoupled from git, so work is never lost in a discarded worktree or abandoned PR.
Use the `scripts/task.py` wrapper so the repo conventions (the `task` label, plain ASCII, the Task
issue-form sections, and the `status: in progress` label) are applied for you instead of retyping `gh`
flags. It also stamps the worktree branch on the issue and runs a heartbeat, so the maintainer can tell
which in-progress issues are actively being worked on and which are abandoned (and resumable).

## When to use

Use this skill before writing any code (issue-first is a non-negotiable), and whenever a follow-up
surfaces mid-session, so nothing lives only in the chat transcript. Use `start`/`claim` to stamp the
branch, `heartbeat --watch` to keep the issue marked live for your whole session, and `stale` to find
in-progress issues nobody is working on.

## Commands

Run from the repo root with a `gh` that is authenticated to the `urikanonov` account.

```bash
# 1. Search first (consolidate rather than duplicate); --all includes closed history.
python scripts/task.py search "comment panel width" --all

# 2. Create a task issue (labeled `task`); acceptance items become checkboxes.
python scripts/task.py new "UI: enforce legible comment panel width" \
  -d "Keep the side panel from clipping action labels." \
  --ac "Labels stay legible at the minimum width" \
  --ac "Search placeholder is fully visible" \
  --plan "1. Reproduce  2. Fix CSS min-width  3. Add a test" \
  --label ui

# 3. Start work in one step: worktree + branch off latest origin/main, claim, and stamp the branch.
python scripts/task.py start 188 --slug "comment panel width"
#   (or, if you made the worktree yourself, claim from inside it - it auto-detects the branch)
python scripts/task.py claim 188

# 4. Keep a heartbeat running for the whole session (refreshes one pinned comment every 5 min in place).
#    Launch it as a session-scoped background process (NOT detached) so it stops when your session ends.
python scripts/task.py heartbeat 188 --watch

#    Find issues nobody is working on (missing or stale heartbeat); each row names the branch to resume.
python scripts/task.py stale --minutes 15

#    Board of ALL open task issues with handling Copilot session id, branch, last activity, and state.
#    start/claim/heartbeat stamp the session id from COPILOT_AGENT_SESSION_ID (override: --session-id).
python scripts/task.py board                 # add --all-labels for every open issue, --json for rows

#    OPTIONAL: mirror the handling session id + last activity ONTO the Projects v2 board as the
#    "Session" and "Last active" text fields, keeping them CURRENT - it SETS them for open issues with
#    a fresh heartbeat and CLEARS them for closed/stale issues. Needs the `project` token scope
#    (one-time interactive grant) and the two fields created once; else it is a clean no-op.
#      gh auth refresh -s project                 # one-time: grant the write scope
#      # then create TEXT fields named exactly "Session" and "Last active" (board UI or the API;
#      # project-sync prints the createProjectV2Field mutation with the board id if a field is missing)
python scripts/task.py project-sync           # --issue N for one, --dry-run to preview
#    Once set up, run it best-effort from the heartbeat (swallows any project/scope/network error):
python scripts/task.py heartbeat 188 --watch --project-sync
#    The board is also kept current automatically by the scheduled .github/workflows/project-sync.yml
#    (cron + issue open/close/reopen). That workflow needs a project-scoped token as the repo secret
#    PROJECT_SYNC_TOKEN (a CLASSIC PAT with the 'project' and 'repo' scopes; a fine-grained PAT does
#    not reliably work for a user-owned project); until it exists the workflow is a clean no-op.

# 5. Share the implementation plan for approval before coding.
python scripts/task.py plan 188 "1. Rebase onto main  2. Fix  3. Test"

# 6. Tick each acceptance criterion as you finish it (1-based), or --all at once.
# Always use this - it round-trips the body as one string and writes via --body-file, so it
# never corrupts the Markdown. Never hand-edit the body with raw gh: `$b = gh issue view -q .body`
# captures multi-line output as an ARRAY (newlines dropped) and rejoins with no separator,
# collapsing every blank line and heading.
python scripts/task.py check-ac 188 1
python scripts/task.py check-ac 188 --all

# 7. Record the final summary; open the PR with `Closes #188` to close the issue.
python scripts/task.py finish 188 "Enforced a CSS min-width and covered it with a test."
```

## Conventions baked in

- Every new issue gets the `task` label; pass `--label <area>` for area labels (deck, site, ui, runtime,
  tooling, audit, documentation).
- Bodies must be plain ASCII: the wrapper rejects any non-ASCII character (em/en dashes, ellipsis,
  smart quotes, non-breaking spaces, emoji) so the house style holds. Use the wrapper (not raw
  `gh issue create`) for any operation that writes an issue body, so this guard always runs.
- `claim` adds the `status: in progress` label AND stamps the worktree branch (auto-detected, or
  `--branch <name>`) into a single pinned "Work status" comment; `start` also creates the worktree first.
  The `issue-status-sync` workflow adds the label when a PR that says `Closes #N` opens, and merging that
  PR closes the issue.
- `heartbeat <n>` refreshes the "Work status" comment's UTC timestamp IN PLACE (no new comment). With
  `--watch` it becomes a daemon beating every `--interval` seconds (default 300); run it session-scoped
  so a stopped heartbeat certainly means work stopped. `stale` lists in-progress issues whose heartbeat
  is missing or older than the threshold, so abandoned work is easy to find and resume from its branch.
- The "Work status" comment is adopted only from a trusted author - a maintainer/collaborator
  (`author_association` OWNER/MEMBER/COLLABORATOR) or the invoking account itself - so an outsider cannot
  plant it on a public issue; heartbeats never regress a newer timestamp, and duplicate status comments
  (from a rare concurrent first-write) converge to one by editing the oldest and pruning the rest.