issy 0.9.0 → 0.10.0

package/README.md

@@ -18,7 +18,7 @@
 
 ## How It Works
 
-issy gives AI coding assistants a skill for managing issues. Just talk naturally:
+issy gives AI coding assistants versioned instructions for managing issues. Add a small AGENTS.md rule or install the bootstrap skill, then just talk naturally:
 
 > "Create a bug for the login redirect issue, high priority"
 
@@ -28,19 +28,31 @@ issy gives AI coding assistants a skill for managing issues. Just talk naturally
 
 The assistant creates, searches, updates, and closes issues for you. Issues are stored as markdown files in `.issy/issues/` — readable, diffable, and committed with your code.
 
-## Install the Skill
+## Teach Your AI Assistant
+
+```bash
+issy learn
+```
+
+`issy learn` prints the canonical AI-agent reference for your installed issy version. To make agents run it automatically, 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.
+```
+
+You can also install the lightweight bootstrap skill:
 
 ```bash
 issy skill install
 ```
 
-Or, if you haven't installed `issy` yet:
+Or, without running the issy wrapper:
 
 ```bash
 npx skills add miketromba/issy
 ```
 
-That's it. Your AI assistant can now manage issues in any repo.
+The skill contains only the relevance rule and tells compatible assistants to run `issy learn`, keeping the real agent guidance in one versioned place. The `issy` CLI still needs to be available when the assistant runs `issy learn`.
 
 ## Why Markdown?
 
@@ -78,9 +90,9 @@ Once installed globally, you can run commands from your terminal:
 ```bash
 issy                          # Start the web UI
 issy list                     # List open issues (roadmap order)
-issy list --unblocked         # List open issues with no open blockers
 issy next                     # Show next issue to work on
 issy create --title "Bug"     # Create an issue
+issy learn                    # Print AI-agent instructions
 ```
 
 ### Repository installation
@@ -125,19 +137,18 @@ Opens a local read-only UI at `http://localhost:1554` for browsing issues.
 issy init                     # Create .issy/issues/ directory
 issy init --seed              # Create with a welcome issue
 issy list                     # List open issues (roadmap order)
-issy list --unblocked         # List open issues with no open blockers
 issy next                     # Show next issue to work on
 issy search "auth"            # Fuzzy search
 issy read 0001                # View issue
 issy create --title "Bug" --after 0002    # Create issue after #0002
-issy create --title "Feature" --depends-on 0012,0035 --last  # Blocked by issues
 issy create --title "Bug" --body "Details here" --last  # Create with body content
 issy update 0001 --before 0003            # Reposition in roadmap
-issy update 0001 --depends-on 0012,0035   # Replace blockers
 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 skill install            # Install the AI skill
+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
 ```
@@ -164,14 +175,6 @@ issy list --sort priority     # Sort by priority instead
 issy list --sort created      # Sort by creation date
 ```
 
-The `Blk` column in `issy list` shows the count of currently open blockers. `-` means the issue is unblocked. Use `issy list --unblocked` to show only open issues that have no open blockers. Dependency IDs that do not match an existing issue are ignored.
-
-Issues can declare blockers with `depends_on`:
-
-```yaml
-depends_on: 0012, 0035
-```
-
 ### 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.
@@ -223,7 +226,6 @@ scope: medium
 type: bug
 status: open
 order: a0
-depends_on: 0012, 0035
 created: 2025-01-15T10:30:00
 ---
 
@@ -241,7 +243,6 @@ session isn't established, causing a redirect loop.
 | `status` | `open`, `closed` |
 | `labels` | comma-separated (optional) |
 | `order` | fractional index key (managed by issy) |
-| `depends_on` | comma-separated blocking issue IDs (optional) |
 
 ## Configuration
 

package/dist/cli.js

@@ -355,9 +355,6 @@ function generateFrontmatter(data) {
   if (data.order) {
     lines.push(`order: ${data.order}`);
   }
-  if (data.depends_on) {
-    lines.push(`depends_on: ${data.depends_on}`);
-  }
   lines.push(`created: ${data.created}`);
   if (data.updated) {
     lines.push(`updated: ${data.updated}`);
@@ -366,44 +363,6 @@ function generateFrontmatter(data) {
   return lines.join(`
 `);
 }
-function parseDependencyIds(dependsOn) {
-  if (!dependsOn)
-    return [];
-  const seen = new Set;
-  const ids = [];
-  for (const token of dependsOn.split(/[,\s]+/)) {
-    const value = token.trim().replace(/^['"]+|['"]+$/g, "").replace(/^#/, "");
-    if (!/^\d+$/.test(value))
-      continue;
-    const id = value.padStart(4, "0");
-    if (seen.has(id))
-      continue;
-    seen.add(id);
-    ids.push(id);
-  }
-  return ids;
-}
-function filterExistingDependencyIds(dependsOn, issues, excludeId) {
-  const existingIds = new Set(issues.map((issue) => issue.id));
-  const excludedId = excludeId?.padStart(4, "0");
-  return parseDependencyIds(dependsOn).filter((id) => existingIds.has(id) && id !== excludedId);
-}
-function formatExistingDependencyIds(dependsOn, issues, excludeId) {
-  return filterExistingDependencyIds(dependsOn, issues, excludeId).join(", ");
-}
-function getDependencyIssues(issue, issues) {
-  const dependencyIds = filterExistingDependencyIds(issue.frontmatter.depends_on, issues, issue.id);
-  if (dependencyIds.length === 0)
-    return [];
-  const issueById = new Map(issues.map((i) => [i.id, i]));
-  return dependencyIds.map((id) => issueById.get(id)).filter((dependency) => Boolean(dependency));
-}
-function getBlockingIssues(issue, issues) {
-  return getDependencyIssues(issue, issues).filter((dependency) => dependency.frontmatter.status === "open");
-}
-function isIssueUnblocked(issue, issues) {
-  return issue.frontmatter.status === "open" && getBlockingIssues(issue, issues).length === 0;
-}
 function getIssueIdFromFilename(filename) {
   const match = filename.match(/^(\d+)-/);
   return match ? match[1] : filename.replace(".md", "");
@@ -537,8 +496,6 @@ async function createIssue(input) {
   const issueNumber = await getNextIssueNumber();
   const slug = createSlug(input.title);
   const filename = `${issueNumber}-${slug}.md`;
-  const existingIssues = await getAllIssues();
-  const dependsOn = formatExistingDependencyIds(input.depends_on, existingIssues, issueNumber);
   const frontmatter = {
     title: input.title,
     priority,
@@ -547,7 +504,6 @@ async function createIssue(input) {
     labels: input.labels || undefined,
     status: "open",
     order: input.order || undefined,
-    depends_on: dependsOn || undefined,
     created: formatDate()
   };
   const body = input.body ?? `
@@ -573,8 +529,6 @@ async function updateIssue(id, input) {
   if (!issue) {
     throw new Error(`Issue not found: ${id}`);
   }
-  const allIssues = await getAllIssues();
-  const dependsOn = input.depends_on !== undefined ? formatExistingDependencyIds(input.depends_on, allIssues, issue.id) : undefined;
   const updatedFrontmatter = {
     ...issue.frontmatter,
     ...input.title && { title: input.title },
@@ -586,9 +540,6 @@ async function updateIssue(id, input) {
     },
     ...input.status && { status: input.status },
     ...input.order && { order: input.order },
-    ...input.depends_on !== undefined && {
-      depends_on: dependsOn || undefined
-    },
     updated: formatDate()
   };
   const updatedContent = input.body !== undefined ? `
@@ -2088,14 +2039,6 @@ function filterByQuery(issues, query) {
         if (issue.frontmatter.status !== statusValue) {
           return false;
         }
-      } else if (statusValue === "unblocked") {
-        if (!isIssueUnblocked(issue, issues)) {
-          return false;
-        }
-      } else if (statusValue === "blocked") {
-        if (issue.frontmatter.status !== "open" || isIssueUnblocked(issue, issues)) {
-          return false;
-        }
       }
     }
     if (parsed.qualifiers.priority) {
@@ -2183,23 +2126,7 @@ function typeSymbol(type) {
 }
 function formatIssueRow(issue) {
   const status = issue.frontmatter.status === "open" ? "OPEN  " : "CLOSED";
-  const blocked = issue.blockers > 0 ? String(issue.blockers) : "-";
-  return `  ${issue.id}  ${prioritySymbol(issue.frontmatter.priority)}   ${typeSymbol(issue.frontmatter.type)}    ${status}  ${blocked.padEnd(3)}  ${issue.frontmatter.title}`;
-}
-function printDependsOn(issue, issues) {
-  const dependencyIssues = getDependencyIssues(issue, issues);
-  if (dependencyIssues.length === 0)
-    return;
-  console.log(`  Depends on:  ${dependencyIssues.map((i) => `#${i.id}`).join(", ")}`);
-}
-function getDependsOnArg(values) {
-  const value = values["depends-on"];
-  return typeof value === "string" ? value : undefined;
-}
-async function resolveDependsOn(value, excludeId) {
-  if (value === undefined)
-    return;
-  return formatExistingDependencyIds(value, await getAllIssues(), excludeId);
+  return `  ${issue.id}  ${prioritySymbol(issue.frontmatter.priority)}   ${typeSymbol(issue.frontmatter.type)}    ${status}  ${issue.frontmatter.title}`;
 }
 async function resolvePosition(opts) {
   const openIssues = await getOpenIssuesByOrder();
@@ -2231,7 +2158,7 @@ function hasHelpFlag(commandArgs) {
 async function listIssues(options) {
   const allIssues = await getAllIssues();
   const queryParts = [];
-  if (!options.all && !options.unblocked)
+  if (!options.all)
     queryParts.push("is:open");
   if (options.priority)
     queryParts.push(`priority:${options.priority}`);
@@ -2243,23 +2170,17 @@ async function listIssues(options) {
     queryParts.push(`sort:${options.sort}`);
   if (options.search)
     queryParts.push(options.search);
-  const query = queryParts.join(" ");
-  let issues = query ? filterByQuery(allIssues, query) : allIssues;
-  if (options.unblocked) {
-    issues = issues.filter((issue) => isIssueUnblocked(issue, allIssues));
-  }
+  const query = queryParts.join(" ") || "is:open";
+  const issues = filterByQuery(allIssues, query);
   if (issues.length === 0) {
     console.log("No issues found.");
     return;
   }
   console.log(`
-  ID    Pri  Type  Status  Blk  Title`);
+  ID    Pri  Type  Status   Title`);
   console.log(`  ${"-".repeat(100)}`);
   for (const issue of issues) {
-    console.log(formatIssueRow({
-      ...issue,
-      blockers: getBlockingIssues(issue, allIssues).length
-    }));
+    console.log(formatIssueRow(issue));
   }
   console.log(`
   Total: ${issues.length} issue(s)
@@ -2267,7 +2188,6 @@ async function listIssues(options) {
 }
 async function readIssue(id) {
   const issue = await getIssue(id);
-  const allIssues = await getAllIssues();
   if (!issue) {
     console.error(`Issue not found: ${id}`);
     process.exit(1);
@@ -2286,7 +2206,6 @@ ${"=".repeat(70)}`);
   if (issue.frontmatter.labels) {
     console.log(`  Labels:      ${issue.frontmatter.labels}`);
   }
-  printDependsOn(issue, allIssues);
   if (issue.frontmatter.order) {
     console.log(`  Order:       ${issue.frontmatter.order}`);
   }
@@ -2309,13 +2228,10 @@ async function searchIssuesCommand(query, options) {
   console.log(`
   Search results for "${query}":`);
   console.log(`
-  ID    Pri  Type  Status  Blk  Title`);
+  ID    Pri  Type  Status   Title`);
   console.log(`  ${"-".repeat(100)}`);
   for (const issue of issues) {
-    console.log(formatIssueRow({
-      ...issue,
-      blockers: getBlockingIssues(issue, allIssues).length
-    }));
+    console.log(formatIssueRow(issue));
   }
   console.log(`
   Found: ${issues.length} issue(s)
@@ -2341,7 +2257,6 @@ async function createIssueCommand(options) {
       scope: options.scope,
       type: options.type,
       labels: options.labels,
-      depends_on: await resolveDependsOn(options.dependsOn) || undefined,
       order
     };
     const issue = await createIssue(input);
@@ -2378,9 +2293,6 @@ async function updateIssueCommand(id, options) {
       scope: options.scope,
       type: options.type,
       labels: options.labels,
-      ...options.dependsOn !== undefined && {
-        depends_on: await resolveDependsOn(options.dependsOn, id) || ""
-      },
       order
     });
     console.log(`Updated issue: ${issue.filename}`);
@@ -2429,7 +2341,6 @@ async function reopenIssueCommand(id, options) {
 }
 async function nextIssueCommand() {
   const issue = await getNextIssue();
-  const allIssues = await getAllIssues();
   if (!issue) {
     console.log("No open issues.");
     return;
@@ -2448,7 +2359,6 @@ ${"=".repeat(70)}`);
   if (issue.frontmatter.labels) {
     console.log(`  Labels:      ${issue.frontmatter.labels}`);
   }
-  printDependsOn(issue, allIssues);
   if (issue.frontmatter.order) {
     console.log(`  Order:       ${issue.frontmatter.order}`);
   }
@@ -2476,7 +2386,6 @@ Options:
 Commands:
   list                    List all open issues (roadmap order)
     --all, -a             Include closed issues
-    --unblocked           Only show open issues with no open blockers
     --priority, -p <p>    Filter by priority (high, medium, low)
     --scope <s>           Filter by scope (small, medium, large)
     --type, -t <t>        Filter by type (bug, improvement)
@@ -2490,6 +2399,10 @@ 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
+
   create                  Create a new issue
     --title, -t <t>       Issue title
     --body, -b <b>        Markdown body content
@@ -2497,7 +2410,6 @@ Commands:
     --scope <s>           Scope (small, medium, large)
     --type <t>            Type (bug, improvement)
     --labels, -l <l>      Comma-separated labels
-    --depends-on <ids>    Comma-separated blocking issue IDs
     --before <id>         Insert before this issue in roadmap
     --after <id>          Insert after this issue in roadmap
     --first               Insert at the beginning of the roadmap
@@ -2510,7 +2422,6 @@ Commands:
     --scope <s>           New scope
     --type <t>            New type
     --labels, -l <l>      New labels
-    --depends-on <ids>    Replace blocking issue IDs (empty clears)
     --before <id>         Move before this issue in roadmap
     --after <id>          Move after this issue in roadmap
     --first               Move to the beginning of the roadmap
@@ -2524,13 +2435,14 @@ Commands:
     --first               Insert at the beginning of the roadmap
     --last                Insert at the end of the roadmap
 
-  skill install           Install the issy skill for your AI coding assistant
+  skill install           Install the issy bootstrap skill
 
 Examples:
   issy list
-  issy list --unblocked
   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
@@ -2550,7 +2462,6 @@ List all open issues in roadmap order.
 
 Options:
   --all, -a             Include closed issues
-  --unblocked           Only show open issues with no open blockers
   --priority, -p <p>    Filter by priority (high, medium, low)
   --scope <s>           Filter by scope (small, medium, large)
   --type, -t <t>        Filter by type (bug, improvement)
@@ -2563,7 +2474,6 @@ Options:
         args: args.slice(1),
         options: {
           all: { type: "boolean", short: "a" },
-          unblocked: { type: "boolean" },
           priority: { type: "string", short: "p" },
           scope: { type: "string" },
           type: { type: "string", short: "t" },
@@ -2641,7 +2551,6 @@ Options:
   --scope <s>           Scope: small, medium, large
   --type <t>            Type: bug, improvement (default: improvement)
   --labels, -l <l>      Comma-separated labels
-  --depends-on <ids>    Comma-separated blocking issue IDs
   --before <id>         Insert before this issue in roadmap
   --after <id>          Insert after this issue in roadmap
   --first               Insert at the beginning of the roadmap
@@ -2649,7 +2558,6 @@ Options:
 
 Examples:
   issy create --title "Fix login bug" --type bug --priority high --after 0002
-  issy create --title "Add export" --depends-on 0001,0002 --last
   issy create --title "Add dark mode" --last
 `);
         return;
@@ -2663,7 +2571,6 @@ Examples:
           scope: { type: "string" },
           type: { type: "string" },
           labels: { type: "string", short: "l" },
-          "depends-on": { type: "string" },
           before: { type: "string" },
           after: { type: "string" },
           first: { type: "boolean" },
@@ -2671,10 +2578,7 @@ Examples:
         },
         allowPositionals: true
       });
-      await createIssueCommand({
-        ...values,
-        dependsOn: getDependsOnArg(values)
-      });
+      await createIssueCommand(values);
       break;
     }
     case "update": {
@@ -2690,7 +2594,6 @@ Options:
   --scope <s>           New scope: small, medium, large
   --type <t>            New type: bug, improvement
   --labels, -l <l>      New labels (comma-separated)
-  --depends-on <ids>    Replace blocking issue IDs (empty clears)
   --before <id>         Move before this issue in roadmap
   --after <id>          Move after this issue in roadmap
   --first               Move to the beginning of the roadmap
@@ -2698,7 +2601,6 @@ Options:
 
 Examples:
   issy update 0001 --priority low --after 0003
-  issy update 0002 --depends-on 0001,0003
   issy update 0002 --title "Renamed issue" --first
 `);
         return;
@@ -2717,7 +2619,6 @@ Examples:
           scope: { type: "string" },
           type: { type: "string" },
           labels: { type: "string", short: "l" },
-          "depends-on": { type: "string" },
           before: { type: "string" },
           after: { type: "string" },
           first: { type: "boolean" },
@@ -2725,10 +2626,7 @@ Examples:
         },
         allowPositionals: true
       });
-      await updateIssueCommand(id, {
-        ...values,
-        dependsOn: getDependsOnArg(values)
-      });
+      await updateIssueCommand(id, values);
       break;
     }
     case "close": {

package/dist/main.js

@@ -366,9 +366,6 @@ function generateFrontmatter(data) {
   if (data.order) {
     lines.push(`order: ${data.order}`);
   }
-  if (data.depends_on) {
-    lines.push(`depends_on: ${data.depends_on}`);
-  }
   lines.push(`created: ${data.created}`);
   if (data.updated) {
     lines.push(`updated: ${data.updated}`);
@@ -377,44 +374,6 @@ function generateFrontmatter(data) {
   return lines.join(`
 `);
 }
-function parseDependencyIds(dependsOn) {
-  if (!dependsOn)
-    return [];
-  const seen = new Set;
-  const ids = [];
-  for (const token of dependsOn.split(/[,\s]+/)) {
-    const value = token.trim().replace(/^['"]+|['"]+$/g, "").replace(/^#/, "");
-    if (!/^\d+$/.test(value))
-      continue;
-    const id = value.padStart(4, "0");
-    if (seen.has(id))
-      continue;
-    seen.add(id);
-    ids.push(id);
-  }
-  return ids;
-}
-function filterExistingDependencyIds(dependsOn, issues, excludeId) {
-  const existingIds = new Set(issues.map((issue) => issue.id));
-  const excludedId = excludeId?.padStart(4, "0");
-  return parseDependencyIds(dependsOn).filter((id) => existingIds.has(id) && id !== excludedId);
-}
-function formatExistingDependencyIds(dependsOn, issues, excludeId) {
-  return filterExistingDependencyIds(dependsOn, issues, excludeId).join(", ");
-}
-function getDependencyIssues(issue, issues) {
-  const dependencyIds = filterExistingDependencyIds(issue.frontmatter.depends_on, issues, issue.id);
-  if (dependencyIds.length === 0)
-    return [];
-  const issueById = new Map(issues.map((i) => [i.id, i]));
-  return dependencyIds.map((id) => issueById.get(id)).filter((dependency) => Boolean(dependency));
-}
-function getBlockingIssues(issue, issues) {
-  return getDependencyIssues(issue, issues).filter((dependency) => dependency.frontmatter.status === "open");
-}
-function isIssueUnblocked(issue, issues) {
-  return issue.frontmatter.status === "open" && getBlockingIssues(issue, issues).length === 0;
-}
 function getIssueIdFromFilename(filename) {
   const match = filename.match(/^(\d+)-/);
   return match ? match[1] : filename.replace(".md", "");
@@ -548,8 +507,6 @@ async function createIssue(input) {
   const issueNumber = await getNextIssueNumber();
   const slug = createSlug(input.title);
   const filename = `${issueNumber}-${slug}.md`;
-  const existingIssues = await getAllIssues();
-  const dependsOn = formatExistingDependencyIds(input.depends_on, existingIssues, issueNumber);
   const frontmatter = {
     title: input.title,
     priority,
@@ -558,7 +515,6 @@ async function createIssue(input) {
     labels: input.labels || undefined,
     status: "open",
     order: input.order || undefined,
-    depends_on: dependsOn || undefined,
     created: formatDate()
   };
   const body = input.body ?? `
@@ -584,8 +540,6 @@ async function updateIssue(id, input) {
   if (!issue) {
     throw new Error(`Issue not found: ${id}`);
   }
-  const allIssues = await getAllIssues();
-  const dependsOn = input.depends_on !== undefined ? formatExistingDependencyIds(input.depends_on, allIssues, issue.id) : undefined;
   const updatedFrontmatter = {
     ...issue.frontmatter,
     ...input.title && { title: input.title },
@@ -597,9 +551,6 @@ async function updateIssue(id, input) {
     },
     ...input.status && { status: input.status },
     ...input.order && { order: input.order },
-    ...input.depends_on !== undefined && {
-      depends_on: dependsOn || undefined
-    },
     updated: formatDate()
   };
   const updatedContent = input.body !== undefined ? `
@@ -2099,14 +2050,6 @@ function filterByQuery(issues, query) {
         if (issue.frontmatter.status !== statusValue) {
           return false;
         }
-      } else if (statusValue === "unblocked") {
-        if (!isIssueUnblocked(issue, issues)) {
-          return false;
-        }
-      } else if (statusValue === "blocked") {
-        if (issue.frontmatter.status !== "open" || isIssueUnblocked(issue, issues)) {
-          return false;
-        }
       }
     }
     if (parsed.qualifiers.priority) {
@@ -2175,12 +2118,339 @@ function filterByQuery(issues, query) {
   }
   return result;
 }
+// src/learn.ts
+function markdown(lines) {
+  return `${lines.join(`
+`).trim()}
+`;
+}
+var compact = markdown([
+  "# issy agent instructions",
+  "",
+  "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.",
+  "",
+  "## First action",
+  "",
+  "- 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.",
+  "",
+  "## Essential workflow",
+  "",
+  "- List work: `issy list` or `issy list --all`.",
+  '- 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>`.',
+  "- Update work: `issy update <id> [options]`.",
+  "- Close work: `issy close <id>` after the work is complete and verified.",
+  "- Reopen work: `issy reopen <id> <position>`.",
+  "",
+  "## Issue authoring",
+  "",
+  "- 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.",
+  "",
+  "## Roadmap ordering",
+  "",
+  "- 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.",
+  "",
+  "## Closing",
+  "",
+  "- 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.",
+  "",
+  "## More focused context",
+  "",
+  "- `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."
+]);
+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.",
+      "",
+      "## 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 next` shows the first open issue in roadmap order.",
+      '- `issy create --title "..." --last` appends a new issue.',
+      "- `issy update <id> --before <other-id>` repositions an issue.",
+      "- `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 --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 "Urgent fix" --first`.',
+      '- `issy create --title "Fix crash" --body "## Problem\\n\\nApp crashes on startup." --last`.',
+      "",
+      "Create options: `--title`, `--body`, `--priority`, `--scope`, `--type`, `--labels`, `--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> --body "## Problem\\n\\nUpdated description."`.',
+      "",
+      "Update options: `--title`, `--body`, `--priority`, `--scope`, `--type`, `--labels`, `--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]",
+    "",
+    "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"
+  ]);
+}
+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}
+
+${topicList()}`);
+  }
+  return topic.content;
+}
+
 // src/main.ts
 var args = process.argv.slice(2);
 if (args[0] === "--version" || args[0] === "-v") {
   console.log(`issy v${process.env.ISSY_PKG_VERSION || "unknown"}`);
   process.exit(0);
 }
+if (args[0] === "learn") {
+  try {
+    process.stdout.write(getLearnOutput(args.slice(1)));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "Failed to learn");
+    process.exit(1);
+  }
+  process.exit(0);
+}
 var issyDir2 = resolveIssyDir();
 var issuesDir2 = join2(issyDir2, "issues");
 process.env.ISSY_DIR = issyDir2;
@@ -2279,11 +2549,11 @@ function skill() {
 Usage: issy skill <command>
 
 Commands:
-  install    Install the issy skill for your AI coding assistant
+  install    Install the issy bootstrap skill for your AI coding assistant
 `);
     process.exit(subcommand ? 1 : 0);
   }
-  console.log(`Installing issy skill via skills CLI...
+  console.log(`Installing issy bootstrap skill via skills CLI...
 `);
   try {
     execSync("npx skills add miketromba/issy", { stdio: "inherit" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "issy",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "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.9.0",
-    "@miketromba/issy-core": "^0.9.0",
+    "@miketromba/issy-app": "^0.10.0",
+    "@miketromba/issy-core": "^0.10.0",
     "update-notifier": "^7.3.1"
   }
 }