issue-flow 0.1.0__tar.gz

issue_flow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Petter Maehlen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

issue_flow-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.3
+Name: issue-flow
+Version: 0.1.0
+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: MIT License
+         
+         Copyright (c) 2026 Jan Petter Maehlen
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+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/
+      issue-init.md         # /issue-init — fetch a GitHub issue locally
+      issue-start.md        # /issue-start — plan and implement
+      issue-close.md        # /issue-close — test, commit, push, PR
+    rules/
+      issueflow-rules.mdc   # Always-on Cursor rule for the workflow
+  docs/
+    cursor-issue-workflow.md # Human-readable overview of the workflow
+```
+
+The three Cursor slash commands give agents a repeatable flow:
+
+1. `/issue-init 42` — pulls GitHub issue #42 into `.issueflows/01-current-issues/` and archives older issues.
+2. `/issue-start` — reads the issue file, plans, and implements.
+3. `/issue-close` — runs tests, updates status files, commits, pushes, and opens a PR.
+
+## 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 use `/issue-init`, `/issue-start`, `/issue-close`.
+
+## Usage
+
+```
+issue-flow init [PROJECT_DIR] [--force]
+```
+
+| Argument / Option | Description |
+|---|---|
+| `PROJECT_DIR` | Project root directory. Defaults to `.` (current directory). |
+| `--force`, `-f` | Overwrite existing files instead of skipping them. |
+
+Running `init` a second time is safe — existing files are skipped unless `--force` is passed.
+
+## 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_CURSOR_DIR` | `.cursor` | Name of the Cursor config directory. |
+| `ISSUEFLOW_DOCS_DIR` | `docs` | Where to write the workflow documentation file. |
+
+## 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/
+```
+
+## 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
+
+See [LICENSE](LICENSE).

issue_flow-0.1.0/README.md

@@ -0,0 +1,105 @@
+# 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/
+      issue-init.md         # /issue-init — fetch a GitHub issue locally
+      issue-start.md        # /issue-start — plan and implement
+      issue-close.md        # /issue-close — test, commit, push, PR
+    rules/
+      issueflow-rules.mdc   # Always-on Cursor rule for the workflow
+  docs/
+    cursor-issue-workflow.md # Human-readable overview of the workflow
+```
+
+The three Cursor slash commands give agents a repeatable flow:
+
+1. `/issue-init 42` — pulls GitHub issue #42 into `.issueflows/01-current-issues/` and archives older issues.
+2. `/issue-start` — reads the issue file, plans, and implements.
+3. `/issue-close` — runs tests, updates status files, commits, pushes, and opens a PR.
+
+## 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 use `/issue-init`, `/issue-start`, `/issue-close`.
+
+## Usage
+
+```
+issue-flow init [PROJECT_DIR] [--force]
+```
+
+| Argument / Option | Description |
+|---|---|
+| `PROJECT_DIR` | Project root directory. Defaults to `.` (current directory). |
+| `--force`, `-f` | Overwrite existing files instead of skipping them. |
+
+Running `init` a second time is safe — existing files are skipped unless `--force` is passed.
+
+## 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_CURSOR_DIR` | `.cursor` | Name of the Cursor config directory. |
+| `ISSUEFLOW_DOCS_DIR` | `docs` | Where to write the workflow documentation file. |
+
+## 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/
+```
+
+## 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
+
+See [LICENSE](LICENSE).

issue_flow-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "issue-flow"
+version = "0.1.0"
+description = "Agents should behave. Let them follow the issue flow."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "jepegit", email = "jepe@ife.no" }
+]
+requires-python = ">=3.13"
+keywords = ["cursor", "ai", "agents", "issue-tracking", "workflow"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "jinja2>=3.1.6",
+    "python-dotenv>=1.2.2",
+    "rich>=14.3.3",
+    "typer>=0.24.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/jepegit/issue-flow"
+Repository = "https://github.com/jepegit/issue-flow"
+Issues = "https://github.com/jepegit/issue-flow/issues"
+
+[project.scripts]
+issue-flow = "issue_flow.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.2,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "ruff>=0.15.9",
+]

issue_flow-0.1.0/src/issue_flow/__init__.py

@@ -0,0 +1,3 @@
+"""issue-flow: Agents should behave. Let them follow the issue flow."""
+
+__version__ = "0.1.0"

issue_flow-0.1.0/src/issue_flow/cli.py

@@ -0,0 +1,44 @@
+"""Command-line interface for issue-flow."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+app = typer.Typer(
+    name="issue-flow",
+    add_completion=False,
+)
+
+
+@app.callback()
+def _callback() -> None:
+    """Agents should behave. Let them follow the issue flow."""
+
+
+@app.command()
+def init(
+    project_dir: Path = typer.Argument(
+        default=Path("."),
+        help="Project root directory (defaults to current directory).",
+        exists=True,
+        file_okay=False,
+        resolve_path=True,
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Overwrite existing files without asking.",
+    ),
+) -> 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)
+
+
+def main() -> None:
+    """Entry point for the `issue-flow` console script."""
+    app()

issue_flow-0.1.0/src/issue_flow/config.py

@@ -0,0 +1,76 @@
+"""Configuration for issue-flow, backed by .env files and environment variables."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotenv import load_dotenv
+import os
+
+
+# Load .env from the current working directory (the user's project root).
+# This runs at import time so that all downstream code sees the env vars.
+load_dotenv(override=False)
+
+
+@dataclass
+class Settings:
+    """Runtime settings for issue-flow.
+
+    Values come from environment variables (prefixed with ISSUEFLOW_) with
+    sensible defaults.  A .env file in the project root is loaded automatically.
+    """
+
+    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")
+    )
+    docs_dir: str = field(
+        default_factory=lambda: os.getenv("ISSUEFLOW_DOCS_DIR", "docs")
+    )
+
+    # 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"
+
+    @property
+    def issueflows_subdirs(self) -> list[str]:
+        return [
+            self.tools_folder,
+            self.current_issues_folder,
+            self.partly_solved_folder,
+            self.solved_folder,
+        ]
+
+    def template_context(self, project_root: Path) -> dict[str, str]:
+        """Build the Jinja2 template context dictionary."""
+        project_name = _detect_project_name(project_root)
+        return {
+            "issueflows_dir": self.issueflows_dir,
+            "cursor_dir": self.cursor_dir,
+            "docs_dir": self.docs_dir,
+            "tools_folder": self.tools_folder,
+            "current_issues_folder": self.current_issues_folder,
+            "partly_solved_folder": self.partly_solved_folder,
+            "solved_folder": self.solved_folder,
+            "project_name": project_name,
+        }
+
+
+def _detect_project_name(project_root: Path) -> str:
+    """Try to read the project name from pyproject.toml, fall back to dir name."""
+    pyproject = project_root / "pyproject.toml"
+    if pyproject.exists():
+        for line in pyproject.read_text(encoding="utf-8").splitlines():
+            stripped = line.strip()
+            if stripped.startswith("name") and "=" in stripped:
+                # e.g.  name = "my-project"
+                value = stripped.split("=", 1)[1].strip().strip('"').strip("'")
+                if value:
+                    return value
+    return project_root.resolve().name

issue_flow-0.1.0/src/issue_flow/init.py

@@ -0,0 +1,83 @@
+"""Implementation of the `issue-flow init` command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+
+from issue_flow.config import Settings
+from issue_flow.templating import (
+    TEMPLATE_MANIFEST,
+    render_template,
+    resolve_output_path,
+)
+
+console = Console()
+
+
+def run_init(project_root: Path, force: bool = False) -> None:
+    """Scaffold .issueflows/ directories and .cursor/ config files.
+
+    Args:
+        project_root: Absolute path to the user's project directory.
+        force: If True, overwrite existing files without asking.
+    """
+    settings = Settings()
+    context = settings.template_context(project_root)
+
+    console.print(
+        f"\n[bold]Initializing issue-flow in [cyan]{project_root}[/cyan][/bold]\n"
+    )
+
+    # ── 1. Create .issueflows/ subdirectories ────────────────────────
+    _create_issueflow_dirs(project_root, settings)
+
+    # ── 2. Render and write template files ───────────────────────────
+    written_files: list[Path] = []
+    skipped_files: list[Path] = []
+
+    for template_name, path_template in TEMPLATE_MANIFEST:
+        relative_path = resolve_output_path(path_template, context)
+        absolute_path = project_root / relative_path
+
+        if absolute_path.exists() and not force:
+            console.print(
+                f"  [yellow]skip[/yellow]  {relative_path}  (already exists, use --force to overwrite)"
+            )
+            skipped_files.append(relative_path)
+            continue
+
+        rendered = render_template(template_name, context)
+        absolute_path.parent.mkdir(parents=True, exist_ok=True)
+        absolute_path.write_text(rendered, encoding="utf-8")
+        console.print(f"  [green]write[/green] {relative_path}")
+        written_files.append(relative_path)
+
+    # ── 3. Summary ───────────────────────────────────────────────────
+    console.print()
+    if written_files:
+        console.print(
+            f"[bold green]Created {len(written_files)} file(s).[/bold green]"
+        )
+    if skipped_files:
+        console.print(
+            f"[bold yellow]Skipped {len(skipped_files)} existing file(s).[/bold yellow]"
+        )
+    if not written_files and not skipped_files:
+        console.print("[bold]Nothing to do.[/bold]")
+
+    console.print("\n[dim]Run [bold]/issue-init <number>[/bold] in Cursor to start tracking a GitHub issue.[/dim]\n")
+
+
+def _create_issueflow_dirs(project_root: Path, settings: Settings) -> None:
+    """Create the .issueflows/ directory tree."""
+    base = project_root / settings.issueflows_dir
+
+    for subdir_name in settings.issueflows_subdirs:
+        dir_path = base / subdir_name
+        if dir_path.exists():
+            console.print(f"  [dim]exists[/dim] {settings.issueflows_dir}/{subdir_name}/")
+        else:
+            dir_path.mkdir(parents=True, exist_ok=True)
+            console.print(f"  [green]mkdir[/green]  {settings.issueflows_dir}/{subdir_name}/")

issue_flow-0.1.0/src/issue_flow/templates/commands/issue-close.md.j2

@@ -0,0 +1,36 @@
+# Close out the current issue
+
+Run this when implementation is done and you are ready to land the work.
+
+## Input
+
+Optional: branch name, PR title, or anything special (e.g. draft PR, skip issue doc update, commit all changes).
+
+## Typical steps
+
+1. **Sanity check**
+   - Run tests and any checks you rely on (e.g. `uv run pytest`).
+   - Skim the diff so the commit matches what you intend to ship.
+
+2. **Issue tracking in the repo** (see project rules under `{{ issueflows_dir }}/{{ current_issues_folder }}`)
+   - Update the status file for this issue: clear checklist, remaining work, and use `- [x] Done` only when fully resolved.
+   - If the issue is fully resolved, move its markdown files from `{{ issueflows_dir }}/{{ current_issues_folder }}` to `{{ issueflows_dir }}/{{ solved_folder }}`. If partially resolved, move to `{{ issueflows_dir }}/{{ partly_solved_folder }}`.
+
+3. **Commit and fix merge conflicts**
+   - Unless told to commit all, stage the right files (avoid unrelated changes).
+   - Write a commit message that states what changed and why in normal sentences.
+   - Make sure you have pulled the last changes from the default branch (e.g. `main`) and check for and fix merge conflicts.
+
+4. **Push**
+   - Push your branch to `origin` (or the remote you use).
+
+5. **Pull request**
+   - Open a PR against the default branch (e.g. `main`).
+   - Describe the change, how to test it, and link the GitHub issue (e.g. `Closes #123` or `Refs #123` in the PR body).
+
+6. **After review**
+   - Address feedback, push updates, and merge when approved and CI is green.
+
+## Output
+
+Summarize what was committed, pushed, and the PR URL (or next step if blocked).

issue_flow-0.1.0/src/issue_flow/templates/commands/issue-init.md.j2

@@ -0,0 +1,81 @@
+# Create original issue file from GitHub issue
+
+Create an `*_original.md` file in `{{ issueflows_dir }}/{{ current_issues_folder }}` from a GitHub issue.
+
+## Input
+The user will provide one of:
+- an issue number (e.g. `123`)
+- or a full GitHub issue URL
+
+Use the text provided after this slash command as the issue reference.
+
+## Steps
+
+0. Check that the required folders exist (`{{ issueflows_dir }}/{{ tools_folder }}`, `{{ issueflows_dir }}/{{ current_issues_folder }}`, `{{ issueflows_dir }}/{{ partly_solved_folder }}`, `{{ issueflows_dir }}/{{ solved_folder }}`). If not, create them after asking for permission.
+
+1. Resolve the issue reference from the user input.
+   - If input is a full URL, extract `owner`, `repo`, and `issue number`.
+   - If input is only an issue number:
+     - derive `owner/repo` from `git remote` (prefer `origin`)
+     - support both SSH and HTTPS remote URL formats
+     - if parsing fails, ask the user for either full issue URL or `owner/repo`
+
+2. Fetch issue data using GitHub CLI (explicit repo if needed):
+   - title
+   - body
+   - url
+   - number
+   - and confirm resolved `owner/repo`
+
+3. Archive existing issue files already in `{{ issueflows_dir }}/{{ current_issues_folder }}` (except the current issue number).
+   - Inspect issue groups by issue number (for example `issue121_*` belongs to issue 121).
+   - Consider all files for that issue in `{{ issueflows_dir }}/{{ current_issues_folder }}` (original + status/supplementary files) as one group to move together.
+   - Decide destination:
+     - move to `{{ issueflows_dir }}/{{ solved_folder }}` if the issue is done
+     - move to `{{ issueflows_dir }}/{{ partly_solved_folder }}` if the issue is not done
+  - Determine "done" status from an explicit checkbox marker in a status file:
+    - done only if a status markdown file for that issue contains `- [x] Done` (case-insensitive match for `done`)
+    - if the checkbox is missing, unchecked (`- [ ] Done`), unclear, or no status file exists, treat as not done
+   - Never move files for the issue currently being created.
+
+4. Create this file:
+   - `{{ issueflows_dir }}/{{ current_issues_folder }}/issue<number>_original.md`
+5. File content format:
+   ```markdown
+   # Issue #<number>: <title>
+
+   Source: <url>
+
+   ## Original issue text
+
+   <body exactly as in GitHub issue>
+   ```
+6. If `gh` is not authenticated or issue fetch fails:
+   - stop and report the exact error
+   - suggest `gh auth login`
+7. If the target file already exists:
+   - do not overwrite silently
+   - ask whether to overwrite or keep both
+
+## Output to user
+Report:
+- issue number fetched
+- repository used (`owner/repo`)
+- file path created
+- archive moves performed (source -> destination, grouped by issue number)
+- whether the operation succeeded
+
+## Constraints
+- Preserve the issue body exactly as returned by GitHub.
+- Use UTF-8 markdown.
+- Allowed file modifications for this command:
+  - create/update the target `issue<number>_original.md`
+  - move pre-existing issue files from `{{ issueflows_dir }}/{{ current_issues_folder }}` to `{{ issueflows_dir }}/{{ partly_solved_folder }}` or `{{ issueflows_dir }}/{{ solved_folder }}` according to the archive rule above
+- If `{{ issueflows_dir }}/{{ current_issues_folder }}` does not exist, report an error and stop.
+- If archive destination directories do not exist, report an error and stop.
+- Prefer deterministic behavior: always state which repo was resolved before writing the file.
+
+## Example invocations
+- `/issue-init 123`
+- `/issue-init https://github.com/owner/repo/issues/123`
+- `/issue-init owner/repo/#123`

issue_flow-0.1.0/src/issue_flow/templates/commands/issue-start.md.j2

@@ -0,0 +1,16 @@
+# Start working with current issue
+
+The issue should already be explained in a markdown file in `{{ issueflows_dir }}/{{ current_issues_folder }}`.
+
+## Input
+If additional input is added, use that for further detailed guidance
+
+## Steps
+
+0. If the issue markdown file is not present, or it is ambiguous which one to select, ask.
+
+1. Plan. If not in plan mode, stop and ask for a confirmation.
+
+2. Check that the plan is not too broad. If too broad, ask if it should be split into several parts.
+
+3. Implement the steps of the plan

issue_flow-0.1.0/src/issue_flow/templates/docs/cursor-issue-workflow.md.j2

@@ -0,0 +1,83 @@
+# Cursor issue workflow (slash commands)
+
+This repo uses three Cursor **slash commands** under `{{ cursor_dir }}/commands/` that line up with how we track GitHub issues in `{{ issueflows_dir }}/{{ current_issues_folder }}/`. Use them in order when you pick up work from GitHub and want the assistant to follow the same steps.
+
+| Command | File | Role |
+|--------|------|------|
+| `/issue-init` | `issue-init.md` | Pull an issue from GitHub into the repo as a local markdown file and tidy older current issues. |
+| `/issue-start` | `issue-start.md` | Plan and implement the work described in `{{ issueflows_dir }}/{{ current_issues_folder }}/`. |
+| `/issue-close` | `issue-close.md` | Finish: tests, issue-folder housekeeping, commit, push, PR. |
+
+---
+
+## 1. `/issue-init` — capture the issue locally
+
+**When:** You have a GitHub issue you want to work on (or archive older "current" issues before starting a new one).
+
+**What you pass:** Either an issue number (e.g. `42`) or a full GitHub issue URL. The assistant resolves `owner/repo` from `git remote origin` when you only pass a number.
+
+**What happens:**
+
+- The assistant uses **GitHub CLI** (`gh`) to fetch title, body, URL, and number. You need `gh` authenticated (`gh auth login` if needed).
+- It creates **`{{ issueflows_dir }}/{{ current_issues_folder }}/issue<number>_original.md`** with the title, source URL, and the **exact** issue body from GitHub.
+- **Archive:** Other files already in `{{ issueflows_dir }}/{{ current_issues_folder }}/` (grouped by issue number, e.g. `issue121_*`) may be **moved** to `{{ issueflows_dir }}/{{ partly_solved_folder }}/` or `{{ issueflows_dir }}/{{ solved_folder }}/`, based on whether a status file for that issue contains a checked **Done** line (`- [x] Done`). The new issue's files are never moved as part of this step.
+- If the target `issue<number>_original.md` already exists, the assistant should not overwrite it without asking.
+
+**Result:** One canonical "original issue" file under `{{ issueflows_dir }}/{{ current_issues_folder }}/` plus optional archive moves. You can add or edit a separate `issue<number>_status.md` (or similar) by hand or with the assistant as work progresses.
+
+---
+
+## 2. `/issue-start` — plan and implement
+
+**When:** The issue is represented in `{{ issueflows_dir }}/{{ current_issues_folder }}/` (at minimum the `*_original.md` file) and you are ready to code.
+
+**What you pass:** Optional extra instructions (scope, constraints, design preferences).
+
+**What the assistant does:**
+
+1. Confirms **which** issue file applies if several exist or things are ambiguous.
+2. **Plans** the work. If you are not in plan mode, it should stop and ask you to confirm before large changes.
+3. Checks the plan is **not too broad**; may suggest splitting into smaller chunks.
+4. **Implements** the plan (code, tests, and updates to issue status docs as appropriate for the task).
+
+**Result:** Implementation aligned with the markdown in `{{ issueflows_dir }}/{{ current_issues_folder }}/` and project rules (tests with `uv run`, dependency management with `uv`, etc.).
+
+---
+
+## 3. `/issue-close` — land the work
+
+**When:** Implementation is done and you want to ship (commit, push, PR).
+
+**What you pass:** Optional notes (branch name, PR title, draft PR, or "skip issue doc update").
+
+**Typical steps the assistant follows:**
+
+1. **Sanity check** — e.g. `uv run pytest`, review the diff.
+2. **Issue folders** — update status markdown; use `- [x] Done` only when fully resolved. Move completed issue files from `{{ issueflows_dir }}/{{ current_issues_folder }}/` to `{{ issueflows_dir }}/{{ solved_folder }}/`, or partly done work to `{{ issueflows_dir }}/{{ partly_solved_folder }}/` (see project rules).
+3. **Commit** — focused staging and a clear message.
+4. **Push** — to your usual remote (e.g. `origin`).
+5. **Pull request** — open against the default branch; link the GitHub issue (`Closes #n` / `Refs #n`).
+6. **After review** — address comments, merge when ready.
+
+**Result:** Short summary of commit, push, and PR link (or what is blocked).
+
+---
+
+## End-to-end flow
+
+```text
+GitHub issue
+    │  /issue-init
+    ▼
+{{ issueflows_dir }}/{{ current_issues_folder }}/issueN_original.md  (+ optional status files)
+    │  /issue-start
+    ▼
+Code + tests (+ status updates during work)
+    │  /issue-close
+    ▼
+Commit → push → PR → merge
+    │
+    └── issue docs in {{ issueflows_dir }}/{{ solved_folder }}/ or {{ issueflows_dir }}/{{ partly_solved_folder }}/ when appropriate
+```
+
+The command definitions are the source of truth: `{{ cursor_dir }}/commands/issue-init.md`, `issue-start.md`, and `issue-close.md`. This document is a readable overview only.

issue_flow-0.1.0/src/issue_flow/templates/rules/issueflow-rules.mdc.j2

@@ -0,0 +1,86 @@
+---
+description: Issue-flow workflow rules for LLMs
+globs:
+alwaysApply: true
+---
+
+
+# Issue-flow best practices
+
+
+## Running python
+
+This is a python project. It uses a python environment (.venv) managed by uv.
+
+❌ BAD:
+```bash
+python run_script.py
+```
+
+✅ GOOD:
+```bash
+uv run run_script.py
+```
+
+### Package Management with `uv`
+
+**✅ Use `uv` exclusively**
+
+- All Python dependencies **must be installed, synchronized, and locked** using `uv`.
+- Never use `pip`, `pip-tools`, or `poetry` directly for dependency management.
+
+**🔁 Managing Dependencies**
+
+```bash
+# Add or upgrade dependencies
+uv add <package>
+
+# Remove dependencies
+uv remove <package>
+
+# Reinstall all dependencies from lock file
+uv sync
+```
+
+**🔁 Scripts**
+
+```bash
+# Run script with proper dependencies
+uv run script.py
+```
+
+
+## Issue tracking structure
+
+```bash
+{{ project_name }}/
+    {{ issueflows_dir }}/
+        {{ tools_folder }}/
+        {{ current_issues_folder }}/
+            issueXX_original.md
+            issueXX_status.md
+        {{ partly_solved_folder }}/
+        {{ solved_folder }}/
+    pyproject.toml
+    readme.md
+    ...
+```
+
+
+## Development information
+
+
+### Working on issues
+
+After each iteration, update the documents in `{{ issueflows_dir }}/{{ current_issues_folder }}` (should contain one file labelled `_original` that consists of the original issue description, and supplementary status files describing what has been done, current status, and remaining work).
+Use an explicit status checkbox in the status file:
+- `- [x] Done` when fully resolved
+- `- [ ] Done` when not fully resolved
+
+### When finishing an issue
+
+If the issue is fully resolved (no additional subtasks present), move the original and status markdown files to `{{ issueflows_dir }}/{{ solved_folder }}`. Else, move them to `{{ issueflows_dir }}/{{ partly_solved_folder }}`.
+
+### Scripts that can help us when working on issues
+
+If you want, you can put small scripts etc. that you have made and think could be useful in the future in our llm tools folder: `{{ issueflows_dir }}/{{ tools_folder }}`. Also, feel free to use the tools in our llm tools folder if you find someone that could be useful.

issue_flow-0.1.0/src/issue_flow/templating.py

@@ -0,0 +1,79 @@
+"""Jinja2 template loading and rendering for issue-flow."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+from jinja2 import Environment, BaseLoader, TemplateNotFound
+
+
+# ---------------------------------------------------------------------------
+# Custom loader that reads from the package's templates/ directory using
+# importlib.resources so it works whether the package is installed as a
+# directory, zip, or editable install.
+# ---------------------------------------------------------------------------
+
+_TEMPLATES_PACKAGE = "issue_flow.templates"
+
+
+class _PackageLoader(BaseLoader):
+    """Load Jinja2 templates shipped inside the issue_flow.templates package."""
+
+    def get_source(
+        self, environment: Environment, template: str
+    ) -> tuple[str, str, callable]:
+        # template is e.g. "commands/issue-init.md.j2"
+        parts = template.replace("\\", "/").split("/")
+        package = _TEMPLATES_PACKAGE + "." + ".".join(parts[:-1]) if len(parts) > 1 else _TEMPLATES_PACKAGE
+        filename = parts[-1]
+
+        try:
+            ref = resources.files(package).joinpath(filename)
+            source = ref.read_text(encoding="utf-8")
+        except (ModuleNotFoundError, FileNotFoundError, TypeError) as exc:
+            raise TemplateNotFound(template) from exc
+
+        # The third element is a callable that returns True if the template
+        # is still up-to-date (always True for packaged templates).
+        return source, template, lambda: True
+
+
+def get_environment() -> Environment:
+    """Return a configured Jinja2 environment that loads from the package."""
+    env = Environment(
+        loader=_PackageLoader(),
+        keep_trailing_newline=True,
+        trim_blocks=False,
+        lstrip_blocks=False,
+    )
+    return env
+
+
+def render_template(template_name: str, context: dict[str, str]) -> str:
+    """Render a single template by name and return the result string."""
+    env = get_environment()
+    template = env.get_template(template_name)
+    return template.render(context)
+
+
+# ---------------------------------------------------------------------------
+# Mapping of template name -> output path (relative to the project root).
+# The output path may itself contain Jinja-style placeholders, so we render
+# the path first.
+# ---------------------------------------------------------------------------
+
+# Each entry: (template_file, output_path_template)
+# The output_path_template uses simple str.format with the context dict.
+TEMPLATE_MANIFEST: list[tuple[str, str]] = [
+    ("commands/issue-init.md.j2", "{cursor_dir}/commands/issue-init.md"),
+    ("commands/issue-start.md.j2", "{cursor_dir}/commands/issue-start.md"),
+    ("commands/issue-close.md.j2", "{cursor_dir}/commands/issue-close.md"),
+    ("rules/issueflow-rules.mdc.j2", "{cursor_dir}/rules/issueflow-rules.mdc"),
+    ("docs/cursor-issue-workflow.md.j2", "{docs_dir}/cursor-issue-workflow.md"),
+]
+
+
+def resolve_output_path(path_template: str, context: dict[str, str]) -> Path:
+    """Resolve a path template like '{cursor_dir}/commands/foo.md' into a Path."""
+    return Path(path_template.format(**context))