imdone-cli 0.74.0 → 0.74.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog 📝
 
+## 0.74.1
+
+- Ship the missed bundled HDD skill updates from `0.74.0`, including the new required `Problem Framing` step before `Hypothesis` so agents anchor hypotheses, slices, acceptance criteria, and plans in a user-provided or user-confirmed problem
+- Update the stock HDD story template so newly created HDD stories include `## Problem Framing` and a matching checklist item before hypothesis work starts
+- Keep Codex and Claude HDD skill copies aligned on command-owned sync timing, README/changelog planning coverage, and project-specific README and changelog style guides
+
 ## 0.74.0
 
 - Make Jira-backed `imdone pull` faster when nothing changed upstream by using saved provider sync state to skip redundant full issue-list fetches when the local cache can prove there is no meaningful delta

package/dist/.claude/skills/hypothesis-driven-development/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: hypothesis-driven-development
-description: Guide a story through hypothesis-driven development from hypothesis through design, plan, implementation order, and outcome review. Use when the user wants to refine a story, define or repair binary acceptance criteria, create or revise an AI-executable plan, add success metrics or demo steps, validate dependency direction, or check progress against the workflow artifacts.
-user-invocable: true
-argument-hint: "[issueKey]"
+description: Guide a story through hypothesis-driven development from user-confirmed problem framing through hypothesis, design, plan, implementation order, and outcome review. Use when the user wants to refine a story, define or repair binary acceptance criteria, create or revise an AI-executable plan, add success metrics or demo steps, validate dependency direction, or check progress against the workflow artifacts.
 ---
 
 # Hypothesis-Driven Development
@@ -65,13 +63,15 @@ Run only the current phase and current unchecked item. Skip anything already che
 ### Phase 1: Define the Outcome
 
 Order:
-1. Hypothesis
-2. Vertical Slice
-3. Acceptance Criteria
-4. Validate Assumptions
-5. Demo Plan
+1. Problem Framing
+2. Hypothesis
+3. Vertical Slice
+4. Acceptance Criteria
+5. Validate Assumptions
+6. Demo Plan
 
 Write locations:
+- Problem Framing: inline in `## Problem Framing` above `## Hypothesis`
 - Hypothesis: inline in `## Hypothesis` above `## Define the Outcome`
 - Related Work: inline in `## Related Work` above `## Define the Outcome`
 - Vertical Slice: inline in `## Vertical Slice` above `## Define the Outcome`
@@ -81,6 +81,7 @@ Write locations:
 - Demo Plan: `attachments/demo.md`
 
 Load `references/define-the-outcome.md` only when working this phase.
+Before Hypothesis, require a user-provided or user-confirmed problem framing. If the issue already contains enough context, draft the framing from the story and ask the user to confirm it with numbered choices. If the issue does not contain enough context, ask the user for the problem framing before writing outcome artifacts.
 During Vertical Slice, first inspect related past stories or experiments in the current backlog plus the configured archive, then link the useful ones under `## Related Work` so the slice benefits from prior decisions and evidence.
 During Success Metrics, require both a user feedback path and an implemented measurement/data-capture mechanism as part of the slice. For app-facing work, prefer in-app feedback plus product instrumentation. For CLI, API, automation, or infrastructure work, treat that interface as the app surface and require a concrete equivalent such as command output, help/feedback links, structured logs, persisted artifacts, audit records, metrics, or provider-visible state. Do not accept "no telemetry", "manual observation only", or "follow-up later" as complete for the current slice.
 
@@ -146,6 +147,7 @@ Load only the reference file needed for the current decision:
 - Keep the issue file current as an attachment index. When an issue attachment exists or is created, make sure the issue file links to it. Leave existing template links in place, and accept duplicates when adding missing links is simpler than normalizing them.
 - Use `imdone agent-config` as the only boundary for HDD config reads and writes, including push reminder settings, push timing state, `active_story`, and saved-key path resolution. Do not parse or rewrite agent config YAML inline, and do not call local skill helper scripts for configuration state.
 - Before any push reminder, check `imdone agent-config get-config` and only ask whether to run `imdone push` when `push.imdoneStatus.hasPendingChanges` is true.
+- Do not mark Hypothesis complete until `## Problem Framing` exists and the user has provided or confirmed it during the HDD session.
 - Every HDD user-facing question must include numbered answer choices so the user can reply with a number alone. Use a numbered free-form option when the user may need to correct the framing or provide custom details.
 - In `interval_prompt` mode, check push timing through `imdone agent-config get-config` before starting any substantial read, edit, verification, or implementation cycle, not only at phase boundaries. Treat `push.promptDue` as already gated by elapsed interval and pending `imdone status` changes.
 - When using this skill, end each user-facing message with a visible indicator showing the active story key, a short story summary, and the HDD skill version from `imdone --version`. Example: `🧭 HDD v0.58.2 | SCRUM-260 — Share changelog section on prompt upgrade`

package/dist/.claude/skills/hypothesis-driven-development/references/define-the-outcome.md

@@ -4,11 +4,27 @@ Use this reference during Phase 1.
 
 ## Order
 
-1. Hypothesis
-2. Vertical Slice
-3. Acceptance Criteria
-4. Validate Assumptions
-5. Demo Plan
+1. Problem Framing
+2. Hypothesis
+3. Vertical Slice
+4. Acceptance Criteria
+5. Validate Assumptions
+6. Demo Plan
+
+## Problem Framing
+
+- Require a user-provided or user-confirmed problem framing before drafting or approving Hypothesis.
+- Write the framing in a dedicated `## Problem Framing` section above `## Hypothesis`, not inside the checklist item.
+- If the issue already contains enough context, draft the framing from the story and ask the user to confirm it with numbered choices before writing or checking the item.
+- If the issue does not contain enough context, ask the user for the framing before writing other Define the Outcome artifacts.
+- The framing must name:
+  - the user, customer, or operational role affected
+  - the problem, pain, or workflow breakdown
+  - why it matters now, including impact or evidence
+  - the current workaround or failure mode when known
+  - what would be observably better if the problem were solved
+- For enabling, CLI, infrastructure, or internal workflow stories, use the affected internal user or automation workflow instead of forcing an external-customer frame.
+- Do not mark Hypothesis complete until Problem Framing exists and was provided or confirmed by the user in the current HDD session.
 
 ## Product Owner Review
 

package/dist/.claude/skills/hypothesis-driven-development/references/session-setup.md

@@ -67,7 +67,7 @@ If the story is not already using the HDD template, use the `imdone-template` sk
 - apply template `hypothesis_driven_development` when it exists locally; otherwise apply `stock_hypothesis_driven_development`
 - re-read the story and attachments after templating, then continue the HDD workflow
 - explain briefly that you are switching the story onto the HDD template so the refinement artifacts land in the expected structure
-- make sure `## Acceptance Criteria`, `## Vertical Slice`, `## Related Work`, `## Hypothesis`, and `## Validate Assumptions` live above `## Define the Outcome`; the checklist should only track whether those sections and attachment artifacts are complete
+- make sure `## Problem Framing`, `## Acceptance Criteria`, `## Vertical Slice`, `## Related Work`, `## Hypothesis`, and `## Validate Assumptions` live above `## Define the Outcome`; the checklist should only track whether those sections and attachment artifacts are complete
 - make sure `Measure Results` and `Retrospect` are backed by `## Results` and `## Retrospect` sections in `attachments/success-metrics.md`; the checklist should only track completion
 
 If the story already has `#HDD-template` but its sections, headings, or checklist order no longer match the current bundled HDD format:
@@ -79,6 +79,7 @@ If the story already has `#HDD-template` but its sections, headings, or checklis
 
 Extract:
 - user-visible behavior that must change
+- user-provided or user-confirmed problem framing
 - user or customer outcome that should improve
 - constraints that must not change
 - likely files or subsystems involved

package/dist/.codex/skills/hypothesis-driven-development/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: hypothesis-driven-development
-description: Guide a story through hypothesis-driven development from hypothesis through design, plan, implementation order, and outcome review. Use when the user wants to refine a story, define or repair binary acceptance criteria, create or revise an AI-executable plan, add success metrics or demo steps, validate dependency direction, or check progress against the workflow artifacts.
-user-invocable: true
-argument-hint: "[issueKey]"
+description: Guide a story through hypothesis-driven development from user-confirmed problem framing through hypothesis, design, plan, implementation order, and outcome review. Use when the user wants to refine a story, define or repair binary acceptance criteria, create or revise an AI-executable plan, add success metrics or demo steps, validate dependency direction, or check progress against the workflow artifacts.
 ---
 
 # Hypothesis-Driven Development
@@ -65,13 +63,15 @@ Run only the current phase and current unchecked item. Skip anything already che
 ### Phase 1: Define the Outcome
 
 Order:
-1. Hypothesis
-2. Vertical Slice
-3. Acceptance Criteria
-4. Validate Assumptions
-5. Demo Plan
+1. Problem Framing
+2. Hypothesis
+3. Vertical Slice
+4. Acceptance Criteria
+5. Validate Assumptions
+6. Demo Plan
 
 Write locations:
+- Problem Framing: inline in `## Problem Framing` above `## Hypothesis`
 - Hypothesis: inline in `## Hypothesis` above `## Define the Outcome`
 - Related Work: inline in `## Related Work` above `## Define the Outcome`
 - Vertical Slice: inline in `## Vertical Slice` above `## Define the Outcome`
@@ -81,6 +81,7 @@ Write locations:
 - Demo Plan: `attachments/demo.md`
 
 Load `references/define-the-outcome.md` only when working this phase.
+Before Hypothesis, require a user-provided or user-confirmed problem framing. If the issue already contains enough context, draft the framing from the story and ask the user to confirm it with numbered choices. If the issue does not contain enough context, ask the user for the problem framing before writing outcome artifacts.
 During Vertical Slice, first inspect related past stories or experiments in the current backlog plus the configured archive, then link the useful ones under `## Related Work` so the slice benefits from prior decisions and evidence.
 During Success Metrics, require both a user feedback path and an implemented measurement/data-capture mechanism as part of the slice. For app-facing work, prefer in-app feedback plus product instrumentation. For CLI, API, automation, or infrastructure work, treat that interface as the app surface and require a concrete equivalent such as command output, help/feedback links, structured logs, persisted artifacts, audit records, metrics, or provider-visible state. Do not accept "no telemetry", "manual observation only", or "follow-up later" as complete for the current slice.
 
@@ -146,6 +147,7 @@ Load only the reference file needed for the current decision:
 - Keep the issue file current as an attachment index. When an issue attachment exists or is created, make sure the issue file links to it. Leave existing template links in place, and accept duplicates when adding missing links is simpler than normalizing them.
 - Use `imdone agent-config` as the only boundary for HDD config reads and writes, including push reminder settings, push timing state, `active_story`, and saved-key path resolution. Do not parse or rewrite agent config YAML inline, and do not call local skill helper scripts for configuration state.
 - Before any push reminder, check `imdone agent-config get-config` and only ask whether to run `imdone push` when `push.imdoneStatus.hasPendingChanges` is true.
+- Do not mark Hypothesis complete until `## Problem Framing` exists and the user has provided or confirmed it during the HDD session.
 - Every HDD user-facing question must include numbered answer choices so the user can reply with a number alone. Use a numbered free-form option when the user may need to correct the framing or provide custom details.
 - In `interval_prompt` mode, check push timing through `imdone agent-config get-config` before starting any substantial read, edit, verification, or implementation cycle, not only at phase boundaries. Treat `push.promptDue` as already gated by elapsed interval and pending `imdone status` changes.
 - When using this skill, end each user-facing message with a visible indicator showing the active story key, a short story summary, and the HDD skill version from `imdone --version`. Example: `🧭 HDD v0.58.2 | SCRUM-260 — Share changelog section on prompt upgrade`

package/dist/.codex/skills/hypothesis-driven-development/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Hypothesis Driven Development"
-  short_description: "Guide a story through hypothesis-driven development from hypothesis"
-  default_prompt: "Use $hypothesis-driven-development when relevant for: Guide a story through hypothesis-driven development from hypothesis."
+  short_description: "Guide a story from problem framing through HDD outcome review"
+  default_prompt: "Use $hypothesis-driven-development to refine a story from user-confirmed problem framing through hypothesis, plan, implementation, and outcome review."
 
 policy:
   allow_implicit_invocation: true

package/dist/.codex/skills/hypothesis-driven-development/references/define-the-outcome.md

@@ -4,11 +4,27 @@ Use this reference during Phase 1.
 
 ## Order
 
-1. Hypothesis
-2. Vertical Slice
-3. Acceptance Criteria
-4. Validate Assumptions
-5. Demo Plan
+1. Problem Framing
+2. Hypothesis
+3. Vertical Slice
+4. Acceptance Criteria
+5. Validate Assumptions
+6. Demo Plan
+
+## Problem Framing
+
+- Require a user-provided or user-confirmed problem framing before drafting or approving Hypothesis.
+- Write the framing in a dedicated `## Problem Framing` section above `## Hypothesis`, not inside the checklist item.
+- If the issue already contains enough context, draft the framing from the story and ask the user to confirm it with numbered choices before writing or checking the item.
+- If the issue does not contain enough context, ask the user for the framing before writing other Define the Outcome artifacts.
+- The framing must name:
+  - the user, customer, or operational role affected
+  - the problem, pain, or workflow breakdown
+  - why it matters now, including impact or evidence
+  - the current workaround or failure mode when known
+  - what would be observably better if the problem were solved
+- For enabling, CLI, infrastructure, or internal workflow stories, use the affected internal user or automation workflow instead of forcing an external-customer frame.
+- Do not mark Hypothesis complete until Problem Framing exists and was provided or confirmed by the user in the current HDD session.
 
 ## Product Owner Review
 

package/dist/.codex/skills/hypothesis-driven-development/references/session-setup.md

@@ -67,7 +67,7 @@ If the story is not already using the HDD template, use the `imdone-template` sk
 - apply template `hypothesis_driven_development` when it exists locally; otherwise apply `stock_hypothesis_driven_development`
 - re-read the story and attachments after templating, then continue the HDD workflow
 - explain briefly that you are switching the story onto the HDD template so the refinement artifacts land in the expected structure
-- make sure `## Acceptance Criteria`, `## Vertical Slice`, `## Related Work`, `## Hypothesis`, and `## Validate Assumptions` live above `## Define the Outcome`; the checklist should only track whether those sections and attachment artifacts are complete
+- make sure `## Problem Framing`, `## Acceptance Criteria`, `## Vertical Slice`, `## Related Work`, `## Hypothesis`, and `## Validate Assumptions` live above `## Define the Outcome`; the checklist should only track whether those sections and attachment artifacts are complete
 - make sure `Measure Results` and `Retrospect` are backed by `## Results` and `## Retrospect` sections in `attachments/success-metrics.md`; the checklist should only track completion
 
 If the story already has `#HDD-template` but its sections, headings, or checklist order no longer match the current bundled HDD format:
@@ -79,6 +79,7 @@ If the story already has `#HDD-template` but its sections, headings, or checklis
 
 Extract:
 - user-visible behavior that must change
+- user-provided or user-confirmed problem framing
 - user or customer outcome that should improve
 - constraints that must not change
 - likely files or subsystems involved

package/dist/.imdone/templates/stock/hypothesis-driven-development.md

@@ -1,5 +1,9 @@
 ${markdown}
 
+## Problem Framing
+
+- [Who is affected, what problem they have, why it matters now, the current workaround or failure mode, and what would be observably better if solved]
+
 ## Hypothesis
 
 - "We believe [doing this] will result in [this outcome] because [reason]"
@@ -22,6 +26,7 @@ ${markdown}
 
 ## Define the Outcome
 
+- [ ] **Problem Framing**
 - [ ] **Hypothesis**
 - [ ] **Vertical Slice**
 - [ ] **Acceptance Criteria**

package/dist/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog 📝
 
+## 0.74.1
+
+- Ship the missed bundled HDD skill updates from `0.74.0`, including the new required `Problem Framing` step before `Hypothesis` so agents anchor hypotheses, slices, acceptance criteria, and plans in a user-provided or user-confirmed problem
+- Update the stock HDD story template so newly created HDD stories include `## Problem Framing` and a matching checklist item before hypothesis work starts
+- Keep Codex and Claude HDD skill copies aligned on command-owned sync timing, README/changelog planning coverage, and project-specific README and changelog style guides
+
 ## 0.74.0
 
 - Make Jira-backed `imdone pull` faster when nothing changed upstream by using saved provider sync state to skip redundant full issue-list fetches when the local cache can prove there is no meaningful delta

package/dist/index.cjs

@@ -154,7 +154,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "imdone-cli",
-      version: "0.74.0",
+      version: "0.74.1",
       author: "Jesse Piascik",
       description: "Turn Jira or GitHub issues into a local Markdown workspace for AI and humans, synced back to your provider.",
       license: "Proprietary",