issy 0.10.1 → 0.11.1

package/README.md

@@ -151,7 +151,6 @@ issy update 0001 --body "New details"     # Replace body content
 issy close 0001               # Close issue
 issy reopen 0001 --after 0004 # Reopen and place in roadmap
 issy learn                    # Print compact AI-agent instructions
-issy learn roadmap            # Print focused topic instructions
 issy skill install            # Install the AI bootstrap skill
 issy migrate                  # Migrate from .issues/ to .issy/
 issy --version                # Check version
@@ -187,6 +186,8 @@ Issues can declare blockers with `depends_on`:
 depends_on: 0012, 0035
 ```
 
+Roadmap placement is validated against open dependencies. An open issue must appear after every open issue it depends on, and `create`, `update`, or `reopen` fails if the requested position would put a blocked issue before one of its blockers.
+
 ### Hooks
 
 issy supports optional hook files in `.issy/` that inject context into stdout after successful operations. The file contents are printed directly, making them visible to AI agents in their command output.

package/dist/cli.js

@@ -404,6 +404,41 @@ function getBlockingIssues(issue, issues) {
 function isIssueUnblocked(issue, issues) {
   return issue.frontmatter.status === "open" && getBlockingIssues(issue, issues).length === 0;
 }
+function compareIssuesByRoadmapOrder(a, b) {
+  const orderA = a.frontmatter.order;
+  const orderB = b.frontmatter.order;
+  if (orderA && orderB) {
+    if (orderA < orderB)
+      return -1;
+    if (orderA > orderB)
+      return 1;
+  }
+  if (orderA && !orderB)
+    return -1;
+  if (!orderA && orderB)
+    return 1;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function validateRoadmapDependencyOrder(issues) {
+  const openIssues = issues.filter((issue) => issue.frontmatter.status === "open").sort(compareIssuesByRoadmapOrder);
+  const positionById = new Map(openIssues.map((issue, index) => [issue.id, index]));
+  const violations = [];
+  for (const issue of openIssues) {
+    const issuePosition = positionById.get(issue.id);
+    if (issuePosition === undefined)
+      continue;
+    for (const dependency of getBlockingIssues(issue, issues)) {
+      const dependencyPosition = positionById.get(dependency.id);
+      if (dependencyPosition === undefined || dependencyPosition < issuePosition) {
+        continue;
+      }
+      violations.push(`#${issue.id} depends on #${dependency.id}`);
+    }
+  }
+  if (violations.length > 0) {
+    throw new Error(`Roadmap dependency order invalid: ${violations.join("; ")}. Issues must be placed after all open issues they depend on.`);
+  }
+}
 function getIssueIdFromFilename(filename) {
   const match = filename.match(/^(\d+)-/);
   return match ? match[1] : filename.replace(".md", "");
@@ -460,17 +495,7 @@ async function getAllIssues() {
       content: body
     });
   }
-  return issues.sort((a, b) => {
-    const orderA = a.frontmatter.order;
-    const orderB = b.frontmatter.order;
-    if (orderA && orderB)
-      return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-    if (orderA && !orderB)
-      return -1;
-    if (!orderA && orderB)
-      return 1;
-    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-  });
+  return issues.sort(compareIssuesByRoadmapOrder);
 }
 async function getOpenIssuesByOrder() {
   const allIssues = await getAllIssues();
@@ -558,8 +583,7 @@ async function createIssue(input) {
   const content = `${generateFrontmatter(frontmatter)}
 ${body}
 `;
-  await writeFile(join(getIssuesDir(), filename), content);
-  return {
+  const newIssue = {
     id: issueNumber,
     filename,
     frontmatter,
@@ -567,6 +591,9 @@ ${body}
 ${body}
 `
   };
+  validateRoadmapDependencyOrder([...existingIssues, newIssue]);
+  await writeFile(join(getIssuesDir(), filename), content);
+  return newIssue;
 }
 async function updateIssue(id, input) {
   const issue = await getIssue(id);
@@ -596,12 +623,16 @@ ${input.body}
 ` : issue.content;
   const content = `${generateFrontmatter(updatedFrontmatter)}
 ${updatedContent}`;
-  await writeFile(join(getIssuesDir(), issue.filename), content);
-  return {
+  const updatedIssue = {
     ...issue,
     frontmatter: updatedFrontmatter,
     content: updatedContent
   };
+  if (input.order !== undefined || input.depends_on !== undefined || input.status === "open") {
+    validateRoadmapDependencyOrder(allIssues.map((current) => current.id === issue.id ? updatedIssue : current));
+  }
+  await writeFile(join(getIssuesDir(), issue.filename), content);
+  return updatedIssue;
 }
 async function closeIssue(id) {
   return updateIssue(id, { status: "closed" });
@@ -2002,17 +2033,7 @@ function createSearchIndex(issues) {
 function sortIssues(issues, sortBy) {
   const sortOption = sortBy.toLowerCase();
   if (sortOption === "roadmap") {
-    issues.sort((a, b) => {
-      const orderA = a.frontmatter.order;
-      const orderB = b.frontmatter.order;
-      if (orderA && orderB)
-        return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-      if (orderA && !orderB)
-        return -1;
-      if (!orderA && orderB)
-        return 1;
-      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-    });
+    issues.sort(compareIssuesByRoadmapOrder);
   } else if (sortOption === "priority") {
     const priorityOrder = {
       high: 0,
@@ -2066,17 +2087,7 @@ function sortIssues(issues, sortBy) {
   } else if (sortOption === "id") {
     issues.sort((a, b) => b.id.localeCompare(a.id));
   } else {
-    issues.sort((a, b) => {
-      const orderA = a.frontmatter.order;
-      const orderB = b.frontmatter.order;
-      if (orderA && orderB)
-        return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-      if (orderA && !orderB)
-        return -1;
-      if (!orderA && orderB)
-        return 1;
-      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-    });
+    issues.sort(compareIssuesByRoadmapOrder);
   }
 }
 function filterByQuery(issues, query) {
@@ -2490,9 +2501,7 @@ Commands:
 
   next                    Show the next issue to work on
 
-  learn [topic]           Print AI-agent instructions for this issy version
-    --all                 Print the full reference
-    --list                List focused topics
+  learn                   Print AI-agent instructions for this issy version
 
   create                  Create a new issue
     --title, -t <t>       Issue title
@@ -2536,7 +2545,6 @@ Examples:
   issy list --priority high --type bug
   issy next
   issy learn
-  issy learn roadmap
   issy read 0001
   issy create --title "Fix login bug" --type bug --priority high --after 0002
   issy create --title "Add dark mode" --last

package/dist/main.js

@@ -415,6 +415,41 @@ function getBlockingIssues(issue, issues) {
 function isIssueUnblocked(issue, issues) {
   return issue.frontmatter.status === "open" && getBlockingIssues(issue, issues).length === 0;
 }
+function compareIssuesByRoadmapOrder(a, b) {
+  const orderA = a.frontmatter.order;
+  const orderB = b.frontmatter.order;
+  if (orderA && orderB) {
+    if (orderA < orderB)
+      return -1;
+    if (orderA > orderB)
+      return 1;
+  }
+  if (orderA && !orderB)
+    return -1;
+  if (!orderA && orderB)
+    return 1;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function validateRoadmapDependencyOrder(issues) {
+  const openIssues = issues.filter((issue) => issue.frontmatter.status === "open").sort(compareIssuesByRoadmapOrder);
+  const positionById = new Map(openIssues.map((issue, index) => [issue.id, index]));
+  const violations = [];
+  for (const issue of openIssues) {
+    const issuePosition = positionById.get(issue.id);
+    if (issuePosition === undefined)
+      continue;
+    for (const dependency of getBlockingIssues(issue, issues)) {
+      const dependencyPosition = positionById.get(dependency.id);
+      if (dependencyPosition === undefined || dependencyPosition < issuePosition) {
+        continue;
+      }
+      violations.push(`#${issue.id} depends on #${dependency.id}`);
+    }
+  }
+  if (violations.length > 0) {
+    throw new Error(`Roadmap dependency order invalid: ${violations.join("; ")}. Issues must be placed after all open issues they depend on.`);
+  }
+}
 function getIssueIdFromFilename(filename) {
   const match = filename.match(/^(\d+)-/);
   return match ? match[1] : filename.replace(".md", "");
@@ -471,17 +506,7 @@ async function getAllIssues() {
       content: body
     });
   }
-  return issues.sort((a, b) => {
-    const orderA = a.frontmatter.order;
-    const orderB = b.frontmatter.order;
-    if (orderA && orderB)
-      return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-    if (orderA && !orderB)
-      return -1;
-    if (!orderA && orderB)
-      return 1;
-    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-  });
+  return issues.sort(compareIssuesByRoadmapOrder);
 }
 async function getOpenIssuesByOrder() {
   const allIssues = await getAllIssues();
@@ -569,8 +594,7 @@ async function createIssue(input) {
   const content = `${generateFrontmatter(frontmatter)}
 ${body}
 `;
-  await writeFile(join(getIssuesDir(), filename), content);
-  return {
+  const newIssue = {
     id: issueNumber,
     filename,
     frontmatter,
@@ -578,6 +602,9 @@ ${body}
 ${body}
 `
   };
+  validateRoadmapDependencyOrder([...existingIssues, newIssue]);
+  await writeFile(join(getIssuesDir(), filename), content);
+  return newIssue;
 }
 async function updateIssue(id, input) {
   const issue = await getIssue(id);
@@ -607,12 +634,16 @@ ${input.body}
 ` : issue.content;
   const content = `${generateFrontmatter(updatedFrontmatter)}
 ${updatedContent}`;
-  await writeFile(join(getIssuesDir(), issue.filename), content);
-  return {
+  const updatedIssue = {
     ...issue,
     frontmatter: updatedFrontmatter,
     content: updatedContent
   };
+  if (input.order !== undefined || input.depends_on !== undefined || input.status === "open") {
+    validateRoadmapDependencyOrder(allIssues.map((current) => current.id === issue.id ? updatedIssue : current));
+  }
+  await writeFile(join(getIssuesDir(), issue.filename), content);
+  return updatedIssue;
 }
 async function closeIssue(id) {
   return updateIssue(id, { status: "closed" });
@@ -2013,17 +2044,7 @@ function createSearchIndex(issues) {
 function sortIssues(issues, sortBy) {
   const sortOption = sortBy.toLowerCase();
   if (sortOption === "roadmap") {
-    issues.sort((a, b) => {
-      const orderA = a.frontmatter.order;
-      const orderB = b.frontmatter.order;
-      if (orderA && orderB)
-        return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-      if (orderA && !orderB)
-        return -1;
-      if (!orderA && orderB)
-        return 1;
-      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-    });
+    issues.sort(compareIssuesByRoadmapOrder);
   } else if (sortOption === "priority") {
     const priorityOrder = {
       high: 0,
@@ -2077,17 +2098,7 @@ function sortIssues(issues, sortBy) {
   } else if (sortOption === "id") {
     issues.sort((a, b) => b.id.localeCompare(a.id));
   } else {
-    issues.sort((a, b) => {
-      const orderA = a.frontmatter.order;
-      const orderB = b.frontmatter.order;
-      if (orderA && orderB)
-        return orderA < orderB ? -1 : orderA > orderB ? 1 : 0;
-      if (orderA && !orderB)
-        return -1;
-      if (!orderA && orderB)
-        return 1;
-      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-    });
+    issues.sort(compareIssuesByRoadmapOrder);
   }
 }
 function filterByQuery(issues, query) {
@@ -2181,336 +2192,215 @@ function markdown(lines) {
 `).trim()}
 `;
 }
-var compact = markdown([
-  "# issy agent instructions",
+var output = markdown([
+  "# Track issues with the issy CLI",
+  "",
+  "## Authoring Issues",
+  "",
+  "Issues describe *what* needs to be done and *why*. Keep them high-level unless the user provides specific details.",
+  "",
+  "### What to Include",
+  "",
+  "- **Problem/Overview**: What's wrong or what's needed (1-2 paragraphs)",
+  "- **Proposed Solution**: High-level approach",
+  '- **Acceptance Criteria**: Optional - what "done" looks like from user perspective',
+  "- **Verification**: Optional but encouraged - how to prove the issue is resolved (see below)",
+  "- **Future Considerations**: Optional - related ideas for later",
+  "- **References**: Optional - links to related docs, issues, or resources",
+  "",
+  "### Verification Guidance",
+  "",
+  "When possible, include verification steps or hints that tell the implementing agent *how to prove* the issue is resolved. This helps ensure work is actually verified before being marked complete.",
+  "",
+  "**Why include verification?** Agents should never claim work is done without evidence. If the issue itself describes how to verify, the implementing agent can follow those steps and provide concrete proof (command output, test results, screenshots, etc.).",
+  "",
+  "**Verification examples:**",
+  "- Commands to run and expected output (`curl`, CLI commands, `bun test`)",
+  "- UI flows to test (can use `agent-browser` skill if available for automation)",
+  "- Database queries to confirm state changes",
+  "- Specific behavior to observe or confirm",
+  "- Edge cases to check",
+  "",
+  "**Examples:**",
+  "",
+  "```markdown",
+  "## Verification",
+  'Run `bun test src/auth.test.ts` — all tests should pass, including the new "handles expired tokens" case.',
+  "```",
+  "",
+  "```markdown",
+  "## Verification",
+  "Perform the following using the agent-browser skill:",
+  "",
+  "1. Navigate to /settings and toggle dark mode",
+  "2. Refresh the page — preference should persist",
+  '3. Check localStorage contains `theme: "dark"`',
+  "```",
+  "",
+  "```markdown",
+  "## Verification",
+  'After deployment, `curl https://api.example.com/health` should return `{"status": "ok"}` with a 200 response.',
+  "```",
+  "",
+  "### Implementation Details",
+  "",
+  "**Only include implementation details if the user explicitly provides them.** Don't invent:",
+  "",
+  "- Task lists or phases",
+  "- Specific code changes or file paths",
+  "- Step-by-step instructions",
+  "- Technical breakdowns",
   "",
-  "Use issy for project issue tracking when the user asks to create, read, update, list, search, prioritize, close, reopen, or choose issue/task/bug work.",
+  "**Why?** The engineer working on the issue will plan their own implementation. Issues capture the user's intent, not execution plans generated by the agent.",
   "",
-  "## First action",
+  "**The rule:** Capture what the user says. If they provide implementation details, include them. If they don't, keep it high-level.",
   "",
-  "- If this request is about issue tracking, run `issy learn` before acting unless you already ran it in this session.",
-  "- Use the returned guidance as the source of truth for this installed issy version.",
-  "- For focused details, run `issy learn <topic>` instead of loading everything.",
+  "## Issue Sizing",
   "",
-  "## Essential workflow",
+  "An issue should be completable and verifiable in a single focused session — pick it up, implement it, prove it works, close it. If that's not realistic, split along verification boundaries so each child issue is independently closeable. Don't split when it adds overhead without adding clarity.",
   "",
-  "- List work: `issy list`, `issy list --all`, or `issy list --unblocked`.",
-  '- Search work: `issy search "query"` or `issy search "query" --all`.',
-  "- Read before changing: `issy read <id>`.",
-  "- Pick next work: `issy next`.",
-  '- Create work: `issy create --title "..." --type bug|improvement --priority high|medium|low <position>`.',
-  '- Create blocked work: `issy create --title "..." --depends-on 0001,0002 <position>`.',
-  "- Update work: `issy update <id> [options]`, including `--depends-on <ids>` to replace blockers.",
-  "- Close work: `issy close <id>` after the work is complete and verified.",
-  "- Reopen work: `issy reopen <id> <position>`.",
+  "## Roadmap Ordering",
   "",
-  "## Issue authoring",
+  "issy maintains a **roadmap** — a strict, intentional ordering of all open issues. Every open issue has a position in the roadmap, and the ordering is designed to be dependency-aware and chronological. No issue should be blocked by one that follows it.",
   "",
-  "- Capture what needs to be done and why. Keep implementation details out unless the user provides them.",
-  "- Good bodies usually include Problem/Overview, Proposed Solution, optional Acceptance Criteria, optional Verification, optional Future Considerations, and optional References.",
-  "- Include verification guidance when possible so the implementing agent can prove completion with commands, UI flows, queries, or expected behavior.",
-  "- Issues should be completable and verifiable in one focused session. Split only when a child issue is independently closeable.",
+  "### Rules",
   "",
-  "## Roadmap ordering",
+  "- When **creating** an issue: if there are already open issues, you **must** provide a position flag: `--before <id>`, `--after <id>`, `--first`, or `--last`.",
+  "- When **reopening** an issue: same rule — provide a position flag if there are other open issues.",
+  "- When **updating** an issue: optionally provide a position flag to reposition it in the roadmap.",
+  "- `issy next` returns the first open issue in roadmap order — the next unit of work.",
+  "- `issy list` sorts by roadmap order by default.",
   "",
-  "- Open issues form a strict roadmap order.",
-  "- When creating an issue and open issues already exist, include exactly one position flag: `--before <id>`, `--after <id>`, `--first`, or `--last`.",
-  "- When reopening an issue and other open issues exist, include exactly one position flag.",
-  "- Use dependency order: prerequisites first, dependent/user-facing work later. Use `--last` when placement is unclear.",
-  "- Use `depends_on` / `--depends-on` when an issue cannot start until specific blocking issues are closed.",
-  "- `issy list` shows a `Blk` column with open blocker counts; `-` means unblocked.",
-  "- `issy list --unblocked` shows only open issues with no open blockers.",
+  "### Choosing placement",
   "",
-  "## Closing",
+  "Think about logical dependency when choosing position:",
+  "- If issue B requires work from issue A to be done first, A must come before B.",
+  "- Place foundational/infrastructure work early, user-facing features later.",
+  "- Use `--first` for urgent work that should be tackled immediately.",
+  "- Use `--last` when in doubt — appends to the end of the roadmap.",
+  "- Use `--before <id>` or `--after <id>` for precise placement between existing issues.",
   "",
-  "- Before closing, verify the issue is actually resolved.",
-  "- If useful context was discovered, append a brief `## Resolution Notes` section before closing.",
-  "- If the repo tracks issues in git, consider committing `.issy/` changes after mutations.",
+  "## CLI Commands",
   "",
-  "## More focused context",
+  "Use the `issy` CLI. If not installed, install it globally using the project's package manager (e.g., `bun install issy --global`, `pnpm add issy --global`, `npm install issy --global`).",
   "",
-  "- `issy learn topics` lists available topics.",
-  "- `issy learn authoring` covers issue writing rules.",
-  "- `issy learn roadmap` covers placement rules.",
-  "- `issy learn commands` covers CLI command syntax.",
-  "- `issy learn hooks` covers hook files.",
-  "- `issy learn agents` prints AGENTS.md and skill bootstrap guidance.",
-  "- `issy learn --all` prints the full agent reference."
+  "```bash",
+  "# List issues (roadmap order by default)",
+  "issy list                    # Open issues only",
+  "issy list --all              # Include closed",
+  "issy list --priority high    # Filter: high, medium, low",
+  "issy list --scope small      # Filter: small, medium, large",
+  "issy list --type bug         # Filter: bug, improvement",
+  'issy list --search "keyword" # Fuzzy search',
+  "issy list --sort priority    # Sort: roadmap (default), priority, created, updated, id",
+  "",
+  "# Search issues (fuzzy search with typo tolerance)",
+  'issy search "dashboard"      # Search open issues',
+  'issy search "k8s" --all      # Include closed issues',
+  "",
+  "# Read issue",
+  "issy read <id>               # e.g., issy read 0001",
+  "",
+  "# Next issue (first open issue in roadmap order)",
+  "issy next",
+  "",
+  "# Create issue (position flag required when open issues exist)",
+  'issy create --title "Fix login bug" --type bug --priority high --after 0002',
+  'issy create --title "Add dark mode" --type improvement --last --labels "ui, frontend"',
+  'issy create --title "Urgent fix" --first',
+  'issy create --title "Fix crash" --body "## Problem\\n\\nApp crashes on startup." --last',
+  "",
+  "# Update issue (position flags to reposition in roadmap)",
+  "issy update <id> --priority low",
+  "issy update <id> --after 0003",
+  "issy update <id> --first",
+  'issy update <id> --labels "api, backend"',
+  'issy update <id> --body "## Problem\\n\\nUpdated description of the issue."',
+  "",
+  "# Close issue",
+  "issy close <id>",
+  "",
+  "# Reopen issue (position flag required when other open issues exist)",
+  "issy reopen <id> --last",
+  "issy reopen <id> --after 0004",
+  "```",
+  "",
+  "## Hooks",
+  "",
+  "issy supports optional hook files in `.issy/` that print context to stdout after successful operations. This is useful for injecting reminders into the agent's context — for example, prompting the agent to update documentation or run post-action checks.",
+  "",
+  "| Hook file | Triggered after |",
+  "|-----------|----------------|",
+  "| `on_create.md` | Creating an issue |",
+  "| `on_update.md` | Updating an issue |",
+  "| `on_close.md` | Closing an issue |",
+  "",
+  "## Project Structure",
+  "",
+  "Issues are stored in `.issy/issues/` as markdown files with YAML frontmatter. The directory structure:",
+  "",
+  "```",
+  ".issy/",
+  "  issues/",
+  "    0001-fix-login-redirect.md",
+  "    0002-add-dark-mode.md",
+  "  on_create.md   # Optional: printed after successful create",
+  "  on_update.md   # Optional: printed after successful update",
+  "  on_close.md    # Optional: printed after successful close",
+  "```",
+  "",
+  "## Closing Issues with Learnings",
+  "",
+  "When closing an issue, append a `## Resolution Notes` section if anything useful was discovered during implementation:",
+  "",
+  "- Alternative approaches considered or rejected",
+  "- Unexpected gotchas or edge cases found",
+  "- Decisions made that differ from the original plan",
+  "- Useful context for future reference",
+  "",
+  "Keep it brief—just capture what someone revisiting this issue would want to know.",
+  "",
+  "## Issue Properties",
+  "",
+  "| Property | Required | Values |",
+  "|----------|----------|--------|",
+  "| title | Yes | string |",
+  "| body | No | markdown content (the issue body after frontmatter) |",
+  "| priority | Yes | `high`, `medium`, `low` |",
+  "| scope | No | `small`, `medium`, `large` |",
+  "| type | Yes | `bug`, `improvement` |",
+  "| labels | No | comma-separated strings |",
+  "| status | Yes | `open`, `closed` |",
+  "| order | Auto | fractional index key (managed by issy) |",
+  "",
+  "## After Mutations",
+  "",
+  "If your workflow tracks issues in git, consider committing updates so the tracker stays in sync."
 ]);
-var topics = [
-  {
-    name: "authoring",
-    description: "Issue writing, sizing, verification, and resolution notes.",
-    content: markdown([
-      "# issy issue authoring",
-      "",
-      "Issues describe what needs to be done and why. Keep them high-level unless the user provides specific implementation details.",
-      "",
-      "## What to include",
-      "",
-      "- Problem/Overview: what is wrong or needed, usually one or two paragraphs.",
-      "- Proposed Solution: high-level approach.",
-      "- Acceptance Criteria: optional, from the user perspective.",
-      "- Verification: optional but encouraged; explain how to prove the issue is resolved.",
-      "- Future Considerations: optional related ideas for later.",
-      "- References: optional links to related docs, issues, PRs, or resources.",
-      "",
-      "## Verification guidance",
-      "",
-      "When possible, include verification steps or hints. Agents should not claim work is done without evidence.",
-      "",
-      "Useful verification examples:",
-      "",
-      "- Commands to run and expected output, such as `bun test`, `npm test`, `curl`, or a project CLI.",
-      "- UI flows to test, including browser automation when available.",
-      "- Database queries or API calls that confirm state changes.",
-      "- Specific behavior to observe.",
-      "- Edge cases to check.",
-      "",
-      "## Implementation details rule",
-      "",
-      "Only include implementation details if the user explicitly provides them. Do not invent task lists, phases, file paths, code changes, or step-by-step technical breakdowns.",
-      "",
-      "The issue should capture the user intent. The engineer or agent implementing it can plan the implementation later.",
-      "",
-      "## Sizing",
-      "",
-      "An issue should be completable and verifiable in a single focused session. Split large work along verification boundaries so each child issue can be independently completed and closed. Do not split when it adds overhead without clarity.",
-      "",
-      "## Closing with learnings",
-      "",
-      "When closing an issue, append a brief `## Resolution Notes` section if useful context was discovered during implementation:",
-      "",
-      "- Alternative approaches considered or rejected.",
-      "- Unexpected gotchas or edge cases.",
-      "- Decisions that differ from the original plan.",
-      "- Useful context for future maintainers."
-    ])
-  },
-  {
-    name: "roadmap",
-    description: "Strict roadmap ordering and position flag rules.",
-    aliases: ["ordering"],
-    content: markdown([
-      "# issy roadmap ordering",
-      "",
-      "issy maintains a strict roadmap order for all open issues. `issy next` returns the first open issue in that order. `issy list` sorts by roadmap order by default.",
-      "",
-      "## Required position flags",
-      "",
-      "- Creating an issue: if open issues already exist, provide exactly one of `--before <id>`, `--after <id>`, `--first`, or `--last`.",
-      "- Reopening an issue: if other open issues exist, provide exactly one position flag.",
-      "- Updating an issue: position flags are optional and reposition the issue when provided.",
-      "- Never provide more than one position flag.",
-      "",
-      "## Explicit blockers",
-      "",
-      "- Use `depends_on` when an issue cannot start until specific blocking issues are closed.",
-      '- Create blocked work with `issy create --title "..." --depends-on 0001,0002 --last`.',
-      "- Replace blockers with `issy update <id> --depends-on 0001,0003`.",
-      '- Clear blockers with `issy update <id> --depends-on ""`.',
-      "- Missing or malformed dependency IDs are ignored.",
-      "- `issy list` shows a compact `Blk` column. `-` means unblocked; otherwise the value is the number of open blockers.",
-      "- `issy list --unblocked` shows only open issues with no open blockers.",
-      "",
-      "## Choosing placement",
-      "",
-      "- Place prerequisites before dependent issues.",
-      "- Place foundational or infrastructure work before user-facing work that depends on it.",
-      "- Use `--first` for urgent work that should be tackled immediately.",
-      "- Use `--last` when placement is unclear.",
-      "- Use `--before <id>` or `--after <id>` for precise placement.",
-      "",
-      "## Useful commands",
-      "",
-      "- `issy list` shows open issues in roadmap order.",
-      "- `issy list --unblocked` shows open issues with no open blockers.",
-      "- `issy next` shows the first open issue in roadmap order.",
-      '- `issy create --title "..." --last` appends a new issue.',
-      '- `issy create --title "..." --depends-on 0001,0002 --last` creates an issue blocked by other issues.',
-      "- `issy update <id> --before <other-id>` repositions an issue.",
-      "- `issy update <id> --depends-on 0001,0003` replaces blockers.",
-      "- `issy reopen <id> --after <other-id>` reopens and places a closed issue."
-    ])
-  },
-  {
-    name: "commands",
-    description: "CLI command syntax for issue operations.",
-    aliases: ["cli", "reference"],
-    content: markdown([
-      "# issy CLI command reference",
-      "",
-      "Use the `issy` CLI. If it is not installed, install it with the project package manager, for example `npm install issy --global`, `pnpm add issy --global`, or `bun install issy --global`.",
-      "",
-      "## List and search",
-      "",
-      "- `issy list`: list open issues in roadmap order.",
-      "- `issy list --all`: include closed issues.",
-      "- `issy list --unblocked`: list open issues with no open blockers.",
-      "- `issy list --priority high|medium|low`: filter by priority.",
-      "- `issy list --scope small|medium|large`: filter by scope.",
-      "- `issy list --type bug|improvement`: filter by type.",
-      '- `issy list --search "keyword"`: fuzzy search while listing.',
-      "- `issy list --sort roadmap|priority|created|updated|id`: choose sort order.",
-      '- `issy search "query"`: fuzzy search open issues.',
-      '- `issy search "query" --all`: include closed issues.',
-      "",
-      "## Read and choose work",
-      "",
-      "- `issy read <id>`: read a full issue.",
-      "- `issy next`: show the next open issue in roadmap order.",
-      "",
-      "## Create",
-      "",
-      '- `issy create --title "Fix login bug" --type bug --priority high --after 0002`.',
-      '- `issy create --title "Add dark mode" --type improvement --last --labels "ui, frontend"`.',
-      '- `issy create --title "Add export" --depends-on 0001,0002 --last`.',
-      '- `issy create --title "Urgent fix" --first`.',
-      '- `issy create --title "Fix crash" --body "## Problem\\n\\nApp crashes on startup." --last`.',
-      "",
-      "Create options: `--title`, `--body`, `--priority`, `--scope`, `--type`, `--labels`, `--depends-on`, `--before`, `--after`, `--first`, `--last`.",
-      "",
-      "## Update",
-      "",
-      "- `issy update <id> --priority low`.",
-      "- `issy update <id> --after 0003`.",
-      "- `issy update <id> --first`.",
-      '- `issy update <id> --labels "api, backend"`.',
-      "- `issy update <id> --depends-on 0001,0003`.",
-      '- `issy update <id> --body "## Problem\\n\\nUpdated description."`.',
-      "",
-      "Update options: `--title`, `--body`, `--priority`, `--scope`, `--type`, `--labels`, `--depends-on`, `--before`, `--after`, `--first`, `--last`.",
-      "",
-      "## Close and reopen",
-      "",
-      "- `issy close <id>`.",
-      "- `issy reopen <id> --last`.",
-      "- `issy reopen <id> --after 0004`.",
-      "",
-      "When reopening and other open issues exist, include exactly one position flag."
-    ])
-  },
-  {
-    name: "hooks",
-    description: "Optional `.issy/` hook files that print agent context after mutations.",
-    content: markdown([
-      "# issy hooks",
-      "",
-      "issy supports optional hook files in `.issy/`. After a successful mutation, issy prints the matching hook file contents to stdout so agents can see project-specific reminders.",
-      "",
-      "## Hook files",
-      "",
-      "- `.issy/on_create.md`: printed after `issy create`.",
-      "- `.issy/on_update.md`: printed after `issy update`.",
-      "- `.issy/on_close.md`: printed after `issy close`.",
-      "",
-      "## Good hook uses",
-      "",
-      "- Remind agents to update docs for user-facing behavior changes.",
-      "- Remind agents to run project-specific checks.",
-      "- Add team conventions for issue mutations.",
-      "- Surface release or changelog requirements.",
-      "",
-      "Hook content should be concise because it is injected directly into command output."
-    ])
-  },
-  {
-    name: "agents",
-    description: "Bootstrap instructions for AGENTS.md and shell skills.",
-    aliases: ["skill", "bootstrap"],
-    content: markdown([
-      "# issy agent bootstrap",
-      "",
-      "`issy learn` is the canonical AI-agent reference for the installed issy version. Skills and AGENTS.md files should bootstrap agents into this command instead of duplicating the full reference.",
-      "",
-      "## Relevance rule",
-      "",
-      "Use issy when creating, reading, updating, listing, searching, prioritizing, closing, reopening, or choosing project issues, tasks, bugs, improvements, or roadmap work.",
-      "",
-      "## AGENTS.md snippet",
-      "",
-      "Add this to AGENTS.md:",
-      "",
-      "```md",
-      "When the task involves creating, reading, updating, listing, searching, prioritizing, closing, reopening, or choosing project issues, tasks, bugs, improvements, or roadmap work, run `issy learn` first and follow its guidance.",
-      "```",
-      "",
-      "## Skill bootstrap behavior",
-      "",
-      "A compatible skill should only define the relevance rule and instruct the agent to run `issy learn` when relevant. The operational reference belongs in the CLI output."
-    ])
-  }
-];
-var aliases = new Map;
-for (const topic of topics) {
-  aliases.set(topic.name, topic);
-  for (const alias of topic.aliases ?? []) {
-    aliases.set(alias, topic);
-  }
-}
-function topicList() {
-  return markdown([
-    "# issy learn topics",
-    "",
-    "Run `issy learn <topic>` for focused agent context.",
-    "",
-    ...topics.map((topic) => `- \`${topic.name}\`: ${topic.description}`),
-    "",
-    "Other options:",
-    "",
-    "- `issy learn`: compact default instructions.",
-    "- `issy learn --all`: full reference.",
-    "- `issy learn --help`: command usage."
-  ]);
-}
 function usage() {
   return markdown([
-    "Usage: issy learn [topic] [options]",
+    "Usage: issy learn [options]",
     "",
     "Print AI-agent instructions for using issy.",
     "",
-    "Topics:",
-    ...topics.map((topic) => `  ${topic.name.padEnd(10)} ${topic.description}`),
-    "",
     "Options:",
-    "  --all       Print the compact guidance and all topics",
-    "  --list      List available topics",
     "  --help, -h  Show this help",
     "",
     "Examples:",
-    "  issy learn",
-    "  issy learn roadmap",
-    "  issy learn commands",
-    "  issy learn --all"
+    "  issy learn"
   ]);
 }
 function getLearnOutput(args = []) {
   if (args.includes("--help") || args.includes("-h")) {
     return usage();
   }
-  if (args.includes("--list")) {
-    return topicList();
-  }
-  if (args.includes("--all")) {
-    return [compact, ...topics.map((topic2) => topic2.content)].join(`
----
-
-`);
-  }
-  const topicArg = args.find((arg) => !arg.startsWith("-"));
-  if (!topicArg) {
-    return compact;
-  }
-  if (topicArg === "topics" || topicArg === "list") {
-    return topicList();
-  }
-  const topic = aliases.get(topicArg);
-  if (!topic) {
-    throw new Error(`Unknown learn topic: ${topicArg}
+  const unknownArg = args.find((arg) => arg.trim() !== "");
+  if (unknownArg) {
+    throw new Error(`Unknown learn argument: ${unknownArg}
 
-${topicList()}`);
+${usage()}`);
   }
-  return topic.content;
+  return output;
 }
 
 // src/main.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "issy",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "AI-native issue tracking. Markdown files in .issues/, managed by your coding assistant.",
   "type": "module",
   "license": "MIT",
@@ -35,8 +35,8 @@
     "lint": "biome check src bin"
   },
   "dependencies": {
-    "@miketromba/issy-app": "^0.10.1",
-    "@miketromba/issy-core": "^0.10.1",
+    "@miketromba/issy-app": "^0.11.1",
+    "@miketromba/issy-core": "^0.11.1",
     "update-notifier": "^7.3.1"
   }
 }