issue-flow: Instructions file for Codex

AGENTS.md

Guidance for AI agents working in the issue-flow repository.

What this project is

issue-flow is a small Python CLI that scaffolds a lightweight, agent-friendly issue-tracking workflow into other projects. Running issue-flow init writes a .issueflows/ tracking tree plus editor skills, rules, and command files where the selected editor still needs them, so AI agents can pick up GitHub issues, plan work, and land PRs in a consistent way.

This repo is the tool itself — not a project that has been scaffolded by it.

• Package name: issue-flow (module issue_flow)
• Entry point: issue-flow = "issue_flow.cli:main"
• Requires Python 3.12+ (development pin: 3.13 in .python-version)
• Source of truth for scaffolded files: Jinja2 templates under src/issue_flow/templates/

Environment & tooling

This project uses a uv-managed virtual environment (.venv). Use uv exclusively for dependency management and running code — never pip, pip-tools, or poetry.

uv sync                 # install/refresh all deps from the lock file
uv add <package>        # add or upgrade a dependency
uv remove <package>     # remove a dependency
uv run <script.py>      # run a script with the right environment

❌ python run_script.py → ✅ uv run run_script.py

Common commands

uv run pytest                      # run the test suite
uv run ruff check src/ tests/      # lint
uv version --bump <part>           # bump version (used by /iflow-close)

Project layout

src/issue_flow/
  cli.py            # Typer CLI: init / update / graphify
  init.py           # scaffolding logic (writes .issueflows/ + .cursor/)
  config.py         # env-driven config (ISSUEFLOW_* vars, .env)
  dependencies.py   # external-CLI checks (git, gh)
  templating.py     # Jinja2 rendering helpers
  graphify.py       # optional graphify integration
  migrate.py        # one-shot migrations `update` applies to older scaffolds
  templates/        # Jinja2 templates for all scaffolded output
    commands/         # thin command wrapper (editors with a commands dir)
    skills/           # Agent Skills: SKILL.md router + mode files per command
    rules/            # always-on rule body (AGENTS.md block) + pointers
tests/              # pytest suite