issue-flow 0.2.2__tar.gz → 0.2.3__tar.gz

issue_flow-0.2.3/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: issue-flow
+Version: 0.2.3
+Summary: Agents should behave. Let them follow the issue flow.
+Keywords: cursor,ai,agents,issue-tracking,workflow
+Author: jepegit
+Author-email: jepegit <jepe@ife.no>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: rich>=14.3.3
+Requires-Dist: typer>=0.24.1
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/jepegit/issue-flow
+Project-URL: Repository, https://github.com/jepegit/issue-flow
+Project-URL: Issues, https://github.com/jepegit/issue-flow/issues
+Description-Content-Type: text/markdown
+
+# issue-flow
+
+Agents should behave. Let them follow the issue flow.
+
+**issue-flow** scaffolds a lightweight issue-tracking workflow into your project so that Cursor AI agents can pick up GitHub issues, plan work, and land PRs in a consistent way.
+
+## What it does
+
+Running `issue-flow init` in your project root creates:
+
+```text
+your-project/
+  .issueflows/
+    00-tools/                # Helper scripts for agents
+    01-current-issues/       # Active issue markdown files
+    02-partly-solved-issues/ # Parked / in-progress issues
+    03-solved-issues/        # Completed issues archive
+  .cursor/
+    commands/
+      iflow.md               # /iflow — smart dispatcher (quick start)
+      issue-init.md          # /issue-init — fetch a GitHub issue locally
+      issue-plan.md          # /issue-plan — write issue<N>_plan.md and confirm
+      issue-start.md         # /issue-start — implement the plan
+      issue-pause.md         # /issue-pause — park work in 02-partly-solved-issues/
+      issue-close.md         # /issue-close — test, commit, push, PR
+      issue-cleanup.md       # /issue-cleanup — post-merge branch hygiene
+      issue-yolo.md          # /issue-yolo — all-in-one for small, low-risk issues
+    skills/                  # Optional Agent Skills (explicit / @ invoke)
+      issueflow-iflow/SKILL.md
+      issueflow-issue-init/SKILL.md
+      issueflow-issue-plan/SKILL.md
+      issueflow-issue-start/SKILL.md
+      issueflow-issue-pause/SKILL.md
+      issueflow-issue-close/SKILL.md
+      issueflow-issue-cleanup/SKILL.md
+      issueflow-issue-yolo/SKILL.md
+      issueflow-version-bump/SKILL.md
+      issueflow-history-update/SKILL.md
+    rules/
+      issueflow-rules.mdc    # Always-on Cursor rule for the workflow
+  docs/
+    cursor-issue-workflow.md # Human-readable overview of the workflow
+```
+
+The Cursor slash commands give agents a repeatable flow. The linear path is:
+
+1. `/issue-init 42` — pulls GitHub issue #42 into `.issueflows/01-current-issues/` and archives older issues.
+2. `/issue-plan` — drafts `issue<N>_plan.md` (Goal / Constraints / Approach / Files to touch / Test strategy / Open questions) and stops for your confirmation.
+3. `/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.
+4. `/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.
+5. `/issue-cleanup` — after the PR merges, switches to the default branch, fast-forwards, prunes, and deletes the merged local branch.
+
+Plus a few off-path commands:
+
+- `/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.
+- `/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.
+- `/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).
+
+The matching **Agent Skills** (under `.cursor/skills/`) carry the same workflows for on-demand use with `/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)).
+
+## Prerequisites
+
+issue-flow itself is a small Python CLI, but the **scaffolded slash commands
+it writes into your project shell out to a few external tools**. If they are
+missing, the slash commands will fail at runtime — so `issue-flow init` now
+checks for them up front and prints install hints before it does anything.
+
+Required:
+
+- **[Git](https://git-scm.com/downloads)** — used by every slash command for
+  branch, fetch, status, commit, and push operations. Almost certainly already
+  installed if you're here, but the check covers it for completeness.
+- **[GitHub CLI (`gh`)](https://cli.github.com/)** — used by `/issue-init` to
+  fetch issues, by `/issue-close` to open PRs, and by `/issue-cleanup` to check
+  PR merge status. After installing, run `gh auth login` once to authenticate.
+
+Recommended:
+
+- **[uv](https://docs.astral.sh/uv/)** — how issue-flow itself is meant to be
+  installed, and how this repo manages its own Python environment.
+
+Quick install pointers for `gh`:
+
+| Platform | Command |
+|---|---|
+| macOS (Homebrew) | `brew install gh` |
+| Windows (winget) | `winget install --id GitHub.cli -e` |
+| Linux (Debian/Ubuntu) | `sudo apt install gh` (or see [cli.github.com](https://cli.github.com/) for the official repo) |
+
+If a dependency is missing, `issue-flow init` prints the installation hints
+and asks whether to continue anyway. You can bypass the prompt in automation
+with `issue-flow init --skip-dep-check` (the same flag is available on
+`issue-flow update`), and the prompt is also auto-skipped when stdin is not
+a TTY (e.g. CI pipelines).
+
+## Installation
+
+Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install issue-flow
+```
+
+Or add it as a dev dependency to your project:
+
+```bash
+uv add --dev issue-flow
+```
+
+## Quick start
+
+```bash
+cd your-project
+issue-flow init
+```
+
+That'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).
+
+## Usage
+
+```
+issue-flow init [PROJECT_DIR] [--force] [--skip-dep-check]
+issue-flow update [PROJECT_DIR] [--skip-dep-check]
+```
+
+### `issue-flow init`
+
+| Argument / Option | Description |
+|---|---|
+| `PROJECT_DIR` | Project root directory. Defaults to `.` (current directory). |
+| `--force`, `-f` | Overwrite generated Cursor commands, rules, and workflow doc instead of skipping them. |
+| `--skip-dep-check` | Skip the external-CLI dependency check (`git`, `gh`) and the confirmation prompt that follows if anything is missing. Useful in automation. |
+
+Running `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`.
+
+### `issue-flow update`
+
+| Argument / Option | Description |
+|---|---|
+| `PROJECT_DIR` | Project root directory. Defaults to `.` (current directory). |
+| `--skip-dep-check` | Skip the external-CLI dependency check (`git`, `gh`) and the confirmation prompt that follows if anything is missing. |
+
+Use `update` after upgrading the **issue-flow** package to refresh the packaged slash commands, Cursor rule, and `docs/cursor-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.
+
+### When to use which
+
+| Goal | Command |
+|---|---|
+| First-time setup, or add missing files only | `issue-flow init` |
+| Pull newer templates after `uv tool upgrade issue-flow` (or similar) | `issue-flow update` |
+| Replace generated scaffolds without upgrading logic | `issue-flow init --force` |
+
+## Configuration
+
+issue-flow reads a `.env` file from the project root (via python-dotenv). The following environment variables are supported:
+
+| Variable | Default | Description |
+|---|---|---|
+| `ISSUEFLOW_DIR` | `.issueflows` | Name of the issue-tracking directory. |
+| `ISSUEFLOW_AGENT_DIR` | `.cursor` | Name of the agent/IDE config directory (currently `.cursor`). |
+| `ISSUEFLOW_DOCS_DIR` | `docs` | Where to write the workflow documentation file. |
+| `ISSUEFLOW_HISTORY_FILE` | `HISTORY.md` | Changelog file that `/issue-close` updates (set to e.g. `CHANGELOG.md` for different conventions). |
+
+## Development
+
+```bash
+git clone https://github.com/jepegit/issue-flow.git
+cd issue-flow
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check src/ tests/
+```
+
+## Changelog
+
+See [HISTORY.md](HISTORY.md) for release notes.
+
+## Future plans
+
+- **Multi-tool support** — generate config for other AI coding tools (Claude Code, Windsurf, etc.) in addition to Cursor.
+- **`issue-flow status`** — show a dashboard of current, partly-solved, and solved issues.
+- **Custom templates** — let users supply their own Jinja2 templates to tailor slash commands and rules to their team's conventions.
+- **Git hook integration** — optionally move issue files on commit based on status markers.
+- **GitHub Actions workflow** — ship a reusable action that syncs issue state between `.issueflows/` and GitHub issue labels/milestones.
+
+## License
+
+This project is released under the MIT License. See the full text in the repository: [LICENSE](https://github.com/jepegit/issue-flow/blob/main/LICENSE).

issue_flow-0.2.3/README.md

@@ -0,0 +1,192 @@
+# issue-flow
+
+Agents should behave. Let them follow the issue flow.
+
+**issue-flow** scaffolds a lightweight issue-tracking workflow into your project so that Cursor AI agents can pick up GitHub issues, plan work, and land PRs in a consistent way.
+
+## What it does
+
+Running `issue-flow init` in your project root creates:
+
+```text
+your-project/
+  .issueflows/
+    00-tools/                # Helper scripts for agents
+    01-current-issues/       # Active issue markdown files
+    02-partly-solved-issues/ # Parked / in-progress issues
+    03-solved-issues/        # Completed issues archive
+  .cursor/
+    commands/
+      iflow.md               # /iflow — smart dispatcher (quick start)
+      issue-init.md          # /issue-init — fetch a GitHub issue locally
+      issue-plan.md          # /issue-plan — write issue<N>_plan.md and confirm
+      issue-start.md         # /issue-start — implement the plan
+      issue-pause.md         # /issue-pause — park work in 02-partly-solved-issues/
+      issue-close.md         # /issue-close — test, commit, push, PR
+      issue-cleanup.md       # /issue-cleanup — post-merge branch hygiene
+      issue-yolo.md          # /issue-yolo — all-in-one for small, low-risk issues
+    skills/                  # Optional Agent Skills (explicit / @ invoke)
+      issueflow-iflow/SKILL.md
+      issueflow-issue-init/SKILL.md
+      issueflow-issue-plan/SKILL.md
+      issueflow-issue-start/SKILL.md
+      issueflow-issue-pause/SKILL.md
+      issueflow-issue-close/SKILL.md
+      issueflow-issue-cleanup/SKILL.md
+      issueflow-issue-yolo/SKILL.md
+      issueflow-version-bump/SKILL.md
+      issueflow-history-update/SKILL.md
+    rules/
+      issueflow-rules.mdc    # Always-on Cursor rule for the workflow
+  docs/
+    cursor-issue-workflow.md # Human-readable overview of the workflow
+```
+
+The Cursor slash commands give agents a repeatable flow. The linear path is:
+
+1. `/issue-init 42` — pulls GitHub issue #42 into `.issueflows/01-current-issues/` and archives older issues.
+2. `/issue-plan` — drafts `issue<N>_plan.md` (Goal / Constraints / Approach / Files to touch / Test strategy / Open questions) and stops for your confirmation.
+3. `/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.
+4. `/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.
+5. `/issue-cleanup` — after the PR merges, switches to the default branch, fast-forwards, prunes, and deletes the merged local branch.
+
+Plus a few off-path commands:
+
+- `/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.
+- `/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.
+- `/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).
+
+The matching **Agent Skills** (under `.cursor/skills/`) carry the same workflows for on-demand use with `/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)).
+
+## Prerequisites
+
+issue-flow itself is a small Python CLI, but the **scaffolded slash commands
+it writes into your project shell out to a few external tools**. If they are
+missing, the slash commands will fail at runtime — so `issue-flow init` now
+checks for them up front and prints install hints before it does anything.
+
+Required:
+
+- **[Git](https://git-scm.com/downloads)** — used by every slash command for
+  branch, fetch, status, commit, and push operations. Almost certainly already
+  installed if you're here, but the check covers it for completeness.
+- **[GitHub CLI (`gh`)](https://cli.github.com/)** — used by `/issue-init` to
+  fetch issues, by `/issue-close` to open PRs, and by `/issue-cleanup` to check
+  PR merge status. After installing, run `gh auth login` once to authenticate.
+
+Recommended:
+
+- **[uv](https://docs.astral.sh/uv/)** — how issue-flow itself is meant to be
+  installed, and how this repo manages its own Python environment.
+
+Quick install pointers for `gh`:
+
+| Platform | Command |
+|---|---|
+| macOS (Homebrew) | `brew install gh` |
+| Windows (winget) | `winget install --id GitHub.cli -e` |
+| Linux (Debian/Ubuntu) | `sudo apt install gh` (or see [cli.github.com](https://cli.github.com/) for the official repo) |
+
+If a dependency is missing, `issue-flow init` prints the installation hints
+and asks whether to continue anyway. You can bypass the prompt in automation
+with `issue-flow init --skip-dep-check` (the same flag is available on
+`issue-flow update`), and the prompt is also auto-skipped when stdin is not
+a TTY (e.g. CI pipelines).
+
+## Installation
+
+Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install issue-flow
+```
+
+Or add it as a dev dependency to your project:
+
+```bash
+uv add --dev issue-flow
+```
+
+## Quick start
+
+```bash
+cd your-project
+issue-flow init
+```
+
+That'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).
+
+## Usage
+
+```
+issue-flow init [PROJECT_DIR] [--force] [--skip-dep-check]
+issue-flow update [PROJECT_DIR] [--skip-dep-check]
+```
+
+### `issue-flow init`
+
+| Argument / Option | Description |
+|---|---|
+| `PROJECT_DIR` | Project root directory. Defaults to `.` (current directory). |
+| `--force`, `-f` | Overwrite generated Cursor commands, rules, and workflow doc instead of skipping them. |
+| `--skip-dep-check` | Skip the external-CLI dependency check (`git`, `gh`) and the confirmation prompt that follows if anything is missing. Useful in automation. |
+
+Running `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`.
+
+### `issue-flow update`
+
+| Argument / Option | Description |
+|---|---|
+| `PROJECT_DIR` | Project root directory. Defaults to `.` (current directory). |
+| `--skip-dep-check` | Skip the external-CLI dependency check (`git`, `gh`) and the confirmation prompt that follows if anything is missing. |
+
+Use `update` after upgrading the **issue-flow** package to refresh the packaged slash commands, Cursor rule, and `docs/cursor-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.
+
+### When to use which
+
+| Goal | Command |
+|---|---|
+| First-time setup, or add missing files only | `issue-flow init` |
+| Pull newer templates after `uv tool upgrade issue-flow` (or similar) | `issue-flow update` |
+| Replace generated scaffolds without upgrading logic | `issue-flow init --force` |
+
+## Configuration
+
+issue-flow reads a `.env` file from the project root (via python-dotenv). The following environment variables are supported:
+
+| Variable | Default | Description |
+|---|---|---|
+| `ISSUEFLOW_DIR` | `.issueflows` | Name of the issue-tracking directory. |
+| `ISSUEFLOW_AGENT_DIR` | `.cursor` | Name of the agent/IDE config directory (currently `.cursor`). |
+| `ISSUEFLOW_DOCS_DIR` | `docs` | Where to write the workflow documentation file. |
+| `ISSUEFLOW_HISTORY_FILE` | `HISTORY.md` | Changelog file that `/issue-close` updates (set to e.g. `CHANGELOG.md` for different conventions). |
+
+## Development
+
+```bash
+git clone https://github.com/jepegit/issue-flow.git
+cd issue-flow
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check src/ tests/
+```
+
+## Changelog
+
+See [HISTORY.md](HISTORY.md) for release notes.
+
+## Future plans
+
+- **Multi-tool support** — generate config for other AI coding tools (Claude Code, Windsurf, etc.) in addition to Cursor.
+- **`issue-flow status`** — show a dashboard of current, partly-solved, and solved issues.
+- **Custom templates** — let users supply their own Jinja2 templates to tailor slash commands and rules to their team's conventions.
+- **Git hook integration** — optionally move issue files on commit based on status markers.
+- **GitHub Actions workflow** — ship a reusable action that syncs issue state between `.issueflows/` and GitHub issue labels/milestones.
+
+## License
+
+This project is released under the MIT License. See the full text in the repository: [LICENSE](https://github.com/jepegit/issue-flow/blob/main/LICENSE).

{issue_flow-0.2.2 → issue_flow-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "issue-flow"
-version = "0.2.2"
+version = "0.2.3"
 description = "Agents should behave. Let them follow the issue flow."
 readme = "README.md"
 license = "MIT"

{issue_flow-0.2.2 → issue_flow-0.2.3}/src/issue_flow/cli.py

@@ -32,11 +32,21 @@ def init(
         "-f",
         help="Overwrite existing files without asking.",
     ),
+    skip_dep_check: bool = typer.Option(
+        False,
+        "--skip-dep-check",
+        help=(
+            "Skip the external-CLI dependency check (git, gh) and the "
+            "confirmation prompt that follows if anything is missing."
+        ),
+    ),
 ) -> None:
     """Scaffold issue-flow directories and Cursor config files in a project."""
     from issue_flow.init import run_init
 
-    run_init(project_root=project_dir, force=force)
+    run_init(
+        project_root=project_dir, force=force, skip_dep_check=skip_dep_check
+    )
 
 
 @app.command()
@@ -48,11 +58,19 @@ def update(
         file_okay=False,
         resolve_path=True,
     ),
+    skip_dep_check: bool = typer.Option(
+        False,
+        "--skip-dep-check",
+        help=(
+            "Skip the external-CLI dependency check (git, gh) and the "
+            "confirmation prompt that follows if anything is missing."
+        ),
+    ),
 ) -> None:
     """Refresh packaged Cursor commands, rules, and workflow doc from this package."""
     from issue_flow.init import run_update
 
-    run_update(project_root=project_dir)
+    run_update(project_root=project_dir, skip_dep_check=skip_dep_check)
 
 
 def main() -> None:

{issue_flow-0.2.2 → issue_flow-0.2.3}/src/issue_flow/config.py

@@ -25,18 +25,26 @@ class Settings:
     issueflows_dir: str = field(
         default_factory=lambda: os.getenv("ISSUEFLOW_DIR", ".issueflows")
     )
-    cursor_dir: str = field(
-        default_factory=lambda: os.getenv("ISSUEFLOW_CURSOR_DIR", ".cursor")
+    agent_dir: str = field(
+        default_factory=lambda: os.getenv("ISSUEFLOW_AGENT_DIR", ".cursor")
     )
     docs_dir: str = field(
         default_factory=lambda: os.getenv("ISSUEFLOW_DOCS_DIR", "docs")
     )
+    history_file: str = field(
+        default_factory=lambda: os.getenv("ISSUEFLOW_HISTORY_FILE", "HISTORY.md")
+    )
+
+    # Give a deprecation warning if the user is using the old ISSUEFLOW_CURSOR_DIR environment variable
+    if os.getenv("ISSUEFLOW_CURSOR_DIR"):
+        print("WARNING: The ISSUEFLOW_CURSOR_DIR environment variable is deprecated (replaced by ISSUEFLOW_AGENT_DIR).")
 
     # Subdirectory names inside .issueflows/
     tools_folder: str = "00-tools"
     current_issues_folder: str = "01-current-issues"
     partly_solved_folder: str = "02-partly-solved-issues"
     solved_folder: str = "03-solved-issues"
+    designs_folder: str = "04-designs-and-guides"
 
     @property
     def issueflows_subdirs(self) -> list[str]:
@@ -45,6 +53,7 @@ class Settings:
             self.current_issues_folder,
             self.partly_solved_folder,
             self.solved_folder,
+            self.designs_folder,
         ]
 
     def template_context(self, project_root: Path) -> dict[str, str]:
@@ -52,12 +61,14 @@ class Settings:
         project_name = _detect_project_name(project_root)
         return {
             "issueflows_dir": self.issueflows_dir,
-            "cursor_dir": self.cursor_dir,
+            "agent_dir": self.agent_dir,
             "docs_dir": self.docs_dir,
+            "history_file": self.history_file,
             "tools_folder": self.tools_folder,
             "current_issues_folder": self.current_issues_folder,
             "partly_solved_folder": self.partly_solved_folder,
             "solved_folder": self.solved_folder,
+            "designs_folder": self.designs_folder,
             "project_name": project_name,
         }
 

issue_flow-0.2.3/src/issue_flow/dependencies.py

@@ -0,0 +1,162 @@
+"""External CLI dependency detection for issue-flow.
+
+The scaffolded workflow shells out to ``git`` and ``gh`` (GitHub CLI) via
+slash commands. We detect missing tools at ``issue-flow init`` /
+``issue-flow update`` time so users get a clear install hint rather than a
+confusing failure later from inside a Cursor command.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from dataclasses import dataclass
+
+from rich.console import Console
+
+
+@dataclass(frozen=True)
+class Dependency:
+    """A single external CLI tool issue-flow's workflow depends on."""
+
+    name: str
+    command: str
+    purpose: str
+    docs_url: str
+    # Platform hint → short install snippet. Keys are free-form labels
+    # shown verbatim (e.g. "macOS (Homebrew)", "Windows (winget)", "Linux
+    # (Debian/Ubuntu)"). Values are one-line commands.
+    install_hints: tuple[tuple[str, str], ...]
+
+
+# The scaffolded slash commands (see
+# ``src/issue_flow/templates/commands/*.md.j2``) invoke these tools. ``uv``
+# is intentionally *not* listed here: it is an install-time prerequisite
+# for issue-flow itself, not something the scaffold calls at runtime, so
+# it belongs in the README only.
+REQUIRED_DEPENDENCIES: tuple[Dependency, ...] = (
+    Dependency(
+        name="Git",
+        command="git",
+        purpose=(
+            "Used by every slash command for branch, fetch, status, "
+            "commit, and push operations."
+        ),
+        docs_url="https://git-scm.com/downloads",
+        install_hints=(
+            ("macOS (Homebrew)", "brew install git"),
+            ("Windows (winget)", "winget install --id Git.Git -e"),
+            ("Linux (Debian/Ubuntu)", "sudo apt install git"),
+        ),
+    ),
+    Dependency(
+        name="GitHub CLI",
+        command="gh",
+        purpose=(
+            "Used by /issue-init to fetch issues, /issue-close to open "
+            "PRs, and /issue-cleanup to check PR merge status. Remember "
+            "to run `gh auth login` once after installing."
+        ),
+        docs_url="https://cli.github.com/",
+        install_hints=(
+            ("macOS (Homebrew)", "brew install gh"),
+            ("Windows (winget)", "winget install --id GitHub.cli -e"),
+            (
+                "Linux (Debian/Ubuntu)",
+                "sudo apt install gh  # or see https://cli.github.com/ for the official repo",
+            ),
+        ),
+    ),
+)
+
+
+def check_dependencies(
+    dependencies: tuple[Dependency, ...] = REQUIRED_DEPENDENCIES,
+) -> list[Dependency]:
+    """Return the subset of ``dependencies`` whose ``command`` is not on ``PATH``.
+
+    Uses :func:`shutil.which` only — no subprocess invocations — so it is
+    safe to call on any platform without risk of hanging or prompting.
+    """
+    return [dep for dep in dependencies if shutil.which(dep.command) is None]
+
+
+def format_missing_report(
+    missing: list[Dependency],
+    console: Console,
+) -> None:
+    """Print a human-readable report listing missing dependencies.
+
+    The output is intentionally compact and uses only ``rich`` markup so
+    it blends with the rest of the ``init`` output.
+    """
+    if not missing:
+        return
+
+    count = len(missing)
+    noun = "dependency" if count == 1 else "dependencies"
+    console.print(
+        f"[bold yellow]Missing {count} external {noun}:[/bold yellow]"
+    )
+    for dep in missing:
+        console.print(
+            f"\n  [bold]{dep.name}[/bold]  "
+            f"([cyan]{dep.command}[/cyan] not found on PATH)"
+        )
+        console.print(f"    [dim]{dep.purpose}[/dim]")
+        console.print(f"    Docs: [blue]{dep.docs_url}[/blue]")
+        console.print("    Install:")
+        for label, snippet in dep.install_hints:
+            console.print(f"      - {label}: [green]{snippet}[/green]")
+    console.print()
+
+
+def prompt_or_skip(
+    missing: list[Dependency],
+    console: Console,
+    *,
+    skip: bool,
+    stdin_is_tty: bool | None = None,
+) -> bool:
+    """Decide whether to proceed despite missing deps.
+
+    Returns ``True`` to continue, ``False`` if the user declined.
+
+    - If ``missing`` is empty, returns ``True``.
+    - If ``skip`` is ``True``, prints a one-line note and returns ``True``
+      without prompting.
+    - If stdin is not a TTY (e.g. CI, piped input), prints a one-line
+      note and returns ``True`` without prompting so automation doesn't
+      hang.
+    - Otherwise asks the user with :func:`typer.confirm`.
+    """
+    if not missing:
+        return True
+
+    format_missing_report(missing, console)
+
+    if skip:
+        console.print(
+            "[dim]Dependency check bypassed via --skip-dep-check; "
+            "continuing anyway.[/dim]\n"
+        )
+        return True
+
+    if stdin_is_tty is None:
+        stdin_is_tty = sys.stdin.isatty()
+
+    if not stdin_is_tty:
+        console.print(
+            "[dim]Non-interactive session (stdin is not a TTY); "
+            "continuing without prompting. "
+            "Install the tools above before running the slash commands.[/dim]\n"
+        )
+        return True
+
+    # Imported lazily to keep this module importable in environments
+    # that only need check_dependencies (e.g. tests or custom scripts).
+    import typer
+
+    return typer.confirm(
+        "Continue with issue-flow setup anyway?", default=False
+    )