---
name: imdone
description: Use the imdone CLI as the single repo-local entry point for Jira- or GitHub-backed backlog workflows. Prefer direct `imdone` commands over manual issue-file edits when a command exists. Use structured output modes when machine-readable results are needed.
user-invocable: true
argument-hint: "[command] [flags]"
---

# Imdone

Use this as the default repo-local skill for CLI-backed imdone work.

The skill's job is to choose and run the right `imdone` command, not to re-implement provider workflows in prompt text.

## Core Rule

- Prefer direct `imdone` commands over manual file edits when a command exists for the requested job.
- Prefer `--format json` or `--format yaml` when the caller needs machine-readable output.
- Treat structured output as a contract: commands that support JSON or YAML should return only the requested payload on `stdout`.

## High-Value Command Surface

Start from the live CLI help in [references/command-catalog.md](references/command-catalog.md).

The main command families this skill should cover are:

- `imdone pull` and `imdone push` for provider sync
- `imdone status` for pending local changes
- `imdone list` / `imdone ls` for local issue listing and filtering
- `imdone show` for local issue context
- `imdone move` for provider status transitions
- `imdone add` for creating new issues
- `imdone template` for applying templates
- `imdone favorite` for favorites
- `imdone log` for issue history
- `imdone lint`, `clean`, `reset`, `merge`, `update`, and `test` when the request maps to maintenance or repair work

## Workflow

1. Translate the user request into the narrowest real `imdone` command.
2. Use explicit flags instead of relying on interactive prompts when values are already known.
3. Use `--format json|yaml|csv|text` intentionally.
4. Only fall back to manual issue-file edits when the CLI cannot do the requested job.
5. After command-driven changes, report the key result and any follow-up sync or verification step that still matters.

## Command Guidance

### Listing and reading

- Use `imdone ls` / `imdone list` for issue discovery.
- `-q` uses local imdone filter syntax, not JQL and not GitHub search syntax.
- Use `imdone show <issueKey>` for one issue's local context.
- Use `imdone log <issueKey>` for changelog/history requests.

### Status changes

- Use `imdone move <issueKey> <status>` for transitions.
- Treat status matching as case-insensitive, but prefer the exact status names shown by the CLI.
- If moving to `Done` fails because of resolution handling, retry with the smallest explicit resolution flag that matches the project need.

### Issue creation

- Use `imdone add` directly.
- Run add flows serially in this repo. Do not run multiple create flows in parallel.
- When an exact Jira sprint or issue type is needed, use the built-in discovery flags first:
  - `imdone add --provider jira --project-key <KEY> --list-issue-types`
  - `imdone add --provider jira --project-key <KEY> --list-sprints`
- Use explicit flags instead of relying on prompts when the needed values are already known.

### Templates

- Use `imdone template <issueKey> --template <template>` when the user wants to apply or repair a template-backed structure.
- For HDD preparation, prefer `hypothesis_driven_development` when available locally, otherwise use `stock_hypothesis_driven_development`.

### Sync and structured output

- Use `imdone pull` to refresh local provider state.
- Use `imdone push` to sync local changes back to the provider.
- For structured output modes, rely on the CLI payload directly rather than parsing human-facing terminal output.

## Maintenance Path

When the CLI surface changes:

1. Regenerate the local command catalog with `scripts/refresh_command_catalog.sh`.
2. Compare the refreshed help output against this skill.
3. Update only the command guidance that changed materially.

Keep this skill thin. If the CLI contract changes, update the command catalog and this one skill instead of reviving multiple command-specific imdone skills.

## Not In Scope

- Do not create a separate CLI-backed `feedback` skill again.
- Do not keep parallel command-specific imdone skill entry points for add/list/move/template once this skill exists.
- Do not replace specialized non-CLI domain skills such as HDD or cross-repo coordination with this skill.
