project-guide 2.3.7__tar.gz → 2.3.8__tar.gz

{project_guide-2.3.7 → project_guide-2.3.8}/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.8] - 2026-04-14
+
+### Fixed
+- **Sequence-mode "Next Action" directive caused LLMs to skip steps** (Story M.i) — the `_header-sequence.md` include rendered a prominent "Next Action: Prompt the user to change modes" directive *before* the actual Steps section in all 9 sequence-mode templates. LLMs interpreted this as the primary instruction and jumped straight to suggesting a mode switch, ignoring the mode's steps entirely. Fix is belt-and-suspenders: (1) reworded `_header-sequence.md` from "Next Action / Prompt the user to change modes" to "After completing all steps below, prompt the user to change modes" so the directive is unambiguously post-completion, and (2) moved the `{% include "modes/_header-sequence.md" %}` from the top to the bottom of all 9 sequence-mode templates so the directive structurally appears after the steps.
+
+### Changed
+- **`_header-sequence.md`** — reworded from "Next Action / Prompt the user to change modes" to "After completing all steps below, prompt the user to change modes."
+- **All 9 sequence-mode templates** — moved `{% include "modes/_header-sequence.md" %}` from top (before Prerequisites/Steps) to bottom (after all steps and reference material): `plan-concept-mode.md`, `plan-features-mode.md`, `plan-tech-spec-mode.md`, `plan-stories-mode.md`, `plan-phase-mode.md`, `archive-stories-mode.md`, `project-scaffold-mode.md`, `document-brand-mode.md`, `document-landing-mode.md`.
+
 ## [2.3.7] - 2026-04-14
 
 ### Changed

{project_guide-2.3.7 → project_guide-2.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-guide
-Version: 2.3.7
+Version: 2.3.8
 Summary: Stay organized and in control with adaptive LLM workflow prompts.
 Project-URL: Homepage, https://github.com/pointmatic/project-guide
 Project-URL: Documentation, https://pointmatic.github.io/project-guide/

{project_guide-2.3.7 → project_guide-2.3.8}/docs/specs/stories.md

@@ -369,6 +369,16 @@ Stop LLMs from tacking "commit now or continue?" footers onto approval-gate summ
 - [x] Update pip-installed project-guide package to 2.3.6
 - [x] Bump version to 2.3.7
 
+### Story M.i: v2.3.8 Fix Sequence-Mode "Next Action" Directive Skipping Steps [Done]
+
+LLMs in `plan_stories` (and all sequence modes) were skipping the mode's steps and jumping straight to suggesting a mode switch. Root cause: `_header-sequence.md` rendered a prominent "Next Action: Prompt the user to change modes" directive *before* the Steps section. LLMs treated it as the primary instruction.
+
+- [x] Reword `_header-sequence.md` from "Next Action / Prompt the user to change modes" to "After completing all steps below, prompt the user to change modes"
+- [x] Move `{% include "modes/_header-sequence.md" %}` from top to bottom of all 9 sequence-mode templates: `plan-concept-mode.md`, `plan-features-mode.md`, `plan-tech-spec-mode.md`, `plan-stories-mode.md`, `plan-phase-mode.md`, `archive-stories-mode.md`, `project-scaffold-mode.md`, `document-brand-mode.md`, `document-landing-mode.md`
+- [x] Verify: all 266 tests pass, ruff clean
+- [x] Bump version to 2.3.8
+- [x] Update CHANGELOG.md
+
 ---
 
 ## Future

project_guide-2.3.8/project_guide/templates/project-guide/templates/modes/_header-sequence.md

@@ -0,0 +1,7 @@
+**After completing all steps below**, prompt the user to change modes:
+
+```bash
+project-guide mode {{ next_mode }}
+```
+
+---

{project_guide-2.3.7 → project_guide-2.3.8}/project_guide/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "2.3.7"
+__version__ = "2.3.8"

{project_guide-2.3.7 → project_guide-2.3.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "project-guide"
-version = "2.3.7"
+version = "2.3.8"
 description = "Stay organized and in control with adaptive LLM workflow prompts."
 readme = "README.md"
 license = "Apache-2.0"

project_guide-2.3.7/project_guide/templates/project-guide/templates/modes/_header-sequence.md

@@ -1,8 +0,0 @@
-**Next Action**
-Prompt the user to change modes. 
-
-```bash
-project-guide mode {{ next_mode }}
-```
-
----

{project_guide-2.3.7 → project_guide-2.3.8}/project_guide/templates/project-guide/templates/modes/archive-stories-mode.md

@@ -2,8 +2,6 @@ Archive the completed `docs/specs/stories.md` so the next phase can start with a
 
 This mode is intended to run after all active stories are `[Done]` and before the developer plans the next phase. Phase letters continue across the archive boundary (see below).
 
-{% include "modes/_header-sequence.md" %}
-
 ## Prerequisites
 
 - `docs/specs/stories.md` exists.
@@ -77,4 +75,6 @@ After the archive succeeds, suggest the next step:
 >
 > `plan_phase` will read `.archive/` to continue the phase letter sequence (e.g. if the archive's last phase was `K`, the next phase is `L`). See the Phase and Story ID Scheme below.
 
+{% include "modes/_header-sequence.md" %}
+
 {% include "modes/_phase-letters.md" %}

{project_guide-2.3.7 → project_guide-2.3.8}/project_guide/templates/project-guide/templates/modes/document-brand-mode.md

@@ -2,8 +2,6 @@
 
 {{ mode_description }}
 
-{% include "modes/_header-sequence.md" %}
-
 ---
 
 ## Purpose
@@ -482,3 +480,5 @@ The `descriptions.md` file is a critical documentation artifact that:
 - Provides clear guidance on which description to use where
 - Should be created early in the documentation phase
 - Must be approved before disseminating to consumer files
+
+{% include "modes/_header-sequence.md" %}

{project_guide-2.3.7 → project_guide-2.3.8}/project_guide/templates/project-guide/templates/modes/document-landing-mode.md

@@ -1,7 +1,5 @@
 Implement the landing page (GitHub Pages) and extended documentation (MkDocs Material theme). You will create a custom landing page (`index.html`) as the home page combined with MkDocs Material theme built from markdown pages for additional documentation.
 
-{% include "modes/_header-sequence.md" %}
-
 ## Overview
 
 **Architecture:**
@@ -806,3 +804,5 @@ Reference implementations:
 **Questions or issues?** Open an issue on the Pyve repository or consult:
 - [MkDocs Documentation](https://www.mkdocs.org/)
 - [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
+
+{% include "modes/_header-sequence.md" %}

{project_guide-2.3.7 → project_guide-2.3.8}/project_guide/templates/project-guide/templates/modes/plan-concept-mode.md

@@ -1,7 +1,5 @@
 Define the problem space (problem statement, why, pain points, target users, value criteria) and the solution space (solution statement, goals, scope, constraints), and pain point to solution mapping.
 
-{% include "modes/_header-sequence.md" %}
-
 ## Prerequisites
 
 Before starting, the developer must provide (or the LLM must ask for):
@@ -48,3 +46,5 @@ Before starting, the developer must provide (or the LLM must ask for):
   ...
 ...
 ```
+
+{% include "modes/_header-sequence.md" %}

{project_guide-2.3.7 → project_guide-2.3.8}/project_guide/templates/project-guide/templates/modes/plan-features-mode.md

@@ -2,8 +2,6 @@ Define **what** the project does -- requirements, inputs, outputs, behavior -- w
 
 The high-level concept (why) should be captured in `concept.md`. The implementation details (how) should be written in `tech-spec.md`. The breakdown of the implementation plan (step-by-step tasks) should be written in `stories.md`.
 
-{% include "modes/_header-sequence.md" %}
-
 ## Prerequisites
 
 Before starting, the developer must provide (or the LLM must ask for):
@@ -55,3 +53,5 @@ Description of the feature's purpose.
 - Edge case 1 -> How it's handled
 - Edge case 2 -> How it's handled
 ```
+
+{% include "modes/_header-sequence.md" %}

{project_guide-2.3.7 → project_guide-2.3.8}/project_guide/templates/project-guide/templates/modes/plan-phase-mode.md

@@ -2,8 +2,6 @@ Generate a combined concept/features/tech-spec document for a new phase in an ex
 
 Use this mode when the developer wants to add a significant new capability to a project that already has an established codebase and spec documents.
 
-{% include "modes/_header-sequence.md" %}
-
 ## Prerequisites
 
 Before planning a new phase, the following should exist:
@@ -72,4 +70,6 @@ Before planning a new phase, the following should exist:
 
    Present the updated file to the developer for approval. Show only what was added (since this is an append operation, the diff is minimal).
 
+{% include "modes/_header-sequence.md" %}
+
 {% include "modes/_phase-letters.md" %}

{project_guide-2.3.7 → project_guide-2.3.8}/project_guide/templates/project-guide/templates/modes/plan-stories-mode.md

@@ -2,8 +2,6 @@ Break the project into an ordered sequence of small, independently completable s
 
 The high-level concept (why) should be captured in `concept.md`. The requirements and behavior (what) should be captured in `features.md`. The implementation details (how) should be written in `tech-spec.md`.
 
-{% include "modes/_header-sequence.md" %}
-
 ## Prerequisites
 
 Before writing stories, the following must be approved:
@@ -66,3 +64,5 @@ Phases may be added, removed, or renamed to fit the project.
 - [ ] Task 2
 - [ ] Task 3
 ```
+
+{% include "modes/_header-sequence.md" %}

{project_guide-2.3.7 → project_guide-2.3.8}/project_guide/templates/project-guide/templates/modes/plan-tech-spec-mode.md

@@ -2,8 +2,6 @@ Define **how** the project is built -- architecture, module layout, dependencies
 
 The high-level concept (why) should be captured in `concept.md`. The requirements and behavior (what) should be captured in `features.md`. The breakdown of this implementation plan (step-by-step tasks) should be written in `stories.md`.
 
-{% include "modes/_header-sequence.md" %}
-
 ## Prerequisites
 
 Before starting, the developer must provide (or the LLM must ask for):
@@ -72,3 +70,5 @@ Include a **Filename Conventions** section in the tech spec:
 | **Python packages** | Underscores (PEP 8) | `my_package/`, `utils/` |
 | **JavaScript/TypeScript** | Hyphens or camelCase | `api-client.ts`, `dataProcessor.ts` |
 | **Configuration files** | Hyphens or dots | `mkdocs.yml`, `.gitignore`, `pyproject.toml` |
+
+{% include "modes/_header-sequence.md" %}

{project_guide-2.3.7 → project_guide-2.3.8}/project_guide/templates/project-guide/templates/modes/project-scaffold-mode.md

@@ -1,7 +1,5 @@
 Scaffold the project foundation: license, copyright headers, package manifest, README with badges, CHANGELOG, and .gitignore. This is a one-time scaffolding step after planning is complete, using decisions made in the concept, features, tech-spec, and stories documents.
 
-{% include "modes/_header-sequence.md" %}
-
 ## Prerequisites
 
 Before starting, the developer must provide (or the LLM must ask for):
@@ -130,3 +128,5 @@ Once approved, proceed to coding:
 ```bash
 project-guide mode {{ next_mode }}
 ```
+
+{% include "modes/_header-sequence.md" %}