issy 0.9.0 → 0.10.1

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?
 
@@ -81,6 +93,7 @@ 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
@@ -137,7 +150,9 @@ 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
 ```

package/dist/cli.js

@@ -2490,6 +2490,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
@@ -2524,13 +2528,15 @@ 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

package/dist/main.js

@@ -2175,12 +2175,359 @@ 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`, `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>`.",
+  "",
+  "## 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.",
+  "- 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.",
+  "",
+  "## 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.",
+      "",
+      "## 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]",
+    "",
+    "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 +2626,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.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.9.0",
-    "@miketromba/issy-core": "^0.9.0",
+    "@miketromba/issy-app": "^0.10.1",
+    "@miketromba/issy-core": "^0.10.1",
     "update-notifier": "^7.3.1"
   }
 }