imdone-cli 0.76.0 → 0.77.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog 📝
 
+## 0.77.0
+
+- Let bundled Codex and Claude `imdone` plugins record first-prompt context as local progress notes on the configured active story when a session starts inside the same software project, while later prompts use correction/context judgement and explicit issue/file targets still override the default
+
 ## 0.76.0
 
 - Tell users how to recover when config-dependent commands run outside an initialized imdone project or when the configured backlog checkout is missing, while keeping setup-free commands such as `docs`, `help`, `init`, `clone`, `license`, and `version` available before `.imdone-cli.yml` exists

package/dist/.claude/plugins/imdone/README.md

@@ -2,4 +2,4 @@
 
 This plugin registers the imdone AI correction note hook with Claude-compatible plugin runtimes.
 
-The hook listens for developer prompts that disagree with AI output, ask for an adjustment, add missing context, or report an AI workflow problem such as hooks/plugins not loading. Matching prompts delegate to the bundled `ai-adjustment-note` writer so notes go to the active HDD story when one is configured, or report `needs-target` when the user must choose an issue or file.
+The hook always captures the first prompt in a session when it can identify a new session inside an imdone-enabled software project. Later prompts use judgement: developer disagreement, requested adjustments, added context, or AI workflow problems delegate to the bundled `ai-adjustment-note` writer so notes go to the configured active story when one is configured, or report `needs-target` when the user must choose an issue or file.

package/dist/.claude/plugins/imdone/scripts/ai_adjustment_note_hook.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +13,8 @@ const DISAGREEMENT_PATTERN = /\b(no|nope|not quite|wrong|incorrect|that'?s not|t
 const CONTEXT_PATTERN = /\b(context|more context|additional context|to clarify|clarification|for context|the important part|the point is|the intent is|this is meant to|meant to)\b/i;
 const PROBLEM_SIGNAL_PATTERN = /\b(doesn'?t look like|does not look like|didn'?t|did not|doesn'?t|does not|isn'?t|is not|wasn'?t|was not|won'?t|will not|can'?t|cannot|couldn'?t|could not|failed|fails|failing|failure|not working|isn'?t working|broken|not installed|not loaded|not enabled|not showing|not listed|didn'?t record|did not record|didn'?t capture|did not capture|didn'?t run|did not run|didn'?t trigger|did not trigger|why didn'?t|why did not|should have recorded|should have captured|expected it to)\b/i;
 const AI_WORKFLOW_PATTERN = /\b(ai|agent|codex|claude|hook|plugin|prompt|output|response|capture|record|note|hdd|imdone|runtime|marketplace|install|installed|enabled|loaded)\b/i;
+const FIRST_PROMPT_KEYS = ['isFirstPrompt', 'firstPrompt', 'is_first_prompt', 'first_prompt'];
+const SESSION_ID_KEYS = ['session_id', 'sessionId', 'conversation_id', 'conversationId', 'thread_id', 'threadId', 'chat_id', 'chatId'];
 
 function readStdin() {
   return new Promise(resolve => {
@@ -61,7 +65,85 @@ function extractPrompt(payload) {
     .trim();
 }
 
-function classifyCapture(prompt) {
+function collectValueByKeys(value, keys) {
+  if (!value || typeof value !== 'object') return null;
+
+  for (const key of keys) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) return value[key];
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = collectValueByKeys(item, keys);
+      if (found !== null && found !== undefined) return found;
+    }
+    return null;
+  }
+
+  for (const item of Object.values(value)) {
+    const found = collectValueByKeys(item, keys);
+    if (found !== null && found !== undefined) return found;
+  }
+  return null;
+}
+
+function explicitFirstPrompt(payload) {
+  const value = collectValueByKeys(payload, FIRST_PROMPT_KEYS);
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string' && /^(true|false)$/i.test(value.trim())) return value.trim().toLowerCase() === 'true';
+  return null;
+}
+
+function extractSessionId(payload) {
+  const value = collectValueByKeys(payload, SESSION_ID_KEYS);
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function sessionStatePath(repoRoot) {
+  const projectHash = createHash('sha256').update(repoRoot).digest('hex').slice(0, 16);
+  return path.join(tmpdir(), 'imdone-ai-adjustment-note', `${projectHash}.json`);
+}
+
+function readSeenSessions(repoRoot) {
+  try {
+    const parsed = JSON.parse(readFileSync(sessionStatePath(repoRoot), 'utf8'));
+    return parsed && typeof parsed === 'object' && parsed.sessions && typeof parsed.sessions === 'object'
+      ? parsed.sessions
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function hasSeenSession(repoRoot, sessionId) {
+  return Boolean(readSeenSessions(repoRoot)[sessionId]);
+}
+
+function markSessionSeen(repoRoot, sessionId) {
+  if (!sessionId) return;
+  const stateFile = sessionStatePath(repoRoot);
+  const sessions = readSeenSessions(repoRoot);
+  sessions[sessionId] = new Date().toISOString();
+  mkdirSync(path.dirname(stateFile), { recursive: true });
+  writeFileSync(stateFile, JSON.stringify({ sessions }, null, 2), 'utf8');
+}
+
+function isFirstPrompt(payload, repoRoot) {
+  const explicit = explicitFirstPrompt(payload);
+  if (explicit !== null) return explicit;
+  const sessionId = extractSessionId(payload);
+  return Boolean(sessionId && !hasSeenSession(repoRoot, sessionId));
+}
+
+function classifyCapture(prompt, { firstPrompt = false } = {}) {
+  if (firstPrompt) {
+    return {
+      title: 'AI first prompt captured',
+      change: 'Developer started a prompt in an imdone-enabled software project.',
+      reason: 'Capturing the first prompt preserves plate-spun session context before follow-up judgement applies.'
+    };
+  }
+
   if (DISAGREEMENT_PATTERN.test(prompt) || CONTEXT_PATTERN.test(prompt) || (PROBLEM_SIGNAL_PATTERN.test(prompt) && AI_WORKFLOW_PATTERN.test(prompt))) {
     return {
       title: 'AI correction captured',
@@ -133,12 +215,14 @@ function runWriter({ writer, repoRoot, request, capture }) {
 async function main() {
   const payload = parsePayload(await readStdin());
   const prompt = extractPrompt(payload);
-  const capture = prompt ? classifyCapture(prompt) : null;
-  if (!capture) return;
-
   const scriptDir = path.dirname(fileURLToPath(import.meta.url));
   const startDir = firstString(payload.cwd, payload.projectRoot, payload.workspace, process.env.PWD, process.cwd());
   const repoRoot = findRepoRoot(startDir);
+  const sessionId = extractSessionId(payload);
+  const capture = prompt ? classifyCapture(prompt, { firstPrompt: isFirstPrompt(payload, repoRoot) }) : null;
+  if (sessionId) markSessionSeen(repoRoot, sessionId);
+  if (!capture) return;
+
   const writer = findWriter(repoRoot, scriptDir);
   if (!writer) {
     process.stderr.write('imdone ai-adjustment-note writer was not found; skipping note capture.\n');

package/dist/.claude/plugins/imdone/scripts/record_ai_adjustment_note.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import path from 'node:path';
+import { appendFile, mkdir } from 'node:fs/promises';
 import { execFileSync, spawnSync } from 'node:child_process';
 
 function parseArgs(argv) {
@@ -67,6 +68,44 @@ function runImdone(args, cwd) {
   });
 }
 
+function getGitAuthor(cwd) {
+  const readConfig = (key) => {
+    try {
+      return execFileSync('git', ['-C', cwd, 'config', '--get', key], { encoding: 'utf8' }).trim();
+    } catch {
+      return '';
+    }
+  };
+  const name = readConfig('user.name');
+  const email = readConfig('user.email');
+  if (name && email) return `${name} <${email}>`;
+  if (name) return name;
+  if (email) return `<${email}>`;
+  return 'Unknown user';
+}
+
+function formatIsoWithOffset(date) {
+  const pad = (value, size = 2) => String(value).padStart(size, '0');
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const absoluteOffset = Math.abs(offsetMinutes);
+  return [
+    `${pad(date.getFullYear(), 4)}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`,
+    'T',
+    `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`,
+    `.${pad(date.getMilliseconds(), 3)}`,
+    `${sign}${pad(Math.floor(absoluteOffset / 60))}:${pad(absoluteOffset % 60)}`
+  ].join('');
+}
+
+async function appendFileNote({ filePath, note, cwd }) {
+  const resolvedPath = path.resolve(cwd, filePath);
+  await mkdir(path.dirname(resolvedPath), { recursive: true });
+  const entry = `\n## ${formatIsoWithOffset(new Date())} | ${getGitAuthor(cwd)}\n\n${note}\n`;
+  await appendFile(resolvedPath, entry, 'utf8');
+  return resolvedPath;
+}
+
 function getActiveStory(cwd) {
   const result = runImdone(['agent-config', 'get-active-story'], cwd);
   if (result.status !== 0) return null;
@@ -109,6 +148,15 @@ async function main() {
     return;
   }
 
+  if (options.file) {
+    const filePath = await appendFileNote({ filePath: options.file, note, cwd });
+    process.stdout.write(JSON.stringify({
+      status: 'recorded',
+      target: { type: 'file', filePath }
+    }, null, 2) + '\n');
+    return;
+  }
+
   const issueKey = getActiveStory(cwd);
 
   if (issueKey) {
@@ -127,7 +175,7 @@ async function main() {
 
   process.stdout.write(JSON.stringify({
     status: 'needs-target',
-    message: 'HDD is not active. Ask the user for an imdone issue key before recording.'
+    message: 'No active story is configured. Ask the user for an imdone issue key before recording.'
   }, null, 2) + '\n');
 }
 

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

@@ -5,6 +5,17 @@ description: Guide a story through hypothesis-driven development from user-confi
 
 # Hypothesis-Driven Development
 
+## Tool Availability Boundary
+
+Use imdone only after deterministic command checks:
+- run `imdone --version`; if it exits 0, the `imdone` command is installed
+- run `imdone agent-config get-config`; if it exits 0 with `status: "ok"`, the current workspace is an imdone project for HDD session state and push reminder settings
+- try `imdone note <issueKey> "<note>"` for timestamped progress notes; use the direct Markdown fallback only if `imdone note` is unavailable or exits non-zero for the current workspace
+- use `imdone-template` when a local issue needs the HDD template
+- use `imdone pull`, `imdone push`, and `imdone status` for provider sync when the user chooses to sync
+
+Do not depend on imdone. If the deterministic checks fail, continue the HDD workflow with plain Markdown files in the user's workspace. Store story state in the issue/story file and attachments when they exist, append progress notes directly to `attachments/progress-notes.md` with an ISO timestamp and author when possible only if `imdone note` is unavailable or fails, skip imdone push reminders, and describe sync/publish steps as external evidence gates instead of blocking local HDD work.
+
 ## Operating Model
 
 Guide a story through three outcome-focused phases:
@@ -23,7 +34,7 @@ Purpose:
 - require top-to-bottom implementation: build and execute the red step first, evaluate each markdown task as done before checking it, and do not start the next task while the preceding executable task is unchecked
 - once the plan is accepted, keep implementing until the whole plan is done; do not stop between planned tasks just to ask whether to continue, summarize status, or re-confirm the already-approved direction
 - capture implementation feedback in story artifacts so humans and AI can regain context after interruptions
-- make `attachments/progress-notes.md` the default place to record pivots and corrections through `imdone note`, using `attachments/plan.md` only for the execution plan and task checklist
+- make `attachments/progress-notes.md` the default place to record pivots and corrections, trying `imdone note` first and appending directly to the Markdown file only if `imdone note` is unavailable or fails, using `attachments/plan.md` only for the execution plan and task checklist
 - treat `attachments/demo.md` as a single evolving proof artifact: define it early, then revise it during implementation when the real behavior, commands, or visible outcomes change
 
 Non-goals:
@@ -37,8 +48,8 @@ Before doing workflow work:
 
 1. Read `references/session-setup.md`.
 2. Resolve the story and load only the current story plus its relevant attachments.
-3. Read HDD skill state through `imdone agent-config get-config`. If `push.status` is `missing`, prompt the user for push reminder preferences using the short setup in `references/configuration.md`, then persist the answer with `imdone agent-config set-push-config` before continuing. After push config exists, call `imdone agent-config begin-session` so interval timing starts from the current HDD session. For prompt-reminder config, push timing state, and `active_story` reads and writes, always use `imdone agent-config` instead of local helper scripts or direct YAML edits.
-4. If the story is not already using the HDD template, use the `imdone-template` skill first.
+3. Run the deterministic imdone checks in `references/session-setup.md`. If `imdone agent-config get-config` exits 0 with `status: "ok"`, read HDD skill state from that result. If `push.status` is `missing`, prompt the user for push reminder preferences using the short setup in `references/configuration.md`, then persist the answer with `imdone agent-config set-push-config` before continuing. After push config exists, call `imdone agent-config begin-session` so interval timing starts from the current HDD session. For prompt-reminder config, push timing state, and `active_story` reads and writes in an imdone project, always use `imdone agent-config` instead of local helper scripts or direct YAML edits. If the deterministic checks fail, skip push reminder setup and keep session state in the current Markdown artifacts.
+4. If the story is not already using the HDD template, use the `imdone-template` skill first when imdone is available. If imdone is unavailable, repair the Markdown structure directly using the current HDD headings and attachments described in `references/session-setup.md`.
 5. Make sure the issue file links to every issue attachment that exists so artifacts are easy to find from the story. If the template already includes a link, leave it where it is. Duplicate links are acceptable.
 6. Read `references/interaction-contract.md` and follow it throughout the session.
 
@@ -97,7 +108,7 @@ Order:
 Write locations:
 - Design: `attachments/design.md` and at least one Mermaid diagram in `attachments/diagram.md`
 - Plan: `attachments/plan.md` using explicit red/green/refactor sequencing
-- Progress notes from feedback, pivots, and discovered constraints: record new notes with `imdone note <issueKey> "<note>"` into `attachments/progress-notes.md`; read legacy `Progress notes:` in `attachments/plan.md` only as backward-compatible context
+- Progress notes from feedback, pivots, and discovered constraints: try `imdone note <issueKey> "<note>"` into `attachments/progress-notes.md` first; append directly to `attachments/progress-notes.md` with an ISO timestamp and author only if `imdone note` is unavailable or exits non-zero for the current workspace. Read legacy `Progress notes:` in `attachments/plan.md` only as backward-compatible context.
 
 Load `references/prove-the-outcome.md` only when working this phase.
 Use it for implementation hygiene guidance, including DRY cleanup in touched flows and code-as-documentation defaults.
@@ -148,23 +159,23 @@ Load only the reference file needed for the current decision:
 - Safe to re-run after interruption.
 - Prefer updating current story artifacts over free-floating advice.
 - 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.
+- In imdone projects, 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. Outside imdone projects, skip agent-config behavior and keep state in the current Markdown artifacts.
+- Before any push reminder in an imdone project, check `imdone agent-config get-config` and only ask whether to run `imdone push` when `push.imdoneStatus.hasPendingChanges` is true. If imdone is unavailable, do not ask for `imdone push`; record any publish/sync need as an external evidence gate.
 - Do not mark Hypothesis complete until `## Problem Framing` exists and the user has provided or confirmed it during the HDD session.
 - After Hypothesis is complete, ask once whether to continue through the remaining HDD workflow without routine per-artifact interruption. Respect the chosen continuation scope until a blocker, missing decision, external evidence gate, major pivot, push prompt, or user correction requires stopping.
 - 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`
+- In `interval_prompt` mode inside an imdone project, 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 in an imdone project, 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`. When imdone is unavailable, use the visible indicator without an imdone version, for example: `🧭 HDD | Story — Short summary`
 - When progress notes are recorded, explicitly say so in the user-facing message after the story footer, using a visible indicator such as: `📝 Progress note recorded in attachments/progress-notes.md`
 - Rely on the tool's built-in edit diff. In chat, list changed file paths and summarize the change instead of replaying diffs.
 - Default recording pattern for pivots and corrections:
   - update the affected phase steps in `attachments/plan.md`
-  - record a short progress note with `imdone note <issueKey> "<note>"` for what changed, why it changed, and what must be remembered
-  - let `imdone note` add the author and full ISO timestamp in `attachments/progress-notes.md`
+  - record a short progress note with `imdone note <issueKey> "<note>"` first; append directly to `attachments/progress-notes.md` only if `imdone note` is unavailable or fails, for what changed, why it changed, and what must be remembered
+  - let `imdone note` add the author and full ISO timestamp when available; otherwise include the best available author and a full ISO timestamp in the Markdown note
   - add a new attachment only when the plan is no longer enough to recover the reasoning or boundary cleanly
 - No supported skill alias field was found in the current local skill format, so keep the canonical skill name `hypothesis-driven-development` unless alias support is added to the skill loader.
 - If the next honest step is outside the tool boundary, record the unblock note or evidence gate instead of pretending the story can advance locally.
-- In `phase_prompt` push mode, prompt for `imdone push` after the first real write to `attachments/plan.md` and again after any progress note is recorded in `attachments/progress-notes.md`, not only at the end of a phase.
+- In `phase_prompt` push mode inside an imdone project, prompt for `imdone push` after the first real write to `attachments/plan.md` and again after any progress note is recorded in `attachments/progress-notes.md`, not only at the end of a phase. If imdone is unavailable, skip push prompts.
 - If a follow-on step involves creating issues with `imdone add` or the `imdone-add` skill, treat creation as a serialized repo operation. Do not run multiple `imdone add` commands in parallel in the same repo unless a later implementation explicitly proves that concurrent create flows are safe for git state, attachment upload, and local issue refresh.
 - During Phase 2, do not draft Design, Plan, or Implement artifacts from only the active story. First load the relevant expert reference, then search current backlog stories and the configured archive for similar hypotheses, acceptance criteria, plans, or outcomes. Summarize only the useful prior context; do not bulk-load unrelated archived work.
 - Before checking Implement complete, run the full project test suite from the plan's final confirmation phase after all focused checks are green. If the full suite fails, fix the failure or record a concrete blocker and leave Implement unchecked.

package/dist/.claude/skills/hypothesis-driven-development/references/interaction-contract.md

@@ -23,13 +23,13 @@ Use this throughout the workflow.
 - Preserve clean dependency direction, but do not invent abstractions early. When a new use case creates a real axis of change, the dependency-rule refactor is part of implementation completion, not optional follow-up work.
 - Red/green/refactor and top-to-bottom task order are mandatory during implementation. Build and execute red first, evaluate each task before checking it, check it before starting the next task, and stop if the preceding executable task is still unchecked.
 - Treat `attachments/plan.md` as a live artifact. When implementation changes the path, update the plan immediately.
-- When the user provides implementation feedback, decisions, corrections, or newly discovered constraints, update affected plan steps in `attachments/plan.md` when the execution path changes, and record the chronological note with `imdone note <issueKey> "<note>"` instead of leaving that context only in chat.
+- When the user provides implementation feedback, decisions, corrections, or newly discovered constraints, update affected plan steps in `attachments/plan.md` when the execution path changes, and record the chronological note by trying `imdone note <issueKey> "<note>"` first. Append the note directly to `attachments/progress-notes.md` with an ISO timestamp and author only if `imdone note` is unavailable or exits non-zero for the current workspace.
 - Create additional attachments when warranted for clarity and resumability, for example focused test notes, rollout notes, API notes, review context, or diagrams.
 - Use this default recording pattern:
   - update `attachments/plan.md` only when the execution path, tasks, or checklist changes
-  - call `imdone note <issueKey> "<note>"` for what changed in execution, status, or next step
+  - try `imdone note <issueKey> "<note>"` first; append directly to `attachments/progress-notes.md` only if `imdone note` is unavailable or exits non-zero for the current workspace
   - include why the path changed, what feedback or constraint caused it, and what another human or AI should not have to rediscover
-  - let `imdone note` write the full ISO timestamp and author into `attachments/progress-notes.md`
+  - let `imdone note` write the full ISO timestamp and author into `attachments/progress-notes.md` when available; otherwise write the timestamp and best available author directly
 - Prefer the plan over a new attachment unless the context would be hard to recover from the plan alone.
 - Periodically check shared-context fitness, especially after pivots, blocker discovery, PR creation, before checking Implement complete, and before closing the story.
 - Keep the user in the loop when the plan changes: state what changed, why it changed, and the new next step before or while editing the plan.
@@ -97,17 +97,18 @@ If the user chooses option 1 or 2:
 ## Sync Behavior
 
 - detect the provider from the story metadata comment before using provider-specific wording; use `jira:` or `github:` markers as the source of truth
-- Use `imdone pull` when the local story needs the latest provider state before continuing.
+- Use `imdone pull` when imdone is available and the local story needs the latest provider state before continuing.
+- If imdone is unavailable, skip provider sync commands and record the needed provider refresh, publication, or review as an external evidence gate.
 - If a sync conflict occurs during `imdone push`, resolve the file conflict, then run `imdone merge` before continuing.
-- Follow `references/configuration.md` for push defaults and prompt behavior.
-- Before asking whether to run `imdone push`, check `imdone agent-config get-config` and only prompt when `push.imdoneStatus.hasPendingChanges` is true. If `imdone status` reports `Nothing to push`, skip the reminder.
+- Follow `references/configuration.md` for push defaults and prompt behavior only in imdone projects.
+- Before asking whether to run `imdone push`, check `imdone agent-config get-config` and only prompt when `push.imdoneStatus.hasPendingChanges` is true. If `imdone status` reports `Nothing to push`, skip the reminder. If imdone is unavailable, do not ask for `imdone push`.
 - If push behavior is configured as `interval_prompt`, call `imdone agent-config get-config` before substantial work cycles and when deciding whether to prompt, and use `push.promptDue`, `push.elapsedMinutes`, and `push.nextPromptAt` instead of rough mental timing.
 - In `interval_prompt` mode, call `imdone agent-config record-push-prompt` every time the workflow actually asks whether to run `imdone push`, including prompts triggered by elapsed time, major checkpoints, or explicit user requests.
 - After `imdone push` succeeds, do not call an HDD-only sync timestamp setter. The `imdone push` command owns successful push sync timestamp recording; refresh state with `imdone agent-config get-config` when the workflow needs the updated timing.
-- If `attachments/plan.md` is created from placeholder content into a real plan, treat that as a push-worthy checkpoint in `phase_prompt` mode.
-- If a progress note is recorded in `attachments/progress-notes.md`, treat that as a push-worthy checkpoint in `phase_prompt` mode because resumability context changed materially.
+- If `attachments/plan.md` is created from placeholder content into a real plan in an imdone project, treat that as a push-worthy checkpoint in `phase_prompt` mode.
+- If a progress note is recorded in `attachments/progress-notes.md` in an imdone project, treat that as a push-worthy checkpoint in `phase_prompt` mode because resumability context changed materially.
 
-After each phase:
+After each phase in an imdone project:
 - if `push.mode` is `phase_prompt`, ask:
   ```text
   Phase complete. Push changes now? (imdone push)
@@ -134,4 +135,4 @@ After each phase:
   ```
 - if `push.mode` is `interval_prompt` and `push.promptDue` is false, do not ask to push yet; if `imdone status` is clean, say nothing about pushing
 
-If the user chooses yes, run `imdone push`, then call `imdone agent-config get-config` if the workflow needs refreshed timing. If no, leave the interval overdue state intact and remind the user to push before ending the session.
+If the user chooses yes, run `imdone push`, then call `imdone agent-config get-config` if the workflow needs refreshed timing. If no, leave the interval overdue state intact and remind the user to push before ending the session. If imdone is unavailable, skip this push prompt behavior entirely.

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

@@ -122,10 +122,10 @@ Before drafting or revising Design, Plan, or Implement:
 
 - Preserve completed phases.
 - Update remaining phases to match what has been learned.
-- Add a short progress note for pivots, new constraints, or eliminated risks with `imdone note <issueKey> "<note>"`.
-- During implementation, capture user feedback and newly learned constraints in `attachments/progress-notes.md` through `imdone note` instead of leaving them only in conversation history.
+- Add a short progress note for pivots, new constraints, or eliminated risks by trying `imdone note <issueKey> "<note>"` first. Append directly to `attachments/progress-notes.md` only if `imdone note` is unavailable or exits non-zero for the current workspace.
+- During implementation, capture user feedback and newly learned constraints in `attachments/progress-notes.md` through `imdone note` when that command succeeds, or direct Markdown append only when `imdone note` is unavailable or fails, instead of leaving them only in conversation history.
 - Use progress notes to capture both "what changed" and "why it changed" plus what must be remembered.
-- Let `imdone note` add the full ISO timestamp and author, so resumability includes ordering within the day.
+- Let `imdone note` add the full ISO timestamp and author when available; otherwise write the timestamp and best available author directly, so resumability includes ordering within the day.
 - Tell the user which phase changed and the new execution path.
 - Keep completed checklist items checked and leave future work unchecked.
 - If the pivot is significant, ask one alignment or comprehension question before rewriting multiple phases.
@@ -150,11 +150,11 @@ Before drafting or revising Design, Plan, or Implement:
 - Use code as documentation: prefer readable module boundaries, good function names, explicit data flow, and behavior-focused tests. Add comments only when the code cannot reasonably explain itself.
 - Keep `attachments/demo.md` current during implementation. If the built path, visible outcome, fallback behavior, or operator steps change, revise the existing demo plan instead of creating a second demo artifact.
 - If the root cause changes, update `attachments/plan.md` before continuing.
-- If the user changes direction, clarifies scope, or gives implementation feedback, update affected plan steps in `attachments/plan.md` immediately and record the changed path and reason with `imdone note`.
+- If the user changes direction, clarifies scope, or gives implementation feedback, update affected plan steps in `attachments/plan.md` immediately and record the changed path and reason with `imdone note` first, falling back to a direct progress-note append only if `imdone note` is unavailable or fails.
 - Add a new attachment when the implementation feedback would be hard to recover from the plan alone, such as a focused note for testing, rollout, API contract, review context, or a clarifying diagram.
 - Prefer this pattern:
   - update the affected phase tasks in `attachments/plan.md`
-  - run `imdone note <issueKey> "<old next step, new next step, status change, reason for the pivot, user feedback, discovered constraint, or warning for future resumption>"`
+  - run `imdone note <issueKey> "<old next step, new next step, status change, reason for the pivot, user feedback, discovered constraint, or warning for future resumption>"` first, or append that note directly to `attachments/progress-notes.md` only if `imdone note` is unavailable or fails
 - Before checking `Implement` complete, make sure `attachments/demo.md` still matches the real behavior well enough for another human or AI to show the slice without reconstructing the flow from memory.
 - Before checking `Implement` complete, run the full project test suite from the plan's final confirmation phase after focused checks and artifact-specific verification are green. If the full suite fails, treat that as implementation feedback: fix it, update the plan if the path changes, and do not check Implement complete until the full suite passes or a concrete blocker is recorded.
 - If the next unchecked item requires a real-world meeting, deployment, customer action, or other external evidence, stop local implementation at that evidence gate. Record the blocker, the required outside action, and where the resulting evidence must be captured before more boxes are checked.

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

@@ -14,7 +14,7 @@ Use the story attachments as the source of truth:
 - `attachments/dod.md`
 - `attachments/hdd-skill-feedback.md` if present
 - `attachments/hdd-skill-feedback.json` if present
-- `backlog/.imdone/agent-config.yml` if present through `imdone agent-config`; do not read or edit it directly
+- `backlog/.imdone/agent-config.yml` if imdone is available, read through `imdone agent-config`; do not read or edit it directly
 
 If an attachment is empty, placeholder-only, or still stock-template content, use `.imdone/templates/stock/hypothesis-driven-development.md` and the referenced partial in `.imdone/templates/stock/partials/` as fallback.
 
@@ -23,15 +23,24 @@ If an attachment file is missing:
 - do not pre-seed later-phase attachments unless the workflow has actually reached that phase
 - keep placeholder-only future-phase files out of the way unless the story already links to them and the user wants them created now
 
-## Check Push Reminder Setup
+## Deterministic Tool Availability And Push Reminder Setup
 
-Before resolving the story, call `imdone agent-config get-config`.
+Before resolving the story, determine imdone availability with these deterministic checks:
 
-- if `push.status` is `configured`, use the stored reminder settings for this session
-- if `push.status` is `missing`, ask the user to choose their push reminder behavior using `references/configuration.md`, then persist it with `imdone agent-config set-push-config` before continuing
-- when checking whether to remind about pushing, use the `imdone status` result returned by `get-config`; only prompt when pending changes exist
-- do not silently accept smart defaults when push config is missing; present them as the default option the user can choose
+1. Run `imdone --version`.
+   - Exit 0 means the `imdone` command is installed.
+   - Non-zero exit or command-not-found means imdone command features are unavailable.
+2. If `imdone --version` succeeds, run `imdone agent-config get-config`.
+   - Exit 0 with JSON `status: "ok"` means the current workspace is initialized enough for HDD session state and push reminder behavior.
+   - Non-zero exit or a non-ok status means do not use `imdone agent-config`, push reminders, active-story persistence, or provider sync prompts for this session.
+3. For progress notes, use a separate command-specific check: try `imdone note <issueKey> "<note>"` when a note must be recorded. Append directly to `attachments/progress-notes.md` only if `imdone note` is unavailable or exits non-zero for the current workspace.
+
+- if imdone is available and `push.status` is `configured`, use the stored reminder settings for this session
+- if imdone is available and `push.status` is `missing`, ask the user to choose their push reminder behavior using `references/configuration.md`, then persist it with `imdone agent-config set-push-config` before continuing
+- when checking whether to remind about pushing in an imdone project, use the `imdone status` result returned by `get-config`; only prompt when pending changes exist
+- do not silently accept smart defaults when push config is missing in an imdone project; present them as the default option the user can choose
 - after push config exists, call `imdone agent-config begin-session` so interval timing starts from this HDD session instead of stale wall-clock time from an older run
+- if the deterministic checks fail, skip push reminder setup and use plain Markdown artifacts as the session state; record provider sync or publishing as an external evidence gate when needed
 
 ## Resolve The Story
 
@@ -40,13 +49,13 @@ If an issue key is provided, open:
 
 If no issue key is provided:
 - prefer the story already active in this conversation
-- otherwise call `imdone agent-config get-active-story` to check for one saved local HDD story
+- otherwise, when imdone is available, call `imdone agent-config get-active-story` to check for one saved local HDD story
 - if the helper returns a valid story path, use that story
 - otherwise use the most recently modified `backlog/current-sprint/*/issue-*.md`
 - confirm the candidate with the user before editing
 
 After the story is confirmed, read the story and all relevant attachments before asking anything.
-After the story is confirmed, call `imdone agent-config set-active-story --key <issueKey>` so the next no-key HDD session can resume that story.
+After the story is confirmed in an imdone project, call `imdone agent-config set-active-story --key <issueKey>` so the next no-key HDD session can resume that story. If imdone is unavailable, rely on the conversation and local Markdown paths for resumption.
 
 Detect the issue provider from the issue file metadata comment before using provider-specific language or assumptions:
 - read the closing HTML comment in the issue markdown
@@ -62,7 +71,7 @@ Use the issue file as the attachment index for issue attachments:
 - duplicate links are acceptable when adding a missing link is simpler than normalizing existing ones
 - keep links current when attachment names change or when new focused attachments are added for clarity
 
-If the story is not already using the HDD template, use the `imdone-template` skill before continuing:
+If the story is not already using the HDD template, use the `imdone-template` skill before continuing when imdone is available:
 - detect this by the absence of `#HDD-template` in the issue content or by obviously missing HDD template structure
 - 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
@@ -70,6 +79,8 @@ If the story is not already using the HDD template, use the `imdone-template` sk
 - 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 imdone is unavailable, repair the Markdown structure directly using the same expected headings and attachment filenames instead of blocking on template tooling.
+
 If the story already has `#HDD-template` but its sections, headings, or checklist order no longer match the current bundled HDD format:
 - treat it as an outdated HDD story that should be repaired with the user, not ignored
 - explain what is out of alignment before editing, for example missing checklist items, old heading names, or section order drift

package/dist/.claude/skills/hypothesis-driven-development/scripts/evaluate_progress_notes_contract.mjs

@@ -19,8 +19,11 @@ function main() {
     .toLowerCase();
   const errors = [];
 
-  if (!combined.includes("imdone note")) {
-    errors.push("HDD progress-note guidance must tell agents to record new notes with `imdone note`.");
+  if (!combined.includes("imdone note") || !combined.includes("try `imdone note")) {
+    errors.push("HDD progress-note guidance must tell agents to try `imdone note` first.");
+  }
+  if (!combined.includes("append") || !combined.includes("only if `imdone note` is unavailable")) {
+    errors.push("HDD progress-note guidance must allow direct Markdown appends only when `imdone note` is unavailable or fails.");
   }
   if (!combined.includes("attachments/progress-notes.md")) {
     errors.push("HDD progress lookup must name `attachments/progress-notes.md` as the canonical progress-note artifact.");
@@ -34,7 +37,7 @@ function main() {
     return 1;
   }
 
-  console.log("OK: HDD progress-note guidance uses imdone note with progress-notes.md and legacy plan fallback.");
+  console.log("OK: HDD progress-note guidance tries imdone note first, uses direct Markdown fallback only when needed, and keeps legacy plan fallback.");
   return 0;
 }
 

package/dist/.codex/plugins/imdone/README.md

@@ -2,4 +2,4 @@
 
 This plugin registers the imdone AI correction note hook with Codex-compatible plugin runtimes.
 
-The hook listens for developer prompts that disagree with AI output, ask for an adjustment, add missing context, or report an AI workflow problem such as hooks/plugins not loading. Matching prompts delegate to the bundled `ai-adjustment-note` writer so notes go to the active HDD story when one is configured, or report `needs-target` when the user must choose an issue or file.
+The hook always captures the first prompt in a session when it can identify a new session inside an imdone-enabled software project. Later prompts use judgement: developer disagreement, requested adjustments, added context, or AI workflow problems delegate to the bundled `ai-adjustment-note` writer so notes go to the configured active story when one is configured, or report `needs-target` when the user must choose an issue or file.

package/dist/.codex/plugins/imdone/scripts/ai_adjustment_note_hook.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +13,8 @@ const DISAGREEMENT_PATTERN = /\b(no|nope|not quite|wrong|incorrect|that'?s not|t
 const CONTEXT_PATTERN = /\b(context|more context|additional context|to clarify|clarification|for context|the important part|the point is|the intent is|this is meant to|meant to)\b/i;
 const PROBLEM_SIGNAL_PATTERN = /\b(doesn'?t look like|does not look like|didn'?t|did not|doesn'?t|does not|isn'?t|is not|wasn'?t|was not|won'?t|will not|can'?t|cannot|couldn'?t|could not|failed|fails|failing|failure|not working|isn'?t working|broken|not installed|not loaded|not enabled|not showing|not listed|didn'?t record|did not record|didn'?t capture|did not capture|didn'?t run|did not run|didn'?t trigger|did not trigger|why didn'?t|why did not|should have recorded|should have captured|expected it to)\b/i;
 const AI_WORKFLOW_PATTERN = /\b(ai|agent|codex|claude|hook|plugin|prompt|output|response|capture|record|note|hdd|imdone|runtime|marketplace|install|installed|enabled|loaded)\b/i;
+const FIRST_PROMPT_KEYS = ['isFirstPrompt', 'firstPrompt', 'is_first_prompt', 'first_prompt'];
+const SESSION_ID_KEYS = ['session_id', 'sessionId', 'conversation_id', 'conversationId', 'thread_id', 'threadId', 'chat_id', 'chatId'];
 
 function readStdin() {
   return new Promise(resolve => {
@@ -61,7 +65,85 @@ function extractPrompt(payload) {
     .trim();
 }
 
-function classifyCapture(prompt) {
+function collectValueByKeys(value, keys) {
+  if (!value || typeof value !== 'object') return null;
+
+  for (const key of keys) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) return value[key];
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = collectValueByKeys(item, keys);
+      if (found !== null && found !== undefined) return found;
+    }
+    return null;
+  }
+
+  for (const item of Object.values(value)) {
+    const found = collectValueByKeys(item, keys);
+    if (found !== null && found !== undefined) return found;
+  }
+  return null;
+}
+
+function explicitFirstPrompt(payload) {
+  const value = collectValueByKeys(payload, FIRST_PROMPT_KEYS);
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string' && /^(true|false)$/i.test(value.trim())) return value.trim().toLowerCase() === 'true';
+  return null;
+}
+
+function extractSessionId(payload) {
+  const value = collectValueByKeys(payload, SESSION_ID_KEYS);
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function sessionStatePath(repoRoot) {
+  const projectHash = createHash('sha256').update(repoRoot).digest('hex').slice(0, 16);
+  return path.join(tmpdir(), 'imdone-ai-adjustment-note', `${projectHash}.json`);
+}
+
+function readSeenSessions(repoRoot) {
+  try {
+    const parsed = JSON.parse(readFileSync(sessionStatePath(repoRoot), 'utf8'));
+    return parsed && typeof parsed === 'object' && parsed.sessions && typeof parsed.sessions === 'object'
+      ? parsed.sessions
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function hasSeenSession(repoRoot, sessionId) {
+  return Boolean(readSeenSessions(repoRoot)[sessionId]);
+}
+
+function markSessionSeen(repoRoot, sessionId) {
+  if (!sessionId) return;
+  const stateFile = sessionStatePath(repoRoot);
+  const sessions = readSeenSessions(repoRoot);
+  sessions[sessionId] = new Date().toISOString();
+  mkdirSync(path.dirname(stateFile), { recursive: true });
+  writeFileSync(stateFile, JSON.stringify({ sessions }, null, 2), 'utf8');
+}
+
+function isFirstPrompt(payload, repoRoot) {
+  const explicit = explicitFirstPrompt(payload);
+  if (explicit !== null) return explicit;
+  const sessionId = extractSessionId(payload);
+  return Boolean(sessionId && !hasSeenSession(repoRoot, sessionId));
+}
+
+function classifyCapture(prompt, { firstPrompt = false } = {}) {
+  if (firstPrompt) {
+    return {
+      title: 'AI first prompt captured',
+      change: 'Developer started a prompt in an imdone-enabled software project.',
+      reason: 'Capturing the first prompt preserves plate-spun session context before follow-up judgement applies.'
+    };
+  }
+
   if (DISAGREEMENT_PATTERN.test(prompt) || CONTEXT_PATTERN.test(prompt) || (PROBLEM_SIGNAL_PATTERN.test(prompt) && AI_WORKFLOW_PATTERN.test(prompt))) {
     return {
       title: 'AI correction captured',
@@ -133,12 +215,14 @@ function runWriter({ writer, repoRoot, request, capture }) {
 async function main() {
   const payload = parsePayload(await readStdin());
   const prompt = extractPrompt(payload);
-  const capture = prompt ? classifyCapture(prompt) : null;
-  if (!capture) return;
-
   const scriptDir = path.dirname(fileURLToPath(import.meta.url));
   const startDir = firstString(payload.cwd, payload.projectRoot, payload.workspace, process.env.PWD, process.cwd());
   const repoRoot = findRepoRoot(startDir);
+  const sessionId = extractSessionId(payload);
+  const capture = prompt ? classifyCapture(prompt, { firstPrompt: isFirstPrompt(payload, repoRoot) }) : null;
+  if (sessionId) markSessionSeen(repoRoot, sessionId);
+  if (!capture) return;
+
   const writer = findWriter(repoRoot, scriptDir);
   if (!writer) {
     process.stderr.write('imdone ai-adjustment-note writer was not found; skipping note capture.\n');