Turn story work into product engineering lab notes.

Before you start

• Node.js 22 or newer if you install from npm.
• git and a project directory. Run imdone init from your repo.
• Jira or GitHub access with permission to read and update issues.
• macOS arm64 users who do not want the npm path can use the standalone installer at the bottom of this page.

The package is imdone-cli. It installs the imdone command.

Install and Sync

Start in the repo where the team's working memory should live. imdone creates a local Markdown backlog for Jira or GitHub issues, then keeps the useful parts synced with the provider. Use this npm path when you already have Node installed. The standalone macOS installer is available at the bottom of the page.

What appears in your repo

imdone stores issue content, comments, lifecycle history, attachments, progress notes, and sync metadata as local files you can inspect with your editor, grep, diffs, and AI coding agents.

>tree backlog
backlog
├── .imdone
│   └── config.yml
└── current-sprint
    └── SCRUM-123-Example_issue
        ├── attachments
        │   └── .metadata.yml
        ├── comments-SCRUM-123.md
        ├── issue-SCRUM-123.md
        └── changelog.yml

The backlog is the lab notebook. Each issue folder is a workspace entry where teams can keep hypotheses, acceptance criteria, implementation plans, observations, evidence, decisions, blockers, and next steps attached to the story.

System metadata lives in HTML comments at the end of issue files. Leave it intact so imdone can map local files back to provider issues.

Open the generated Markdown, capture one evidence-bearing progress note or story update, then push the useful context back.

Common commands

Use the AI commands when you want the story record to travel with the coding session. Use imdone ai for lightweight story context, and imdone hdd when the team needs the full Hypothesis-Driven Development workflow.

Work with AI agents

• imdone ai KEY starts a lightweight AI-assisted story session with the issue, comments, attachments, and progress notes in context.
• imdone hdd KEY starts a full Hypothesis-Driven Development session for shaping, planning, implementing, measuring, and learning from a story.

Read provider context

• imdone pull fetches issues, comments, and attachments.
• imdone show KEY inspects one issue.
• imdone list lists local issues.

Write local changes

• imdone push syncs local Markdown updates back.
• imdone note KEY "Observation: ... Evidence: ... Decision: ... Next: ..." records durable progress notes for humans and AI agents.
• imdone add creates a new issue.
• imdone move KEY "In Progress" changes status.
• imdone merge resolves sync conflicts locally.
• imdone docs opens the imdone-cli docs in your browser.

Where to go next

Use the full CLI docs for provider setup, command reference, Git behavior, attachments, AI skills, and troubleshooting.

macOS download

Download the macOS arm64 DMG, run the pkg inside it, then verify the installed imdone command from Terminal. This path is for Mac users who want the runtime included; the npm install above remains the primary cross-platform quick start.

If macOS blocks the installer because it is not signed or notarized yet, use the npm fallback while the standalone release path is finalized.