Open methods, templates, and AI skills for building software as a learning process.
The first included method is Hypothesis Driven Development (HDD): frame the problem, state what you believe will improve, deliver the smallest end-to-end slice, capture evidence, deploy it, and confirm whether the outcome happened.
You can practice HDD without imdone. The public skill works with Markdown files and the issue tracker, editor, or AI coding agent you already use.
- a repository-hosted marketplace for Codex and Claude Code
- one shared plugin under
plugins/product-engineering/ - the full HDD skill, focused references, and plan evaluators
- full and lightweight Markdown story templates
- a plain-Markdown example that does not require a provider integration
- an issue and contribution path for improving the method
New mockups and their supporting assets/renders live in attachments/mockups/ with descriptive revisioned filenames. The story reaches the intended HTML revision through attachment directory READMEs; the HDD agent session review, Design, and Plan link directly to the same accepted artifact. Existing mockup paths and links remain valid. Template-created story files keep their template paths. Every other new HDD-created story artifact goes in a purpose-based subdirectory under attachments/, such as plans/, design/, test-results/, or review-feedback/; use names that describe their contents, keep helpers beside the artifacts they support, follow actual story links, and preserve existing artifact links.
List only root-level attachment files in the issue. Link attachments/README.md for directory navigation; every attachment subdirectory has a README.md with links and descriptions of its files and child directories. The skill checks description growth with an available read-only provider validator; without imdone, its portable helper reports local size and explicitly unverified provider validity. It preserves evidence rather than silently truncating descriptions.
Both Codex and Claude Code use this GitHub repository as the marketplace and install the same product-engineering plugin payload.
codex plugin marketplace add imdone/product-engineering --ref main
codex plugin add product-engineering@product-engineeringclaude plugin marketplace add imdone/product-engineering
claude plugin install product-engineering@product-engineeringnpx skills add imdone/product-engineering --skill hypothesis-driven-developmentThe first public install makes the skill eligible for automatic skills.sh listing through anonymous aggregate install telemetry. Browse the skill at skills.sh/imdone/product-engineering/hypothesis-driven-development.
Then ask your coding agent:
Use the hypothesis-driven-development skill for this story. Read the story and HDD artifacts, then follow the session contract.
Clone this repository:
git clone https://github.com/imdone/product-engineering.git
cd product-engineering
npm testTo practice without an AI plugin loader, copy the full template into your work tracker or repository:
cp templates/hypothesis-driven-development.md my-hdd-story.mdKeep the story plus its evidence together. This plain-Markdown path does not require Codex, Claude Code, or imdone.
- Define the Outcome — confirm the problem, hypothesis, vertical slice, acceptance criteria, success measures, assumptions, and demo.
- Prove the Outcome — design, plan with red/green/refactor, implement top-to-bottom, and run the full project test suite.
- Deploy the Outcome — capture proof that the slice is live in an appropriate place.
- Confirm the Outcome — review done-ness, measure the result, collect direct feedback, and decide whether to close, iterate, or pivot.
During UX-changing Design, HDD links current-state evidence, then creates and reviews a rendered high-fidelity mockup before Plan; Markdown-only artifacts cannot qualify. The plan then derives story-owned tests from the accepted states and viewports, compares rendered implementation evidence with that mockup, and corrects material mismatches before implementation completes. During non-UX Design, it records the reason a mockup is not applicable. For stories requiring a UI change, Full and Lightweight HDD provide a clickable, story-owned HTML mockup in the story and review. The plan links the same accepted HTML artifact and maps its states and viewports to tasks; missing files or a different plan artifact fail validation. Timestamped presentation and decision notes retain feedback and corrections for later outcome measurement.
For low-risk work, lightweight HDD can reduce Define ceremony, but it still needs a minimum success measure before planning: an observable outcome, feedback path, and evidence/data-capture mechanism. Existing full or lightweight closing template metadata selects the saved mode before the skill asks. After the plan is drafted and evaluated, stop at the plan approval checkpoint before implementation or product-code edits; confirm the evaluated plan to continue, or request plan changes.
After accepting the Hypothesis, choose Continue through the evaluated Plan to batch the remaining Define, Design, and Plan edits locally without routine artifact-review or push interruptions. The agent keeps local changes pending while useful work continues. At the evaluated Plan checkpoint, a due reminder may tell you to run imdone push <sessionStoryKey> when ready, without asking for a reply or offering agent execution; product-code edits still require Plan approval.
Full HDD fits ambiguous, high-risk, cross-team, or implementation-heavy work. Lightweight HDD keeps the same evidence and plan-approval discipline while using fewer artifacts for low-risk changes.
HDD is the method. imdone is an optional operational layer for teams that want the story, attachments, chronological notes, and Jira or GitHub state synchronized as shared working memory.
If you want that operational layer, learn more at imdone.io or install the imdone CLI from npm.
The public skill checks whether imdone is installed and whether the current workspace supports its project features. When those deterministic checks pass, it uses imdone for session state, progress notes, templates, and user-approved provider sync; in particular, it tries imdone note before writing a progress note directly. Existing full or lightweight template metadata selects the saved HDD mode before the skill asks a setup question. In an enabled marked session, the retained session story is the automatic note target; an explicitly named Jira key or numeric GitHub issue redirects only that note without changing session or global current state. Push reminders never interrupt useful work or ask the agent to publish changes: at an existing natural stopping point, HDD checks only the retained story and may tell the developer to run imdone push <sessionStoryKey> when ready. If imdone is absent or a command fails, HDD continues with local Markdown and external evidence gates. No imdone command, account, or project configuration is required to practice the method.
For teams using multiple skills, see LIGHTWEIGHT-HDD-WORK-CONTRACT.md; its template is optional.
Open an issue when:
- the workflow is unclear or too heavy
- a template misses a real product-engineering case
- the skill behaves differently across coding agents
- a shared HDD behavior has drifted
See CONTRIBUTING.md before proposing a change.
Before treating the first public version as validated, ask a reviewer:
- What is HDD?
- When would you use it?
- Do you need imdone to try it?
- Where would you give feedback or contribute an improvement?
- What would imdone make easier for a team already using HDD?
The imdone-bundled HDD skill is the authoritative behavior source. When both repositories are available locally, compare the public adaptation with it explicitly:
npm run check:parity -- \
--canonical ../imdone-jira-plugin/cli-package/public/.codex/plugins/imdone/skills/hypothesis-driven-development \
--target ./plugins/product-engineering/skills/hypothesis-driven-developmentThis maintainer check compares shared workflow contracts, guarded optional-imdone integrations, and their tool-neutral fallbacks. It rejects only hard or unguarded imdone dependencies. The published package and its normal npm test run do not require the proprietary repository.