Skip to content

AGENTS.md

Latest commit

 

History

History
319 lines (205 loc) · 22.3 KB

AGENTS.md

File metadata and controls

319 lines (205 loc) · 22.3 KB
Raw

Issue-flow best practices

Running python

Respect the project's existing toolchain first. If this project already documents how to run Python and manage dependencies — in its README, AGENTS.md, CLAUDE.md, .cursor/rules, environment.yml, pyproject.toml, Makefile, CI config, etc. — follow that, even where it conflicts with the defaults below. These rules describe issue-flow's default assumptions, not a mandate to override a project that has already chosen differently.

The one tool-neutral principle: don't call bare python ... — invoke Python through the project's environment (its runner, or an activated virtualenv/conda env) so scripts and tests see the right interpreter and dependencies.

If the project uses conda

When the project documents a conda environment, run all Python commands — scripts and pytest — inside the activated conda environment. Do not substitute uv run.

# Either activate the environment first…
conda activate <env-name>
python run_script.py
pytest

# …or run one-off commands inside it:
conda run -n <env-name> pytest

If the project uses uv (issue-flow's default)

For projects scaffolded fresh (and this is the default when nothing else is documented), use uv:

# ❌ BAD: bare interpreter
python run_script.py

# ✅ GOOD: through uv
uv run run_script.py

Package management with uv

  • Install, synchronize, and lock dependencies with uv; don't reach for pip, pip-tools, or poetry in a uv-managed project.
# Add or upgrade dependencies
uv add <package>

# Remove dependencies
uv remove <package>

# Reinstall all dependencies from the lock file
uv sync

# Run a script with the right environment
uv run script.py

Other toolchains (plain venv / pip / poetry)

If the project uses something else, use whatever it documents (e.g. activate its .venv and use pip, or run poetry run). Match the project; don't force uv.

Issue tracking structure

cellpy/
    .issueflows/
        00-tools/
        01-current-issues/
            issueXX_original.md
            issueXX_status.md
        02-partly-solved-issues/
        03-solved-issues/
        04-designs-and-guides/
        05-epics/
            epicXX_plan.md
    pyproject.toml
    readme.md
    ...

Development information

Working on issues

After each iteration, update the documents in .issueflows/01-current-issues (should contain one file labelled _original with the original issue description, a _plan file with the confirmed approach, 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

Chat invocation (no slash)

On keyboard layouts where / and @ are awkward to type (for example Norwegian), invoke lifecycle skills in chat without special keys.

Primary form: iflow <step> (space-separated) — e.g. iflow plan, iflow pick, iflow close. Plain iflow runs the smart dispatcher.

Also recognized (same obligation as slash-menu invocation): hyphen form (iflow-plan), slash form (/iflow-plan), slash + space (/iflow plan).

When the user message is exactly one of these forms, or starts with it followed by a space and trailing arguments, read and follow the matching skill immediately. Forward trailing text verbatim (e.g. iflow pick fix → iflow-pick with arg fix). Do not treat incidental mid-sentence mentions as commands — the message must start with the invocation.

Chat / slash form Skill
iflow / /iflow iflow (dispatcher)

| iflow archive, iflow-archive, /iflow-archive, /iflow archive | iflow-archive |

| iflow auto, iflow-auto, /iflow-auto, /iflow auto | iflow-auto |

| iflow build, iflow-build, /iflow-build, /iflow build | iflow-build |

| iflow cleanup, iflow-cleanup, /iflow-cleanup, /iflow cleanup | iflow-cleanup |

| iflow close, iflow-close, /iflow-close, /iflow close | iflow-close |

| iflow cycle, iflow-cycle, /iflow-cycle, /iflow cycle | iflow-cycle |

| iflow doctor, iflow-doctor, /iflow-doctor, /iflow doctor | iflow-doctor |

| iflow epic, iflow-epic, /iflow-epic, /iflow epic | iflow-epic |

| iflow fix, iflow-fix, /iflow-fix, /iflow fix | iflow-fix |

| iflow graphify, iflow-graphify, /iflow-graphify, /iflow graphify | iflow-graphify |

| iflow init, iflow-init, /iflow-init, /iflow init | iflow-init |

| iflow issue, iflow-issue, /iflow-issue, /iflow issue | iflow-issue |

| iflow pause, iflow-pause, /iflow-pause, /iflow pause | iflow-pause |

| iflow pick, iflow-pick, /iflow-pick, /iflow pick | iflow-pick |

| iflow plan, iflow-plan, /iflow-plan, /iflow plan | iflow-plan |

| iflow review, iflow-review, /iflow-review, /iflow review | iflow-review |

| iflow status, iflow-status, /iflow-status, /iflow status | iflow-status |

| iflow yolo, iflow-yolo, /iflow-yolo, /iflow yolo | iflow-yolo |

Skill @ attachment is supported on some editors but is not the recommended keyboard-friendly path.

Command lifecycle

If you have not chosen an issue yet, run /iflow-pick (or type iflow pick in chat) — the front door that helps you select the next issue (parked work first, else ranked open GitHub issues), creates the branch, and runs /iflow-init. It is off-path (never auto-dispatched).

If you just want the next right step, run /iflow (or type iflow in chat) — it detects state (by file presence under .issueflows/01-current-issues/ and the status-file - [x] Done marker) and dispatches to /iflow-init, /iflow-plan, /iflow-build, or /iflow-close. It never auto-dispatches to /iflow-pick, /iflow-pause, /iflow-cleanup, or /iflow-yolo — those stay explicit.

The full slash-command lifecycle is:

  1. /iflow-init — capture the GitHub issue as issue<N>_original.md.
  2. /iflow-plan — design the approach in issue<N>_plan.md and get explicit confirmation before any code changes.
  3. /iflow-build — implement the confirmed plan. Asks to run /iflow-plan first if the plan file is missing.
  4. /iflow-pause (optional) — park work mid-stream: update status, move the issue group to 02-partly-solved-issues, optional WIP commit.
  5. /iflow-close — tests, optional uv version --bump, changelog/HISTORY.md update (in the PR commit), status update, commit, push, PR. Does not delete branches. Never offer a HISTORY/CHANGELOG update after close finishes or after merge; use nohistory only to skip intentionally. (A draft opened earlier via /iflow-build early PR does not skip the close HISTORY step.)
  6. /iflow-cleanup — post-merge: switch to default, git pull --ff-only, git fetch --prune, git branch -d on merged local branches under a single consolidated confirm. Never -D. Trailing include GitHub (or similar) adds a remote-branch audit with a second confirm for optional remote deletes / findings issue.

/iflow-yolo chains init → plan → build → close yolo for small, low-risk issues with up-front safeguards (clean tree, passing tests, single consolidated confirm). Its close step is hands-off: changelog decided without a prompt, PR merged (gh pr merge --squash; on pending checks may gh pr checks --watch then retry, with --auto as last resort), then default-branch switch + pull.

Issue labels can select the flow: when an issue picked via /iflow-pick carries the yolo label, it is routed through /iflow-yolo (one combined confirmation). Controlled by label_flows (default true) and yolo_label (default "yolo") under [issueflow] in .issueflows/config.toml; re-run issue-flow update after changing them.

Lifecycle skills include a ### MODEL & EXECUTION DIRECTIVE section that tells agents whether to prioritize economy (speed) or reasoning (depth) for that step. Toggle with step_directives under [issueflow]; override per step via [issueflow.step_profiles]; optional label hints during /iflow-pick via model_label_flows, deep_model_label, and fast_model_label. Re-run issue-flow update after changing any of these.

/iflow-fix opens an interactive iterative-fixes session: it creates one GitHub issue + long-lived branch, then loops over many small fixes (each gets a short plan and is implemented only on confirmation, recorded as a dated bullet in issue<N>_status.md), and ends with /iflow-close. It is off-path (never auto-dispatched); while a session is active, drive it with /iflow-fix + /iflow-close, not /iflow.

/iflow-issue creates one well-specified normal GitHub issue (context / spec / acceptance criteria), then optionally branches and runs /iflow-init into the standard lifecycle. It fills the gap between /iflow-fix (iterative small-fixes) and /iflow-epic (multi-issue staged work). Off-path (never auto-dispatched). For an epic anchor: /iflow-issue epic <intent>.

/iflow-status prints a read-only overview of where every issue stands — the local tracking state under .issueflows/ (focus / parked / solved) plus open GitHub issues cross-referenced against it. It is off-path (never auto-dispatched) and changes nothing.

/iflow-doctor audits .issueflows/ for dirty conditions (ambiguous multi-focus, leftovers in 01-current-issues/, duplicates across folders, and similar) and can apply safe repairs on confirmation (issue-flow doctor / agent audit + repair). It is off-path and never auto-dispatched.

/iflow-review reviews open GitHub issues and applies labels (extendable kinds; v1: yolo → configured yolo_label). Off-path; consolidated confirm before any label create/apply; never auto-dispatched. CLI helpers: issue-flow agent label-candidates / label-apply.

/iflow-epic <N> plans a change too large for one issue as a staged epic: it drafts .issueflows/05-epics/epic<N>_plan.md (anchored to GitHub issue <N>), dividing the work into sequential stages of manageable issue specs with explicit dependencies and a per-issue yolo-fitness judgment. Drafting writes nothing on GitHub; /iflow-epic <N> publish [stage <k>] creates a confirmed stage's issues behind one consolidated confirm (yolo labels per the recorded judgment, task list maintained on the anchor issue, Published: #<M> recorded back into the plan so re-runs are idempotent). Off-path (never auto-dispatched); epics decompose into the normal single-issue lifecycle, never around it.

/iflow-cycle <queue-spec> processes many issues hands-off in a row under a single up-front confirmation — the batch equivalent of /iflow-yolo. It resolves a queue via issue-flow agent queue (explicit numbers, label:<L>, or epic <N> [stage <k>]), then runs each issue through the full yolo chain (PR auto-merged), interrupting you only when input is strictly necessary (unfixable failure, refused merge / non-fast-forward pull, ambiguous or not-actually-small spec, or anything outside the confirmed queue). It stops the whole cycle on the first such condition, leaving the repo clean on the default branch. All yolo-labelled issues: /iflow-cycle yolo (alias for label:yolo). Off-path (never auto-dispatched); never weakens a yolo safeguard to keep moving.

/iflow-auto <N> runs an unattended large-change path over a confirmed epic: select a stage, drive it via /iflow-cycle, record auto_status.md, then adversarial inter-epoch review (review token; may reopen/create issues under the overnight confirm). On findings, honour the loop budget (re-queue + re-review, or stop and ask: accept / grant N more loops / abort). Advance to stage k+1 only when stage k is clear (epic-status done + no open blockers); otherwise epoch_gated. Budget baked as 2 (loops:<n> overrides). Off-path (never auto-dispatched). See .issueflows/04-designs-and-guides/advanced-auto-mode.md.

/iflow-archive condenses old solved issue groups under .issueflows/03-solved-issues/ into a single dated YYYY-MM-DD_archived_issues.md summary file (recording the pre-archive git ref for recovery via git show <ref>:<path>), then deletes the original issue<N>_* files. It is off-path and destructive: nothing is deleted before one consolidated confirmation.

On tools without project slash commands (e.g. Codex CLI), invoke the mirrored Agent Skills instead (for example iflow-init in place of /iflow-init).

When finishing an issue

If the issue is fully resolved (no additional subtasks present), move the original, plan, and status markdown files to .issueflows/03-solved-issues. Else, move them to .issueflows/02-partly-solved-issues.

Scripts that can help us when working on issues

.issueflows/00-tools/ is the project's durable toolbox of reusable helper scripts, with a README.md index describing each one.

  • Check it first. Before writing a new one-off helper for an issue, skim the 00-tools/README.md index and the folder — a suitable tool may already exist.
  • Contribute back. If you build something during an issue that could help on a future one, save it into .issueflows/00-tools/ and add a one-line entry to the index (name, what it does, when to use it) so the next agent knows whether to reach for it.

Optional response styles

A caveman Agent Skill is installed under .cursor/skills/caveman/. It is a terse, "token-greedy" response style that keeps all technical substance while dropping filler, articles, and pleasantries. It is off by default and only kicks in when the user asks for it (e.g. "caveman", "token greedy", "be terse"). Turn it off with "stop caveman" or "normal mode". Code, commits, PRs, security warnings, and destructive-action confirmations are always written in normal prose, never caveman. (To make caveman on by default for this project, set caveman_default = true under [issueflow] in .issueflows/config.toml and re-run issue-flow update.)

Planning aids

A grill-me Agent Skill is installed under .cursor/skills/grill-me/. It runs a relentless planning interview that stress-tests a plan or design — one question at a time, each with a recommended answer — until every branch of the decision tree is resolved. It is off by default and only kicks in when you ask for it (e.g. "grill me", "poke holes in this"). Turn it off with "stop grilling" or "normal mode". (To make grilling on by default during planning for this project, set grill_me_default = true under [issueflow] in .issueflows/config.toml and re-run issue-flow update.)

Designs and guides

Long-lived design docs, design decisions, and project "good practices" live under .issueflows/04-designs-and-guides/. Unlike the issue folders, content here is not tied to a single issue and is not archived when an issue closes — it is the project's durable memory.

  • Project brief: if .issueflows/04-designs-and-guides/this-project.md exists, read it early for project-specific context (what the repo is, stack/runtime, how to run/test, conventions, entry points, and known limitations).
  • Before planning or implementing, skim .issueflows/04-designs-and-guides/ for existing docs relevant to the current issue and follow them (cite them in the plan when they influence the approach).
  • When a non-trivial design decision is made during /iflow-plan or /iflow-build, add or update a markdown file here. Keep entries terse: context, the decision, alternatives considered, and a link back to the issue.
  • Never overwritten by issue-flow update. The folder is recreated if missing, but existing files are left alone.

Multi-root workspaces

When an editor workspace contains multiple sibling repositories, each with its own .issueflows/ scaffold:

  • Resolve the target repo first — explicit root: / repo: hints, then issue-flow agent resolve, then branch/single-scaffold heuristics, then the workspace default from issueflow-workspace.toml at the workspace root (create it with issue-flow workspace init); ask when still ambiguous. Never let git or gh infer the repo from cwd alone.
  • Scoped rules — this repo's issueflow-rules apply under this project root only (path globs). Put toolchain-specific run/test commands in .issueflows/04-designs-and-guides/this-project.md, not in shared boilerplate that every repo merges.
  • Per-repo lifecycle — /iflow-cleanup, branch hygiene, and focus issue folders are per repository; repeat commands in each repo when needed.
  • Design doc — see .issueflows/04-designs-and-guides/multi-repo-workspaces.md when present (issue #67).

Branch hygiene

  • Do issue work on an issue branch named like <N>-<short-slug>, not on the default branch.

  • Before starting or continuing work on an issue branch, run git fetch --prune and check where the branch sits relative to origin/<default> (ahead/behind). A branch that is "several commits ahead" after a merged PR usually means the PR was merged (this project uses squash) and the local branch is stale.

  • Assume squash merges on GitHub. After a PR merges: run /iflow-cleanup — it switches to the default branch, runs git pull --ff-only, git fetch --prune, and deletes merged local branches with git branch -d <branch> under a single consolidated confirm (never -D automatically). /iflow-close no longer does this step itself.

  • If an issue is already archived under .issueflows/02-partly-solved-issues or .issueflows/03-solved-issues, the matching local branch is stale; don't resume work on it silently — switch back to the default branch and, if the issue really needs re-opening, do it deliberately through /iflow-init (which will ask for a second confirmation).

Folder hygiene for .issueflows/01-current-issues

  • Only the focus issue (the one currently being worked on) should live in .issueflows/01-current-issues.
  • /iflow-init and /iflow-build both sweep that folder automatically: every issue<n>_* group other than the focus issue is moved to .issueflows/03-solved-issues if a status file contains - [x] Done, otherwise to .issueflows/02-partly-solved-issues. Keep status files accurate so the sweep routes them correctly.

Knowledge graph (optional, via graphify)

If a graphify-out/ folder exists in the project root, the project has the optional graphify integration enabled and a knowledge graph is available alongside the source.

  • Before grepping, skim graphify-out/GRAPH_REPORT.md. It surfaces god-nodes (most-connected concepts), surprising cross-module connections, and suggested questions the graph can answer — often a faster way to locate the files an issue actually touches than full-text search.
  • /iflow-graphify (slash command) or issue-flow graphify (CLI) rebuild the graph. With no extra args this runs graphify update <project> — AST-only, no LLM API key needed. For richer semantic relationships (cross-file links surfaced by an LLM pass), run issue-flow graphify extract after setting GEMINI_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY / MOONSHOT_API_KEY (or pass --backend ollama for a local LLM). Other subcommands: watch (live), cluster-only --no-viz (re-cluster). Trailing flags pass through verbatim. Your agent's own LLM cannot be reused by subprocesses; graphify needs its own backend.
  • /iflow-graphify is off-path: never auto-dispatched by /iflow, /iflow-build, or /iflow-close. It is the user's call. /iflow-build may suggest skimming GRAPH_REPORT.md; /iflow-close may suggest a rebuild after large structural changes — neither runs graphify automatically.
  • If graphify-out/ is not present, ignore graph-related guidance entirely. The integration is opt-in (install with uv tool install graphifyy, then issue-flow update to register the graphify skill).

Cursor Cloud specific instructions

Environment is already provisioned on cloud VM startup: uv (on PATH via ~/.local/bin), the mdbtools system package (needed to read Arbin .mdb/.res files on Linux), and the startup update script runs uv sync, which installs Python 3.13 and the project + dev dependency group from uv.lock (cellpycore resolves from PyPI). No manual install is normally needed.

  • Product: cellpy is a Python library + cellpy CLI for battery/cell cycling data (no web/GUI server; cellpy serve only launches Jupyter). There is nothing long-running to "start" — you exercise it via the CLI or by importing the library.
  • Run everything through uv run (e.g. uv run cellpy ..., uv run pytest, uv run python ...) so the .venv interpreter and deps are used. Standard commands are in CONTRIBUTING.md, .github/workflows/ci.yml, and pyproject.toml.
  • Tests: uv run pytest -m essential is the fast CI merge gate. Plotting tests run under MPLBACKEND=Agg (no file --ignore in Tier 1 / scheduled / release). Full suite is uv run pytest (default addopts deselects slow/local/unfinished markers).
  • Lint/format: uv run flake8 cellpy and uv run black --check cellpy (line length 120). These are not wired into the Tier-1 CI gate, and the repo currently has pre-existing black reformat suggestions and some flake8 F821 findings — do not treat those as regressions from your change.
  • Build: uv build (hatchling; version derived from git tags via uv-dynamic-versioning, so a shallow/tagless checkout reports a 0.0.0-style dev version — harmless for dev).
  • CLI smoke check: uv run cellpy setup --silent then uv run cellpy info --check. cellpy setup writes a runtime .env_cellpy in the repo root and a ~/.cellpy_prms_*.conf in $HOME — these are local runtime files, do not commit them.
  • Example data (cellpy.utils.example_data, e.g. raw_file()) downloads small fixtures from GitHub on first use, so those helpers need network access.
  • Dual-repo dev with a sibling ../cellpy-core checkout is optional (see CONTRIBUTING.md): uv sync --no-sources then uv pip install -e ../cellpy-core. The default uv sync uses the PyPI cellpycore pin and is sufficient for most work.