From 820c13f052b2f4c3661eb138e27b12f1dc174411 Mon Sep 17 00:00:00 2001 From: jepegit Date: Sun, 19 Apr 2026 22:50:53 +0200 Subject: [PATCH 1/2] Add designs-and-guides folder and update related commands - Introduced a new folder `.issueflows/04-designs-and-guides/` for long-lived design documents, decisions, and good practices. - Updated slash commands (`/iflow`, `/issue-plan`, `/issue-start`, `/issue-close`, `/issue-yolo`) to reference this new folder, encouraging users to consult and document design decisions. - Enhanced the issue-flow rules to include guidance on the new folder's purpose and usage. - Added tests to ensure the folder is created and preserved during initialization and updates, and that commands correctly reference it. This change improves project documentation and consistency in design practices. Closes #26 Made-with: Cursor --- .cursor/commands/iflow.md | 2 ++ .cursor/commands/issue-close.md | 1 + .cursor/commands/issue-plan.md | 4 ++- .cursor/commands/issue-start.md | 1 + .cursor/commands/issue-yolo.md | 2 ++ .cursor/rules/issueflow-rules.mdc | 10 ++++++ .../01-current-issues/issue26_original.md | 12 +++++++ .../01-current-issues/issue26_status.md | 32 +++++++++++++++++++ .issueflows/04-designs-and-guides/.gitkeep | 0 src/issue_flow/config.py | 3 ++ src/issue_flow/templates/commands/iflow.md.j2 | 2 ++ .../templates/commands/issue-close.md.j2 | 1 + .../templates/commands/issue-plan.md.j2 | 4 ++- .../templates/commands/issue-start.md.j2 | 1 + .../templates/commands/issue-yolo.md.j2 | 2 ++ .../templates/rules/issueflow-rules.mdc.j2 | 10 ++++++ tests/test_config.py | 4 ++- tests/test_init.py | 25 ++++++++++++++- tests/test_update.py | 28 ++++++++++++++++ 19 files changed, 140 insertions(+), 4 deletions(-) create mode 100644 .issueflows/01-current-issues/issue26_original.md create mode 100644 .issueflows/01-current-issues/issue26_status.md create mode 100644 .issueflows/04-designs-and-guides/.gitkeep diff --git a/.cursor/commands/iflow.md b/.cursor/commands/iflow.md index bb508de..299686a 100644 --- a/.cursor/commands/iflow.md +++ b/.cursor/commands/iflow.md @@ -4,6 +4,8 @@ Off-path commands (`/issue-pause`, `/issue-cleanup`, `/issue-yolo`) are **not** auto-dispatched. Invoke them directly when you need them. +Long-lived design docs, design decisions, and project good-practices live under `.issueflows/04-designs-and-guides/`. The downstream commands (`/issue-plan`, `/issue-start`, `/issue-close`) read from and add to that folder as they run; `/iflow` itself does not touch it. + ## Input Optional free-form text after the command. `/iflow` forwards the raw trailing text to whichever command it dispatches to. Examples: diff --git a/.cursor/commands/issue-close.md b/.cursor/commands/issue-close.md index 076a0ab..d5eb878 100644 --- a/.cursor/commands/issue-close.md +++ b/.cursor/commands/issue-close.md @@ -21,6 +21,7 @@ Other optional notes still apply: branch name, PR title, draft PR, skip issue do 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. + - Confirm that any design decisions or good-practices that emerged from this issue are captured under `.issueflows/04-designs-and-guides/` before committing. If something is missing, add it now (short markdown: context, decision, alternatives, link back to the issue). 2. **Optional version bump** (only if the user asked for it in the command input) - Read `.cursor/skills/issueflow-version-bump/SKILL.md` and follow it. diff --git a/.cursor/commands/issue-plan.md b/.cursor/commands/issue-plan.md index 8c15fac..f843486 100644 --- a/.cursor/commands/issue-plan.md +++ b/.cursor/commands/issue-plan.md @@ -21,6 +21,8 @@ Optional free-form text after the command. Examples: 1. **Read the issue.** Load `issue_original.md` and any existing `issue_status.md`. Do not rewrite them from this command. +1.5 **Consult existing designs / guides.** Skim `.issueflows/04-designs-and-guides/` for design docs, design decisions, or documented good practices that touch the area you're about to plan. When relevant docs exist, cite them in the plan so the approach stays consistent with prior decisions. + 2. **Explore, then propose.** Do enough read-only research (search, read files, check existing tests) to design the change. Keep it proportional to the issue — small fix = short plan. 3. **Write `issue_plan.md`** in `.issueflows/01-current-issues/` with these sections: @@ -49,7 +51,7 @@ Optional free-form text after the command. Examples: - Anything that needs the user's call before coding. ``` - Keep it terse but specific. Link to files with markdown links when helpful. + Keep it terse but specific. Link to files with markdown links when helpful. If the plan expects to **produce** a design doc / decision record under `.issueflows/04-designs-and-guides/`, call that out explicitly (e.g. in **Files to touch**) so `/issue-start` knows to create it. 4. **Scope check.** If the plan is broad (many unrelated files, several independent deliverables, or mixes refactors with feature work), **propose splitting** into smaller issues or phased PRs and ask the user before continuing. diff --git a/.cursor/commands/issue-start.md b/.cursor/commands/issue-start.md index 3b3b685..82368d6 100644 --- a/.cursor/commands/issue-start.md +++ b/.cursor/commands/issue-start.md @@ -39,6 +39,7 @@ If additional input is added, use that as implementation hints (scope, constrain Wait for an explicit choice. On **(a)**, run the `/issue-plan` flow first (including its user-confirmation stop), then return here. On **(b)**, add a short `- Skipped /issue-plan on ` note to `issue_status.md` and continue. On **(c)**, stop. 2. **Implement** the plan. Prefer minimal, focused diffs. Match existing code style and tooling. Follow project rules under `.cursor/rules/issueflow-rules.mdc` (e.g. `uv run` for Python, `uv add` / `uv remove` / `uv sync` for dependencies). + - **Designs and guides.** Read any relevant files under `.issueflows/04-designs-and-guides/` before making non-trivial decisions. When the work produces a new design decision or establishes a project good-practice (one the plan flagged, or one that only became clear during implementation), add or update a short markdown file under `.issueflows/04-designs-and-guides/`: context, the decision, alternatives considered, and a link back to this issue. Keep it terse. 3. **Update the status file.** After meaningful progress, update (or create) `issue_status.md` under `.issueflows/01-current-issues/` with a `- [ ] Done` checkbox that stays unchecked until fully resolved. Record what has landed and what remains so `/issue-pause` or `/issue-close` has accurate context. diff --git a/.cursor/commands/issue-yolo.md b/.cursor/commands/issue-yolo.md index c5c50e5..e134ebf 100644 --- a/.cursor/commands/issue-yolo.md +++ b/.cursor/commands/issue-yolo.md @@ -4,6 +4,8 @@ Chains `/issue-init` → `/issue-plan` → `/issue-start` → `/issue-close` in For anything non-trivial, use the individual commands so you get confirmation checkpoints. +The chained commands still consult and update `.issueflows/04-designs-and-guides/` (design docs, decisions, good practices) — but if a yolo run uncovers a decision worth recording, that alone is usually a signal the change is **not** small enough for `/issue-yolo`: consider aborting and running the commands individually. + ## Input Same as `/issue-init` (issue number, URL, or empty to infer from the branch). Optional extra tokens are forwarded to the downstream commands: diff --git a/.cursor/rules/issueflow-rules.mdc b/.cursor/rules/issueflow-rules.mdc index e6253ae..0141eae 100644 --- a/.cursor/rules/issueflow-rules.mdc +++ b/.cursor/rules/issueflow-rules.mdc @@ -61,6 +61,7 @@ issue-flow/ issueXX_status.md 02-partly-solved-issues/ 03-solved-issues/ + 04-designs-and-guides/ pyproject.toml readme.md ... @@ -101,6 +102,15 @@ If the issue is fully resolved (no additional subtasks present), move the origin 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/00-tools`. Also, feel free to use the tools in our llm tools folder if you find someone that could be useful. +### 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. + +- **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 `/issue-plan` or `/issue-start`, 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. + + ### Branch hygiene - Do issue work on an **issue branch** named like `-`, not on the default branch. diff --git a/.issueflows/01-current-issues/issue26_original.md b/.issueflows/01-current-issues/issue26_original.md new file mode 100644 index 0000000..3f2eb60 --- /dev/null +++ b/.issueflows/01-current-issues/issue26_original.md @@ -0,0 +1,12 @@ +# Issue #26: create a new folder for storing designs and design decissions + +Source: https://github.com/jepegit/issue-flow/issues/26 + +## Original issue text + +We need an additional folder in `.issueflows` for storing designs and design decisions, as well as what the project decides are good practices. + +Tasks + +1. Implement the creation of the folder (during issue-flow init) and make sure it is not overwritten during issue-flow update +2. Update the relevant slash commands to encourage updating / adding documents to the folder, as well as using the documentation when planning and implementing solutions to issues. diff --git a/.issueflows/01-current-issues/issue26_status.md b/.issueflows/01-current-issues/issue26_status.md new file mode 100644 index 0000000..22a4ea1 --- /dev/null +++ b/.issueflows/01-current-issues/issue26_status.md @@ -0,0 +1,32 @@ +# Issue #26 status: designs-and-guides folder + +- [x] Done + +## Done so far + +- Added `designs_folder = "04-designs-and-guides"` to `Settings` in `src/issue_flow/config.py`; included in `issueflows_subdirs` and `template_context` so the existing `_create_issueflow_dirs` loop picks it up on both `init` and `update`. No changes needed to `src/issue_flow/init.py`. +- Updated the rule template `src/issue_flow/templates/rules/issueflow-rules.mdc.j2`: added the new folder to the Issue-tracking structure tree and a new "Designs and guides" section describing purpose, when to read it, when to write it, and that `issue-flow update` never overwrites its contents. +- Updated slash-command templates to reference `{{ issueflows_dir }}/{{ designs_folder }}/`: + - `commands/issue-plan.md.j2` — new step 1.5 "Consult existing designs / guides" and a Files-to-touch reminder when the plan expects to produce a design doc. + - `commands/issue-start.md.j2` — sub-bullet in step 2 Implement to read relevant designs and record new design decisions. + - `commands/issue-close.md.j2` — sanity-check bullet to confirm design decisions are captured before committing. + - `commands/iflow.md.j2` — one-paragraph header noting the folder and that downstream commands touch it. + - `commands/issue-yolo.md.j2` — note that if a yolo run uncovers a design decision worth recording, the change is probably too big for yolo. +- Added tests: + - `tests/test_init.py` — extended `test_init_creates_directories` and `test_init_creates_gitkeep_files`, plus new `test_init_rule_documents_designs_folder` and `test_init_commands_reference_designs_folder`. + - `tests/test_update.py` — new `test_update_preserves_designs_folder_contents` and `test_update_recreates_removed_designs_folder`. + - `tests/test_config.py` — updated `test_issueflows_subdirs` count (4 -> 5) and `test_template_context_keys` to include `designs_folder`. +- Ran `uv run issue-flow update` in this repo to refresh the in-repo scaffold files so `.cursor/rules/issueflow-rules.mdc`, `.cursor/commands/*.md`, and `.cursor/skills/*` pick up the new wording, and created `.issueflows/04-designs-and-guides/.gitkeep`. +- `uv run pytest`: 68 passed, 0 failed. +- Manual verification in a scratch directory: `init` creates the folder; user content in it survives `update`; deleting the folder and running `update` recreates it with `.gitkeep`. + +## Remaining work + +Both tasks from the original issue are implemented: +1. Folder is created during `issue-flow init` (via `_create_issueflow_dirs` / `issueflows_subdirs`) and preserved by `issue-flow update` (user files are never manifest outputs; the folder is only recreated if missing). +2. The rule and the relevant slash commands now encourage reading from and adding to the folder. + +## Deferred (not in this issue's scope) + +- `docs/cursor-issue-workflow.md.j2` (public workflow overview) and the `skills/` templates under `src/issue_flow/templates/skills/` were intentionally left out of scope per the plan. They will drift slightly from the commands until updated in a follow-up. +- No dedicated `ISSUEFLOW_DESIGNS_DIR` env var was added; the folder name is a plain constant on `Settings` (same pattern as `tools_folder`, `current_issues_folder`, etc.). Easy to flip later if desired. diff --git a/.issueflows/04-designs-and-guides/.gitkeep b/.issueflows/04-designs-and-guides/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/issue_flow/config.py b/src/issue_flow/config.py index d804d5f..a13c6fb 100644 --- a/src/issue_flow/config.py +++ b/src/issue_flow/config.py @@ -44,6 +44,7 @@ class Settings: 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]: @@ -52,6 +53,7 @@ def issueflows_subdirs(self) -> list[str]: self.current_issues_folder, self.partly_solved_folder, self.solved_folder, + self.designs_folder, ] def template_context(self, project_root: Path) -> dict[str, str]: @@ -66,6 +68,7 @@ def template_context(self, project_root: Path) -> dict[str, str]: "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, } diff --git a/src/issue_flow/templates/commands/iflow.md.j2 b/src/issue_flow/templates/commands/iflow.md.j2 index 2d6f328..8a6c980 100644 --- a/src/issue_flow/templates/commands/iflow.md.j2 +++ b/src/issue_flow/templates/commands/iflow.md.j2 @@ -4,6 +4,8 @@ Off-path commands (`/issue-pause`, `/issue-cleanup`, `/issue-yolo`) are **not** auto-dispatched. Invoke them directly when you need them. +Long-lived design docs, design decisions, and project good-practices live under `{{ issueflows_dir }}/{{ designs_folder }}/`. The downstream commands (`/issue-plan`, `/issue-start`, `/issue-close`) read from and add to that folder as they run; `/iflow` itself does not touch it. + ## Input Optional free-form text after the command. `/iflow` forwards the raw trailing text to whichever command it dispatches to. Examples: diff --git a/src/issue_flow/templates/commands/issue-close.md.j2 b/src/issue_flow/templates/commands/issue-close.md.j2 index 4b1f342..bea55af 100644 --- a/src/issue_flow/templates/commands/issue-close.md.j2 +++ b/src/issue_flow/templates/commands/issue-close.md.j2 @@ -21,6 +21,7 @@ Other optional notes still apply: branch name, PR title, draft PR, skip issue do 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. + - Confirm that any design decisions or good-practices that emerged from this issue are captured under `{{ issueflows_dir }}/{{ designs_folder }}/` before committing. If something is missing, add it now (short markdown: context, decision, alternatives, link back to the issue). 2. **Optional version bump** (only if the user asked for it in the command input) - Read `{{ agent_dir }}/skills/issueflow-version-bump/SKILL.md` and follow it. diff --git a/src/issue_flow/templates/commands/issue-plan.md.j2 b/src/issue_flow/templates/commands/issue-plan.md.j2 index 625deb0..e7d27ef 100644 --- a/src/issue_flow/templates/commands/issue-plan.md.j2 +++ b/src/issue_flow/templates/commands/issue-plan.md.j2 @@ -21,6 +21,8 @@ Optional free-form text after the command. Examples: 1. **Read the issue.** Load `issue_original.md` and any existing `issue_status.md`. Do not rewrite them from this command. +1.5 **Consult existing designs / guides.** Skim `{{ issueflows_dir }}/{{ designs_folder }}/` for design docs, design decisions, or documented good practices that touch the area you're about to plan. When relevant docs exist, cite them in the plan so the approach stays consistent with prior decisions. + 2. **Explore, then propose.** Do enough read-only research (search, read files, check existing tests) to design the change. Keep it proportional to the issue — small fix = short plan. 3. **Write `issue_plan.md`** in `{{ issueflows_dir }}/{{ current_issues_folder }}/` with these sections: @@ -49,7 +51,7 @@ Optional free-form text after the command. Examples: - Anything that needs the user's call before coding. ``` - Keep it terse but specific. Link to files with markdown links when helpful. + Keep it terse but specific. Link to files with markdown links when helpful. If the plan expects to **produce** a design doc / decision record under `{{ issueflows_dir }}/{{ designs_folder }}/`, call that out explicitly (e.g. in **Files to touch**) so `/issue-start` knows to create it. 4. **Scope check.** If the plan is broad (many unrelated files, several independent deliverables, or mixes refactors with feature work), **propose splitting** into smaller issues or phased PRs and ask the user before continuing. diff --git a/src/issue_flow/templates/commands/issue-start.md.j2 b/src/issue_flow/templates/commands/issue-start.md.j2 index d515654..81bcca7 100644 --- a/src/issue_flow/templates/commands/issue-start.md.j2 +++ b/src/issue_flow/templates/commands/issue-start.md.j2 @@ -39,6 +39,7 @@ If additional input is added, use that as implementation hints (scope, constrain Wait for an explicit choice. On **(a)**, run the `/issue-plan` flow first (including its user-confirmation stop), then return here. On **(b)**, add a short `- Skipped /issue-plan on ` note to `issue_status.md` and continue. On **(c)**, stop. 2. **Implement** the plan. Prefer minimal, focused diffs. Match existing code style and tooling. Follow project rules under `{{ agent_dir }}/rules/issueflow-rules.mdc` (e.g. `uv run` for Python, `uv add` / `uv remove` / `uv sync` for dependencies). + - **Designs and guides.** Read any relevant files under `{{ issueflows_dir }}/{{ designs_folder }}/` before making non-trivial decisions. When the work produces a new design decision or establishes a project good-practice (one the plan flagged, or one that only became clear during implementation), add or update a short markdown file under `{{ issueflows_dir }}/{{ designs_folder }}/`: context, the decision, alternatives considered, and a link back to this issue. Keep it terse. 3. **Update the status file.** After meaningful progress, update (or create) `issue_status.md` under `{{ issueflows_dir }}/{{ current_issues_folder }}/` with a `- [ ] Done` checkbox that stays unchecked until fully resolved. Record what has landed and what remains so `/issue-pause` or `/issue-close` has accurate context. diff --git a/src/issue_flow/templates/commands/issue-yolo.md.j2 b/src/issue_flow/templates/commands/issue-yolo.md.j2 index cd41d04..f0282da 100644 --- a/src/issue_flow/templates/commands/issue-yolo.md.j2 +++ b/src/issue_flow/templates/commands/issue-yolo.md.j2 @@ -4,6 +4,8 @@ Chains `/issue-init` → `/issue-plan` → `/issue-start` → `/issue-close` in For anything non-trivial, use the individual commands so you get confirmation checkpoints. +The chained commands still consult and update `{{ issueflows_dir }}/{{ designs_folder }}/` (design docs, decisions, good practices) — but if a yolo run uncovers a decision worth recording, that alone is usually a signal the change is **not** small enough for `/issue-yolo`: consider aborting and running the commands individually. + ## Input Same as `/issue-init` (issue number, URL, or empty to infer from the branch). Optional extra tokens are forwarded to the downstream commands: diff --git a/src/issue_flow/templates/rules/issueflow-rules.mdc.j2 b/src/issue_flow/templates/rules/issueflow-rules.mdc.j2 index c6037d3..f347f3f 100644 --- a/src/issue_flow/templates/rules/issueflow-rules.mdc.j2 +++ b/src/issue_flow/templates/rules/issueflow-rules.mdc.j2 @@ -61,6 +61,7 @@ uv run script.py issueXX_status.md {{ partly_solved_folder }}/ {{ solved_folder }}/ + {{ designs_folder }}/ pyproject.toml readme.md ... @@ -101,6 +102,15 @@ If the issue is fully resolved (no additional subtasks present), move the origin 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. +### Designs and guides + +Long-lived design docs, design decisions, and project "good practices" live under `{{ issueflows_dir }}/{{ designs_folder }}/`. 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. + +- **Before planning or implementing**, skim `{{ issueflows_dir }}/{{ designs_folder }}/` 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 `/issue-plan` or `/issue-start`, 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. + + ### Branch hygiene - Do issue work on an **issue branch** named like `-`, not on the default branch. diff --git a/tests/test_config.py b/tests/test_config.py index c1dfffa..6dcffd3 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -18,11 +18,12 @@ def test_default_settings() -> None: def test_issueflows_subdirs() -> None: settings = Settings() subdirs = settings.issueflows_subdirs - assert len(subdirs) == 4 + assert len(subdirs) == 5 assert "00-tools" in subdirs assert "01-current-issues" in subdirs assert "02-partly-solved-issues" in subdirs assert "03-solved-issues" in subdirs + assert "04-designs-and-guides" in subdirs def test_template_context_keys(tmp_path: Path) -> None: @@ -37,6 +38,7 @@ def test_template_context_keys(tmp_path: Path) -> None: "current_issues_folder", "partly_solved_folder", "solved_folder", + "designs_folder", "project_name", } assert set(context.keys()) == expected_keys diff --git a/tests/test_init.py b/tests/test_init.py index c0dde46..48d3d03 100644 --- a/tests/test_init.py +++ b/tests/test_init.py @@ -71,7 +71,7 @@ def test_init_force_does_not_wipe_custom_dotenv(tmp_path: Path) -> None: def test_init_creates_directories(tmp_path: Path) -> None: - """Running init should create .issueflows/ with all four subdirectories.""" + """Running init should create .issueflows/ with all five subdirectories.""" run_init(tmp_path) issueflows = tmp_path / ".issueflows" @@ -80,6 +80,7 @@ def test_init_creates_directories(tmp_path: Path) -> None: assert (issueflows / "01-current-issues").is_dir() assert (issueflows / "02-partly-solved-issues").is_dir() assert (issueflows / "03-solved-issues").is_dir() + assert (issueflows / "04-designs-and-guides").is_dir() def test_init_creates_gitkeep_files(tmp_path: Path) -> None: @@ -92,6 +93,7 @@ def test_init_creates_gitkeep_files(tmp_path: Path) -> None: "01-current-issues", "02-partly-solved-issues", "03-solved-issues", + "04-designs-and-guides", ]: gitkeep = issueflows / subdir / ".gitkeep" assert gitkeep.is_file(), f"{subdir}/.gitkeep should exist" @@ -217,6 +219,27 @@ def test_init_issue_close_documents_uncommitted_and_branch_reminder( assert "issue branch" in content +def test_init_rule_documents_designs_folder(tmp_path: Path) -> None: + """The generated rule file should mention the designs-and-guides folder.""" + run_init(tmp_path) + rule = (tmp_path / ".cursor" / "rules" / "issueflow-rules.mdc").read_text( + encoding="utf-8" + ) + assert "04-designs-and-guides" in rule + assert "Designs and guides" in rule + + +def test_init_commands_reference_designs_folder(tmp_path: Path) -> None: + """/issue-plan, /issue-start, and /issue-close should reference the designs folder.""" + run_init(tmp_path) + commands_dir = tmp_path / ".cursor" / "commands" + for filename in ("issue-plan.md", "issue-start.md", "issue-close.md"): + content = (commands_dir / filename).read_text(encoding="utf-8") + assert "04-designs-and-guides" in content, ( + f"{filename} should reference the designs-and-guides folder" + ) + + def test_init_issue_init_documents_branch_inference(tmp_path: Path) -> None: """issue-init.md should describe resolving an issue from the current branch when no args.""" run_init(tmp_path) diff --git a/tests/test_update.py b/tests/test_update.py index b6fa0a7..2904bd2 100644 --- a/tests/test_update.py +++ b/tests/test_update.py @@ -62,3 +62,31 @@ def test_update_recreates_removed_subdir(tmp_path: Path) -> None: assert removed.is_dir() assert (removed / ".gitkeep").is_file() + + +def test_update_preserves_designs_folder_contents(tmp_path: Path) -> None: + """update must not touch user content inside 04-designs-and-guides/.""" + run_init(tmp_path) + + designs_dir = tmp_path / ".issueflows" / "04-designs-and-guides" + design_doc = designs_dir / "logging-decision.md" + body = "# Logging decision\n\nWe use structlog because X.\n" + design_doc.write_text(body, encoding="utf-8") + + run_update(tmp_path) + + assert design_doc.read_text(encoding="utf-8") == body + + +def test_update_recreates_removed_designs_folder(tmp_path: Path) -> None: + """If 04-designs-and-guides/ was removed, update should recreate it.""" + run_init(tmp_path) + + removed = tmp_path / ".issueflows" / "04-designs-and-guides" + shutil.rmtree(removed) + assert not removed.exists() + + run_update(tmp_path) + + assert removed.is_dir() + assert (removed / ".gitkeep").is_file() From 187b532e0b311e8ae2c904b4d1655243f87ad03c Mon Sep 17 00:00:00 2001 From: jepegit Date: Sun, 19 Apr 2026 22:53:03 +0200 Subject: [PATCH 2/2] Release 0.2.3: designs-and-guides folder (#26) - Bump version to 0.2.3 (patch) via uv version --bump patch. - Promote HISTORY.md [Unreleased] -> [0.2.3] - 2026-04-19 and record the new bullet for #26. - Archive issue26_* into 03-solved-issues/. Refs #26. Made-with: Cursor --- .../issue26_original.md | 0 .../{01-current-issues => 03-solved-issues}/issue26_status.md | 0 HISTORY.md | 3 +++ pyproject.toml | 2 +- uv.lock | 2 +- 5 files changed, 5 insertions(+), 2 deletions(-) rename .issueflows/{01-current-issues => 03-solved-issues}/issue26_original.md (100%) rename .issueflows/{01-current-issues => 03-solved-issues}/issue26_status.md (100%) diff --git a/.issueflows/01-current-issues/issue26_original.md b/.issueflows/03-solved-issues/issue26_original.md similarity index 100% rename from .issueflows/01-current-issues/issue26_original.md rename to .issueflows/03-solved-issues/issue26_original.md diff --git a/.issueflows/01-current-issues/issue26_status.md b/.issueflows/03-solved-issues/issue26_status.md similarity index 100% rename from .issueflows/01-current-issues/issue26_status.md rename to .issueflows/03-solved-issues/issue26_status.md diff --git a/HISTORY.md b/HISTORY.md index 39836ae..9be6b14 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -9,6 +9,8 @@ than the GitHub release notes they link to. ## [Unreleased] +## [0.2.3] - 2026-04-19 + - **Dependency awareness at install time (#18).** A new `Prerequisites` section in the README documents the external CLI tools the scaffolded workflow shells out to (`git`, `gh` — with install hints per OS and a `gh auth login` reminder), and `issue-flow init` / `issue-flow update` now run a `shutil.which`-based dependency check up front. If anything is missing, the CLI prints the install hints and asks for confirmation before continuing. The prompt is auto-skipped on non-TTY stdin (CI) and can be bypassed explicitly with `--skip-dep-check`. - `issue-flow init` now creates or extends a project `.env` with `ISSUEFLOW_*` hints (#35). - Rename `ISSUEFLOW_CURSOR_DIR` to the more tool-agnostic `ISSUEFLOW_AGENT_DIR` (#36). @@ -21,6 +23,7 @@ than the GitHub release notes they link to. - `/issue-yolo` chains `init → plan → start → close` for small, low-risk issues with up-front safeguards (refuses on default branch, refuses with dirty unrelated changes, requires `uv run pytest` to pass, single consolidated confirm). Never chains `/issue-cleanup`. - **Quick start `/iflow` smart dispatcher.** Inspects the focus issue (a branch-derived `N` from an `-` branch is authoritative — it wins even when `issue_*` files don't exist yet or unrelated groups sit in `.issueflows/01-current-issues/`; otherwise falls back to the single group in `01-`, else asks) and dispatches to `/issue-init`, `/issue-plan`, `/issue-start`, or `/issue-close` based on which files exist and whether the status file is marked `- [x] Done`. Warns up front when the focus issue is archived under `02-partly-solved-issues/` or `03-solved-issues/` so the user knows `/issue-init`'s archived-issue guard will ask for an explicit re-open confirmation. Forwards trailing args verbatim. Never auto-dispatches to `/issue-pause`, `/issue-cleanup`, or `/issue-yolo` — those stay explicit. - **`/issue-close` now updates `HISTORY.md` (#15).** New step between the version bump and issue-folder housekeeping, driven by a new `issueflow-history-update` Agent Skill. Appends a bullet to `## [Unreleased]` on a regular close, and on `/issue-close bump ` promotes `## [Unreleased]` to `## [] - ` with a fresh empty `## [Unreleased]` above it. Opt-out via `nohistory`; override the bullet summary with `log "..."`. New config knob `ISSUEFLOW_HISTORY_FILE` (default `HISTORY.md`) lets projects point at `CHANGELOG.md` or similar. +- **New `04-designs-and-guides/` folder (#26).** `.issueflows/04-designs-and-guides/` gives projects a durable home for long-lived design docs, design decisions, and agreed good-practices. `issue-flow init` creates it; `issue-flow update` recreates it only if missing and never overwrites user files inside it. The issueflow rule file documents its purpose, and `/issue-plan`, `/issue-start`, `/issue-close`, `/iflow`, and `/issue-yolo` now read from and/or contribute to the folder during issue work. ## [0.2.2] - 2026-04-17 diff --git a/pyproject.toml b/pyproject.toml index 27e215e..77eda62 100644 --- a/pyproject.toml +++ b/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" diff --git a/uv.lock b/uv.lock index 3c559c1..024d59f 100644 --- a/uv.lock +++ b/uv.lock @@ -43,7 +43,7 @@ wheels = [ [[package]] name = "issue-flow" -version = "0.2.2" +version = "0.2.3" source = { editable = "." } dependencies = [ { name = "jinja2" },