{"id":47846999,"url":"https://github.com/jepegit/issue-flow","last_synced_at":"2026-06-06T21:01:37.473Z","repository":{"id":349019641,"uuid":"1200701112","full_name":"jepegit/issue-flow","owner":"jepegit","description":"Agents should behave. Let them follow the issue flow.","archived":false,"fork":false,"pushed_at":"2026-06-06T19:59:09.000Z","size":321,"stargazers_count":2,"open_issues_count":15,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T21:01:33.489Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jepegit.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T18:17:12.000Z","updated_at":"2026-06-06T19:55:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jepegit/issue-flow","commit_stats":null,"previous_names":["jepegit/issue-flow"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/jepegit/issue-flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jepegit%2Fissue-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jepegit%2Fissue-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jepegit%2Fissue-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jepegit%2Fissue-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jepegit","download_url":"https://codeload.github.com/jepegit/issue-flow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jepegit%2Fissue-flow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33999593,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-03T21:24:43.711Z","updated_at":"2026-06-06T21:01:37.465Z","avatar_url":"https://github.com/jepegit.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"# issue-flow\n\nAgents should behave. Let them follow the issue flow.\n\n**issue-flow** scaffolds a lightweight issue-tracking workflow into your project so that AI coding agents can pick up GitHub issues, plan work, and land PRs in a consistent way. It supports **Cursor, Claude Code, opencode, and Codex** via `--editor` (see [Editor support](#editor-support)); the examples below use the default, Cursor.\n\n## What it does\n\nRunning `issue-flow init` in your project root creates:\n\n```text\nyour-project/\n  .issueflows/\n    00-tools/                # Helper scripts for agents\n    01-current-issues/       # Active issue markdown files\n    02-partly-solved-issues/ # Parked / in-progress issues\n    03-solved-issues/        # Completed issues archive\n  .cursor/\n    commands/\n      issue-pick.md          # /issue-pick — choose the next issue, branch, init (front door)\n      iflow.md               # /iflow — smart dispatcher (quick start)\n      issue-init.md          # /issue-init — fetch a GitHub issue locally\n      issue-plan.md          # /issue-plan — write issue\u003cN\u003e_plan.md and confirm\n      issue-start.md         # /issue-start — implement the plan\n      issue-pause.md         # /issue-pause — park work in 02-partly-solved-issues/\n      issue-close.md         # /issue-close — test, commit, push, PR\n      issue-cleanup.md       # /issue-cleanup — post-merge branch hygiene\n      issue-yolo.md          # /issue-yolo — all-in-one for small, low-risk issues\n      graphify.md            # /graphify — rebuild the graphify knowledge graph (optional)\n    skills/                  # Optional Agent Skills (explicit / @ invoke)\n      issueflow-issue-pick/SKILL.md\n      issueflow-iflow/SKILL.md\n      issueflow-issue-init/SKILL.md\n      issueflow-issue-plan/SKILL.md\n      issueflow-issue-start/SKILL.md\n      issueflow-issue-pause/SKILL.md\n      issueflow-issue-close/SKILL.md\n      issueflow-issue-cleanup/SKILL.md\n      issueflow-issue-yolo/SKILL.md\n      issueflow-version-bump/SKILL.md\n      issueflow-history-update/SKILL.md\n      issueflow-graphify/SKILL.md\n    rules/\n      issueflow-rules.mdc    # Always-on Cursor rule for the workflow\n  AGENTS.md                  # Workflow rules (managed block; shared by all editors)\n  docs/\n    issue-workflow.md        # Human-readable overview of the workflow\n```\n\nThe exact `agent_dir` and the per-editor rules file depend on which editor(s) you scaffold for — see [Editor support](#editor-support). `AGENTS.md` (written as a non-destructive managed block) and `docs/issue-workflow.md` are shared by every editor.\n\nThe Cursor slash commands give agents a repeatable flow. The linear path is:\n\n1. `/issue-init 42` — pulls GitHub issue #42 into `.issueflows/01-current-issues/` and archives older issues.\n2. `/issue-plan` — drafts `issue\u003cN\u003e_plan.md` (Goal / Constraints / Approach / Files to touch / Test strategy / Open questions) and stops for your confirmation.\n3. `/issue-start` — reads the confirmed plan and implements it. If no plan file exists, it offers to run `/issue-plan` first, proceed without a plan, or abort.\n4. `/issue-close` — runs tests, optionally bumps version with `uv version --bump`, appends a `HISTORY.md` entry (or promotes `[Unreleased]` to a new release section on a bump), updates status files, commits, pushes, and opens a PR.\n5. `/issue-cleanup` — after the PR merges, switches to the default branch, fast-forwards, prunes, and deletes the merged local branch.\n\nPlus a few off-path commands:\n\n- `/issue-pick` — **front door**: when you haven't chosen an issue yet, it helps pick one (parked work in `02-partly-solved-issues/` first, else open GitHub issues ranked by milestone, labels, and similarity to recently solved work), creates the `\u003cN\u003e-slug` branch, and runs `/issue-init`. Pass `fix` to create a new general-fixes issue. Off-path; never auto-dispatched.\n- `/iflow` — **quick start**: inspects the current issue's state and dispatches to the right linear step automatically. A branch-derived number (`42-fix-login` → `N=42`) is authoritative, so `/iflow` works from a fresh branch too.\n- `/issue-pause` — park the current issue in `02-partly-solved-issues/` with a **Remaining work** note; optional WIP commit + switch back to the default branch.\n- `/issue-yolo` — all-in-one chain (`init → plan → start → close`) for small, low-risk issues, with up-front safeguards (refuses on the default branch, refuses with dirty unrelated changes, requires passing tests, single consolidated confirm).\n\nThe matching **Agent Skills** (under `.cursor/skills/`) carry the same workflows for on-demand use with `/issueflow-issue-pick`, `/issueflow-iflow`, `/issueflow-issue-init`, `/issueflow-issue-plan`, `/issueflow-issue-start`, `/issueflow-issue-pause`, `/issueflow-issue-close`, `/issueflow-issue-cleanup`, `/issueflow-issue-yolo`, `@issueflow-version-bump` when you need only the bump steps, or `@issueflow-history-update` when you need only the changelog update (see [Cursor Agent Skills](https://cursor.com/docs/context/skills)).\n\n## Prerequisites\n\nissue-flow itself is a small Python CLI, but the **scaffolded slash commands\nit writes into your project shell out to a few external tools**. If they are\nmissing, the slash commands will fail at runtime — so `issue-flow init` now\nchecks for them up front and prints install hints before it does anything.\n\nRequired:\n\n- **[Git](https://git-scm.com/downloads)** — used by every slash command for\n  branch, fetch, status, commit, and push operations. Almost certainly already\n  installed if you're here, but the check covers it for completeness.\n- **[GitHub CLI (`gh`)](https://cli.github.com/)** — used by `/issue-init` to\n  fetch issues, by `/issue-close` to open PRs, and by `/issue-cleanup` to check\n  PR merge status. After installing, run `gh auth login` once to authenticate.\n\nRecommended:\n\n- **[uv](https://docs.astral.sh/uv/)** — how issue-flow itself is meant to be\n  installed, and how this repo manages its own Python environment.\n\nQuick install pointers for `gh`:\n\n| Platform | Command |\n|---|---|\n| macOS (Homebrew) | `brew install gh` |\n| Windows (winget) | `winget install --id GitHub.cli -e` |\n| Linux (Debian/Ubuntu) | `sudo apt install gh` (or see [cli.github.com](https://cli.github.com/) for the official repo) |\n\nIf a dependency is missing, `issue-flow init` prints the installation hints\nand asks whether to continue anyway. You can bypass the prompt in automation\nwith `issue-flow init --skip-dep-check` (the same flag is available on\n`issue-flow update`), and the prompt is also auto-skipped when stdin is not\na TTY (e.g. CI pipelines).\n\n### Optional: graphify integration\n\nissue-flow has a lightweight integration with [graphify](https://graphify.net)\n(PyPI: `graphifyy`, CLI: `graphify`) — a tool that turns the project into a\nqueryable knowledge graph that AI assistants can read instead of grepping\nthrough files. The integration is **opt-in by installing `graphifyy` as its\nown tool** (the same way you installed issue-flow): there is no flag, no\n`.env` switch, no extras to remember. Detection is purely PATH-based.\n\nWhat `issue-flow` does when `graphify` is on PATH:\n\n- `issue-flow init` and `issue-flow update` run `graphify cursor install` so\n  the graphify Cursor skill is registered alongside the issue-flow scaffold.\n  If graphify is not installed, both commands just print install hints and\n  continue — they never block.\n- A new slash command `/graphify` (and matching `/issueflow-graphify` skill) wraps\n  `issue-flow graphify`. With no extra args it runs `graphify update \u003cproject\u003e`\n  — AST-only, **no LLM API key required**, so the no-arg case \"just works\".\n  For richer semantic relationships add `extract` (`issue-flow graphify extract`)\n  and configure a backend (`GEMINI_API_KEY`, `ANTHROPIC_API_KEY`,\n  `OPENAI_API_KEY`, `MOONSHOT_API_KEY`, or `--backend ollama` for a local\n  LLM). Cursor's own LLM is not available to subprocesses, so graphify\n  needs its own backend. Other subcommands (`watch`, `cluster-only`, …)\n  pass through too; trailing flags forward verbatim.\n- The scaffolded rules and `/issue-start` mention `graphify-out/GRAPH_REPORT.md`\n  as a recommended pre-read when the file exists. `/graphify` is **off-path** —\n  `/iflow` never auto-dispatches to it.\n\nTo enable, install graphify as its own standalone tool:\n\n```bash\nuv tool install graphifyy   # recommended\n# or\npipx install graphifyy\n# or\npip install graphifyy\n```\n\n\u003e **Why not an `issue-flow[graphify]` extra (or `uv tool install issue-flow --with graphifyy`)?**\n\u003e `uv tool install` only puts the **host package's** entry-point scripts on\n\u003e PATH. An extra (or `--with graphifyy`) pulls graphifyy into issue-flow's\n\u003e venv but leaves the `graphify` CLI invisible to the shell, so `/graphify`\n\u003e and `graphify cursor install` would still fail. Installing graphify as\n\u003e its own tool puts a real `graphify` shim on PATH and matches how we\n\u003e treat `git` / `gh`.\n\n\u003e **Just installed graphifyy and `issue-flow init` says it's still missing?**\n\u003e uv prints `~/.local/bin is not on your PATH` after the first\n\u003e `uv tool install`. Run `uv tool update-shell` (refreshes shell rc files),\n\u003e then **restart your shell and Cursor** so the new PATH takes effect.\n\u003e issue-flow's missing-CLI hint also detects this case and tells you the\n\u003e exact directory to add.\n\nAfter installing, run `issue-flow update` once so the graphify Cursor skill\ngets registered.\n\n## Installation\n\nRequires Python 3.13+ and [uv](https://docs.astral.sh/uv/).\n\n```bash\nuv tool install issue-flow\n```\n\nOr add it as a dev dependency to your project:\n\n```bash\nuv add --dev issue-flow\n```\n\n## Quick start\n\n```bash\ncd your-project\nissue-flow init\n```\n\nThat's it. Open the project in Cursor and start with `/iflow` (or step through `/issue-init`, `/issue-plan`, `/issue-start`, `/issue-close`, `/issue-cleanup` explicitly).\n\n## Usage\n\n```\nissue-flow init [PROJECT_DIR] [--force] [--skip-dep-check]\nissue-flow update [PROJECT_DIR] [--skip-dep-check]\nissue-flow graphify [-C PROJECT_DIR] [...graphify subcommand + args]\n```\n\n### `issue-flow init`\n\n| Argument / Option | Description |\n|---|---|\n| `PROJECT_DIR` | Project root directory. Defaults to `.` (current directory). |\n| `--force`, `-f` | Overwrite generated commands, rules, and workflow doc instead of skipping them. |\n| `--skip-dep-check` | Skip the external-CLI dependency check (`git`, `gh`) and the confirmation prompt that follows if anything is missing. Useful in automation. |\n| `--editor`, `-e` | AI coding tool(s) to scaffold for: `cursor` (default), `claude`, `opencode`, `codex`, or `all`. Repeatable (`-e cursor -e claude`). See [Editor support](#editor-support). |\n\nRunning `init` again without `--force` is safe: generated scaffold files that already exist are skipped, and **issue markdown under `.issueflows/` is never touched** by `init` or `update`. When the CLI detects an existing scaffold, it reminds you about `update` and `--force`.\n\n### `issue-flow update`\n\n| Argument / Option | Description |\n|---|---|\n| `PROJECT_DIR` | Project root directory. Defaults to `.` (current directory). |\n| `--skip-dep-check` | Skip the external-CLI dependency check (`git`, `gh`) and the confirmation prompt that follows if anything is missing. |\n| `--editor`, `-e` | AI coding tool(s) to refresh for: `cursor` (default), `claude`, `opencode`, `codex`, or `all`. Repeatable. See [Editor support](#editor-support). |\n\nUse `update` after upgrading the **issue-flow** package to refresh the packaged slash commands, rules file(s), and `docs/issue-workflow.md` from the version you have installed. This **overwrites** those generated files (unlike a plain second `init`). It still does not modify arbitrary files under `.issueflows/` (for example your `issue*_original.md` / `issue*_status.md` files), and it creates any **new** `.issueflows/` subdirectories required by the current package.\n\n### `issue-flow graphify`\n\n| Argument / Option | Description |\n|---|---|\n| `-C`, `--project-dir` | Project root directory to scan with graphify. Defaults to `.` (current directory). Modeled on `git -C` so positional args can flow into graphify untouched. |\n| `...graphify subcommand + args` | Optional graphify subcommand + flags. With no extras runs `graphify update \u003cPROJECT_DIR\u003e` — AST-only, **no LLM API key required**. The first extra arg, if it is a recognized build subcommand (`update`, `extract`, `watch`, `cluster-only`, `check-update`), picks the action; trailing tokens forward verbatim. Examples: `issue-flow graphify extract` (semantic LLM pass; needs `GEMINI_API_KEY` / `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `MOONSHOT_API_KEY` or `--backend ollama`), `issue-flow graphify cluster-only --no-viz`, `issue-flow graphify ./subdir`. |\n\n`graphify` requires `graphifyy` to be installed (`uv tool install graphifyy`). When the `graphify` CLI is missing, the command prints install hints and exits with code `2`. Outputs land in `graphify-out/` (`graph.html`, `GRAPH_REPORT.md`, `graph.json`).\n\n### When to use which\n\n| Goal | Command |\n|---|---|\n| First-time setup, or add missing files only | `issue-flow init` |\n| Pull newer templates after `uv tool upgrade issue-flow` (or similar) | `issue-flow update` |\n| Replace generated scaffolds without upgrading logic | `issue-flow init --force` |\n| Rebuild the graphify knowledge graph | `issue-flow graphify` |\n\n## Editor support\n\nissue-flow can scaffold its workflow for several AI coding tools. Pass one or\nmore `--editor` values (repeatable, or `all`) to `init` / `update`; the default\nis `cursor`, so existing setups are unchanged.\n\n```bash\nissue-flow init                          # Cursor (default)\nissue-flow init --editor claude          # Claude Code\nissue-flow init -e cursor -e claude      # both\nissue-flow init --editor all             # every supported editor\n```\n\n**Agent Skills** (`\u003cagent_dir\u003e/skills/\u003cname\u003e/SKILL.md`) are the portable core —\nevery editor gets the full set. **`AGENTS.md`** is the convergent rules file and\nis written for every editor as a non-destructive *managed block* (issue-flow\nonly ever owns the content between its markers, so a hand-maintained `AGENTS.md`\nis preserved). Slash commands and an editor-specific rules file are layered on\ntop where the tool supports them.\n\n| Editor | `agent_dir` | Slash commands | Skills | Extra rules file | `AGENTS.md` | graphify auto-register |\n|---|---|---|---|---|---|---|\n| Cursor | `.cursor/` | `commands/` | yes | `.cursor/rules/issueflow-rules.mdc` | yes | yes |\n| Claude Code | `.claude/` | `commands/` | yes | `CLAUDE.md` | yes | no |\n| opencode | `.opencode/` | `command/` | yes | — | yes | no |\n| Codex | `.codex/` | — (use skills) | yes | — | yes | no |\n\nCodex CLI removed project-scoped slash commands, so on Codex you invoke the\nmirrored skills (e.g. `issueflow-issue-init`) instead of `/issue-init`. The\ngraphify integration currently registers only with Cursor; other editors still\nget the `/graphify` command/skill but no automatic `graphify cursor install`.\n\n## Configuration\n\nissue-flow reads a `.env` file from the project root (via python-dotenv). The following environment variables are supported:\n\n| Variable | Default | Description |\n|---|---|---|\n| `ISSUEFLOW_DIR` | `.issueflows` | Name of the issue-tracking directory. |\n| `ISSUEFLOW_EDITOR` | `cursor` | Default editor profile when `--editor` is not passed (`cursor`, `claude`, `opencode`, `codex`). |\n| `ISSUEFLOW_AGENT_DIR` | *(per editor)* | Override the agent/IDE config directory. When unset it is derived from the editor profile (e.g. `.cursor`, `.claude`, `.opencode`, `.codex`). |\n| `ISSUEFLOW_DOCS_DIR` | `docs` | Where to write the workflow documentation file. |\n| `ISSUEFLOW_HISTORY_FILE` | `HISTORY.md` | Changelog file that `/issue-close` updates (set to e.g. `CHANGELOG.md` for different conventions). |\n\n## Development\n\n```bash\ngit clone https://github.com/jepegit/issue-flow.git\ncd issue-flow\nuv sync\n\n# Run tests\nuv run pytest\n\n# Lint\nuv run ruff check src/ tests/\n```\n\n## Changelog\n\nSee [HISTORY.md](HISTORY.md) for release notes.\n\n## Future plans\n\n- **More editors** — extend `--editor` coverage to further AI coding tools (e.g. Windsurf) on top of the current Cursor / Claude Code / opencode / Codex support.\n- **`issue-flow status`** — show a dashboard of current, partly-solved, and solved issues.\n- **Custom templates** — let users supply their own Jinja2 templates to tailor slash commands and rules to their team's conventions.\n- **Git hook integration** — optionally move issue files on commit based on status markers.\n- **GitHub Actions workflow** — ship a reusable action that syncs issue state between `.issueflows/` and GitHub issue labels/milestones.\n\n## License\n\nThis project is released under the MIT License. See the full text in the repository: [LICENSE](https://github.com/jepegit/issue-flow/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjepegit%2Fissue-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjepegit%2Fissue-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjepegit%2Fissue-flow/lists"}