Add .issueflows/04-designs-and-guides/ folder (#26)

.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:

.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.

.cursor/commands/issue-plan.md

@@ -21,6 +21,8 @@ Optional free-form text after the command. Examples:
 
 1. **Read the issue.** Load `issue<N>_original.md` and any existing `issue<N>_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<N>_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.
 

.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 <date>` note to `issue<N>_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<N>_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.
 

.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:

.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 `<N>-<short-slug>`, not on the default branch.

.issueflows/03-solved-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.

.issueflows/03-solved-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.

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 `<N>-<slug>` branch is authoritative — it wins even when `issue<N>_*` 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 <level>` promotes `## [Unreleased]` to `## [<new_version>] - <YYYY-MM-DD>` 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
 

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"

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,
         }
 

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:

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.

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<N>_original.md` and any existing `issue<N>_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<N>_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.
 

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 <date>` note to `issue<N>_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<N>_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.
 

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: