agent-issues 0.0.119

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (208) hide show
  1. package/.github/agents/agent-issues.agent.md +54 -0
  2. package/.github/agents/agent-issues.claude.md +51 -0
  3. package/dist/agent-installer.d.ts +49 -0
  4. package/dist/agent-installer.js +171 -0
  5. package/dist/agent-installer.js.map +1 -0
  6. package/dist/auth-session.d.ts +40 -0
  7. package/dist/auth-session.js +107 -0
  8. package/dist/auth-session.js.map +1 -0
  9. package/dist/body-backfill.d.ts +26 -0
  10. package/dist/body-backfill.js +219 -0
  11. package/dist/body-backfill.js.map +1 -0
  12. package/dist/build-mode.d.ts +1 -0
  13. package/dist/build-mode.js +1 -0
  14. package/dist/build-mode.js.map +1 -0
  15. package/dist/cli/commands/auth.d.ts +61 -0
  16. package/dist/cli/commands/auth.js +134 -0
  17. package/dist/cli/commands/auth.js.map +1 -0
  18. package/dist/cli/commands/backfill.d.ts +8 -0
  19. package/dist/cli/commands/backfill.js +36 -0
  20. package/dist/cli/commands/backfill.js.map +1 -0
  21. package/dist/cli/commands/comments.d.ts +34 -0
  22. package/dist/cli/commands/comments.js +124 -0
  23. package/dist/cli/commands/comments.js.map +1 -0
  24. package/dist/cli/commands/context.d.ts +13 -0
  25. package/dist/cli/commands/context.js +156 -0
  26. package/dist/cli/commands/context.js.map +1 -0
  27. package/dist/cli/commands/entities.d.ts +91 -0
  28. package/dist/cli/commands/entities.js +420 -0
  29. package/dist/cli/commands/entities.js.map +1 -0
  30. package/dist/cli/commands/export.d.ts +20 -0
  31. package/dist/cli/commands/export.js +98 -0
  32. package/dist/cli/commands/export.js.map +1 -0
  33. package/dist/cli/commands/fallback.d.ts +6 -0
  34. package/dist/cli/commands/fallback.js +10 -0
  35. package/dist/cli/commands/fallback.js.map +1 -0
  36. package/dist/cli/commands/handoff.d.ts +1 -0
  37. package/dist/cli/commands/handoff.js +2 -0
  38. package/dist/cli/commands/handoff.js.map +1 -0
  39. package/dist/cli/commands/installers.d.ts +37 -0
  40. package/dist/cli/commands/installers.js +78 -0
  41. package/dist/cli/commands/installers.js.map +1 -0
  42. package/dist/cli/commands/kanban.d.ts +8 -0
  43. package/dist/cli/commands/kanban.js +83 -0
  44. package/dist/cli/commands/kanban.js.map +1 -0
  45. package/dist/cli/commands/meta.d.ts +14 -0
  46. package/dist/cli/commands/meta.js +33 -0
  47. package/dist/cli/commands/meta.js.map +1 -0
  48. package/dist/cli/commands/plan-entries.d.ts +30 -0
  49. package/dist/cli/commands/plan-entries.js +94 -0
  50. package/dist/cli/commands/plan-entries.js.map +1 -0
  51. package/dist/cli/commands/site.d.ts +29 -0
  52. package/dist/cli/commands/site.js +89 -0
  53. package/dist/cli/commands/site.js.map +1 -0
  54. package/dist/cli/commands/sql.d.ts +6 -0
  55. package/dist/cli/commands/sql.js +21 -0
  56. package/dist/cli/commands/sql.js.map +1 -0
  57. package/dist/cli/commands/synchronize.d.ts +12 -0
  58. package/dist/cli/commands/synchronize.js +31 -0
  59. package/dist/cli/commands/synchronize.js.map +1 -0
  60. package/dist/cli/commands/tenants.d.ts +29 -0
  61. package/dist/cli/commands/tenants.js +101 -0
  62. package/dist/cli/commands/tenants.js.map +1 -0
  63. package/dist/cli/index.d.ts +4 -0
  64. package/dist/cli/index.js +120 -0
  65. package/dist/cli/index.js.map +1 -0
  66. package/dist/cli/renderers.d.ts +250 -0
  67. package/dist/cli/renderers.js +286 -0
  68. package/dist/cli/renderers.js.map +1 -0
  69. package/dist/cli/shared.d.ts +97 -0
  70. package/dist/cli/shared.js +192 -0
  71. package/dist/cli/shared.js.map +1 -0
  72. package/dist/cli.d.ts +11 -0
  73. package/dist/cli.js +41 -0
  74. package/dist/cli.js.map +1 -0
  75. package/dist/context-cli.d.ts +16 -0
  76. package/dist/context-cli.js +131 -0
  77. package/dist/context-cli.js.map +1 -0
  78. package/dist/daemon/daemon-lifecycle.d.ts +1 -0
  79. package/dist/daemon/daemon-lifecycle.js +2 -0
  80. package/dist/daemon/daemon-lifecycle.js.map +1 -0
  81. package/dist/daemon/daemon-main.d.ts +14 -0
  82. package/dist/daemon/daemon-main.js +30 -0
  83. package/dist/daemon/daemon-main.js.map +1 -0
  84. package/dist/daemon/local-daemon-store.d.ts +21 -0
  85. package/dist/daemon/local-daemon-store.js +31 -0
  86. package/dist/daemon/local-daemon-store.js.map +1 -0
  87. package/dist/entity-projection.d.ts +141 -0
  88. package/dist/entity-projection.js +147 -0
  89. package/dist/entity-projection.js.map +1 -0
  90. package/dist/entra-device-login.d.ts +12 -0
  91. package/dist/entra-device-login.js +40 -0
  92. package/dist/entra-device-login.js.map +1 -0
  93. package/dist/export-files.d.ts +24 -0
  94. package/dist/export-files.js +230 -0
  95. package/dist/export-files.js.map +1 -0
  96. package/dist/export-markdown.d.ts +24 -0
  97. package/dist/export-markdown.js +343 -0
  98. package/dist/export-markdown.js.map +1 -0
  99. package/dist/help.d.ts +112 -0
  100. package/dist/help.js +1430 -0
  101. package/dist/help.js.map +1 -0
  102. package/dist/kanban/assets.d.ts +3 -0
  103. package/dist/kanban/assets.js +37 -0
  104. package/dist/kanban/assets.js.map +1 -0
  105. package/dist/kanban/index.d.ts +1 -0
  106. package/dist/kanban/index.js +2 -0
  107. package/dist/kanban/index.js.map +1 -0
  108. package/dist/kanban/server.d.ts +28 -0
  109. package/dist/kanban/server.js +118 -0
  110. package/dist/kanban/server.js.map +1 -0
  111. package/dist/mcp-installer.d.ts +32 -0
  112. package/dist/mcp-installer.js +118 -0
  113. package/dist/mcp-installer.js.map +1 -0
  114. package/dist/mcp-server/index.d.ts +11 -0
  115. package/dist/mcp-server/index.js +504 -0
  116. package/dist/mcp-server/index.js.map +1 -0
  117. package/dist/mcp-server/index.test.d.ts +1 -0
  118. package/dist/mcp-server/index.test.js +746 -0
  119. package/dist/mcp-server/index.test.js.map +1 -0
  120. package/dist/mcp-server/mcp-tool-audit.d.ts +6 -0
  121. package/dist/mcp-server/mcp-tool-audit.js +47 -0
  122. package/dist/mcp-server/mcp-tool-audit.js.map +1 -0
  123. package/dist/mcp-server/stdio.d.ts +2 -0
  124. package/dist/mcp-server/stdio.js +7 -0
  125. package/dist/mcp-server/stdio.js.map +1 -0
  126. package/dist/mcp.d.ts +2 -0
  127. package/dist/mcp.js +19 -0
  128. package/dist/mcp.js.map +1 -0
  129. package/dist/open-storage-driver.d.ts +53 -0
  130. package/dist/open-storage-driver.js +71 -0
  131. package/dist/open-storage-driver.js.map +1 -0
  132. package/dist/open-synchronize-stores.d.ts +24 -0
  133. package/dist/open-synchronize-stores.js +34 -0
  134. package/dist/open-synchronize-stores.js.map +1 -0
  135. package/dist/project-identity.d.ts +23 -0
  136. package/dist/project-identity.js +121 -0
  137. package/dist/project-identity.js.map +1 -0
  138. package/dist/runtime-access-boundary.d.ts +7 -0
  139. package/dist/runtime-access-boundary.js +182 -0
  140. package/dist/runtime-access-boundary.js.map +1 -0
  141. package/dist/service-discovery.d.ts +10 -0
  142. package/dist/service-discovery.js +64 -0
  143. package/dist/service-discovery.js.map +1 -0
  144. package/dist/site/assets.d.ts +4 -0
  145. package/dist/site/assets.js +46 -0
  146. package/dist/site/assets.js.map +1 -0
  147. package/dist/site/cloud-events-relay.d.ts +18 -0
  148. package/dist/site/cloud-events-relay.js +78 -0
  149. package/dist/site/cloud-events-relay.js.map +1 -0
  150. package/dist/site/index.d.ts +1 -0
  151. package/dist/site/index.js +2 -0
  152. package/dist/site/index.js.map +1 -0
  153. package/dist/site/server.d.ts +42 -0
  154. package/dist/site/server.js +320 -0
  155. package/dist/site/server.js.map +1 -0
  156. package/dist/skill-installer.d.ts +35 -0
  157. package/dist/skill-installer.js +174 -0
  158. package/dist/skill-installer.js.map +1 -0
  159. package/dist/vitest-setup.d.ts +1 -0
  160. package/dist/vitest-setup.js +7 -0
  161. package/dist/vitest-setup.js.map +1 -0
  162. package/package.json +42 -0
  163. package/site/dist/assets/index-DKEVC0aQ.css +1 -0
  164. package/site/dist/assets/index-DSR4mIml.js +4396 -0
  165. package/site/dist/index.html +14 -0
  166. package/skills/agent-issues-language.md +5 -0
  167. package/skills/agent-issues-operating-contract.md +208 -0
  168. package/skills/ai-agent-issues/SKILL.md +127 -0
  169. package/skills/ai-domain-modeling/ADR-FORMAT.md +48 -0
  170. package/skills/ai-domain-modeling/CONTEXT-FORMAT.md +54 -0
  171. package/skills/ai-domain-modeling/SKILL.md +45 -0
  172. package/skills/ai-grill-with-docs/SKILL.md +28 -0
  173. package/skills/ai-handoff/SKILL.md +41 -0
  174. package/skills/ai-implement/SKILL.md +98 -0
  175. package/skills/ai-migrate-docs/SKILL.md +65 -0
  176. package/skills/ai-next-work/SKILL.md +43 -0
  177. package/skills/ai-plan/SKILL.md +41 -0
  178. package/skills/ai-prepare/SKILL.md +79 -0
  179. package/skills/ai-prototype/LOGIC.md +67 -0
  180. package/skills/ai-prototype/SKILL.md +31 -0
  181. package/skills/ai-prototype/UI.md +112 -0
  182. package/skills/ai-recipe-migration/SKILL.md +49 -0
  183. package/skills/ai-start-work/SKILL.md +56 -0
  184. package/skills/ai-tdd/SKILL.md +99 -0
  185. package/skills/ai-tdd/deep-modules.md +33 -0
  186. package/skills/ai-tdd/interface-design.md +20 -0
  187. package/skills/ai-tdd/mocking.md +28 -0
  188. package/skills/ai-tdd/refactoring.md +10 -0
  189. package/skills/ai-tdd/tests.md +74 -0
  190. package/skills/ai-to-issues/SKILL.md +70 -0
  191. package/skills/ai-to-prd/SKILL.md +33 -0
  192. package/skills/ai-wayfinder/SKILL.md +110 -0
  193. package/skills/recipes/README.md +29 -0
  194. package/skills/recipes/adr.md +21 -0
  195. package/skills/recipes/context-summary.md +17 -0
  196. package/skills/recipes/context-term.md +3 -0
  197. package/skills/recipes/debt.md +21 -0
  198. package/skills/recipes/epic.md +21 -0
  199. package/skills/recipes/handoff.md +29 -0
  200. package/skills/recipes/initiative.md +21 -0
  201. package/skills/recipes/issue-comment.md +15 -0
  202. package/skills/recipes/issue.md +33 -0
  203. package/skills/recipes/prd.md +29 -0
  204. package/skills/recipes/project.md +21 -0
  205. package/skills/recipes/user-story.md +15 -0
  206. package/skills/recipes/version.md +13 -0
  207. package/skills/recipes/wayfinder-map.md +25 -0
  208. package/skills/recipes/wayfinder-ticket.md +17 -0
package/site/dist/index.html ADDED
@@ -0,0 +1,14 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <title>agent-issues viewer</title>
7
+ <style>#app { min-height: 100vh; }</style>
8
+ <script type="module" crossorigin src="/assets/index-DSR4mIml.js"></script>
9
+ <link rel="stylesheet" crossorigin href="/assets/index-DKEVC0aQ.css">
10
+ </head>
11
+ <body>
12
+ <div id="app"></div>
13
+ </body>
14
+ </html>
package/skills/agent-issues-language.md ADDED
@@ -0,0 +1,5 @@
1
+ # Language standard
2
+
3
+ Use ASD-STE100 Simplified Technical English for every message you write. This rule applies to questions, status updates, explanations, responses, tracker records, plans, prompts, and handoffs.
4
+
5
+ Apply the ASD-STE100 writing rules and dictionary exactly. Do not replace them with your own summary of the standard.
package/skills/agent-issues-operating-contract.md ADDED
@@ -0,0 +1,208 @@
1
+ # Shared Skill Operating Contract
2
+
3
+ All bundled `ai-*` skills follow this contract. They also follow the shared [language standard](./agent-issues-language.md).
4
+
5
+ ## Tracker is canonical
6
+
7
+ `agent-issues` is the single tracker for work. A chat plan, a scratch note, a raw markdown document, and a test file are not work records.
8
+
9
+ - Use the exact operation recipe named by the active skill. Start with its MCP tool. Use the listed CLI fallback only when the MCP server is unavailable or lacks that operation.
10
+ - Before you plan, implement, migrate, or hand off work, run the **Entity Read** recipe, the **Relation Query** recipe, and the **Context Read** recipe to find the active tracked scope.
11
+ - Do not leave a new workstream, ADR, or implementation follow-up untracked. Run the **Entity Create And Edit** recipe to create the missing record when its parent is clear. If not, ask one routing question.
12
+ - For new feature planning, create a new initiative by default. Reuse an existing initiative only when the user asks for that directly.
13
+ - Run the **Entity State And Structure** recipe to change issue status and Plan status. Derive user story and PRD status from their linked issues. An ADR is `current` unless it is `superseded` or `archived`.
14
+ - Treat each entity's complete `reference` field as its public tracker identity. Copy it exactly as returned by the tracker whenever you report or use an entity. Never abbreviate or truncate it, and never replace it with the internal `id`.
15
+
16
+ Issue comments use complete `COM_` references. They are issue discussion, not tracker state: use tracker records for scope, decisions, blockers, handoffs, and status.
17
+
18
+ ## Operation Recipes
19
+
20
+ Every tracker operation uses one of these recipes. CLI fallbacks use `--json`.
21
+
22
+ **Kind** is `Read`, `Write`, `Destructive write`, or `Host`. A `Read` recipe does not change tracker data. A `Write` recipe changes tracker data. A `Destructive write` recipe requires the stated inspection or confirmation flow. A `Host` recipe changes the local environment and has no MCP equivalent.
23
+
24
+ ### Entity Read
25
+
26
+ **Kind:** Read.
27
+
28
+ - MCP: `entity_show({ reference })`.
29
+ - CLI fallback: `agent-issues show <reference> --json`.
30
+
31
+ ### Entity List
32
+
33
+ **Kind:** Read.
34
+
35
+ - MCP: `entity_list({ kind, statuses?, parentId?, limit? })`.
36
+ - CLI fallback: `agent-issues list <kind> [--status <status[,status]>] [--parent <parent>] [--limit <count>] --json`.
37
+
38
+ ### Relation Query
39
+
40
+ **Kind:** Read.
41
+
42
+ - MCP: `relation_query({ entityId, direction?, types? })`.
43
+ - CLI fallback: `agent-issues relations <entityId> [--direction <incoming|outgoing|both>] [--type <type[,type]>] --json`.
44
+
45
+ ### Initiative Read
46
+
47
+ **Kind:** Read.
48
+
49
+ - MCP: `initiative_bundle({ initiativeId })`.
50
+ - CLI fallback: `agent-issues show <initiativeId> --json`.
51
+
52
+ ### Next Work
53
+
54
+ **Kind:** Read.
55
+
56
+ - MCP: `entity_next_work({ scopeId })`.
57
+ - CLI fallback: `agent-issues next-work <initiativeOrDescendantId> --json`.
58
+
59
+ ### Context Read
60
+
61
+ **Kind:** Read.
62
+
63
+ - MCP: `context_show({ scopeRef? })`, `context_directory({})`, `context_search({ query?, view? })`, or `context_conflicts({ query?, view? })`.
64
+ - CLI fallback: `agent-issues context show [<scope>] --json`, `agent-issues context list --json`, `agent-issues context search <query> [--view <all|global|initiatives>] --json`, or `agent-issues context conflicts [<query>] [--view <all|initiatives>] --json`.
65
+
66
+ ### Context Write
67
+
68
+ **Kind:** Write.
69
+
70
+ - MCP: `context_set({ scopeRef?, title, summary, expectedRevision?, expectedContentHash? })`, `context_term_define({ scopeRef?, term, definition, avoid?, expectedRevision?, expectedContentHash? })`, or `context_term_forget({ scopeRef?, term, expectedRevision?, expectedContentHash? })`.
71
+ - CLI fallback: `agent-issues context set --scope <scope> --title "<title>" --body-file - --json`, `agent-issues context define "<term>" --scope <scope> --body-file - [--avoid "<term[,term]>"] --json`, or `agent-issues context forget "<term>" --scope <scope> --json`.
72
+
73
+ ### Entity Create And Edit
74
+
75
+ **Kind:** Write.
76
+
77
+ - MCP create: `entity_create({ kind, title, body?, parentId?, status?, category?, priority?, type?, links? })`.
78
+ - MCP edit: first use the **Entity Read** recipe, then call `entity_edit({ entityId, title?, body?, category?, priority?, type?, expectedRevision, expectedContentHash })`.
79
+ - CLI fallback: `agent-issues create <kind> --title "<title>" [--parent <parent>] --body-file - --json`, or `agent-issues edit <entityId> [--title "<title>"] --body-file - --json`.
80
+
81
+ ### Entity State And Structure
82
+
83
+ **Kind:** Write.
84
+
85
+ - MCP: `entity_status({ entityId, status })`, `entity_move({ entityId, newParentId })`, or `entity_archive({ entityId })`.
86
+ - CLI fallback: `agent-issues status <entityId> <status> --json`, `agent-issues move <entityId> <newParentId> --json`, or `agent-issues archive <entityId> --json`.
87
+
88
+ ### Entity Relations
89
+
90
+ **Kind:** Write.
91
+
92
+ - MCP: `relation_link({ fromId, relationType, toId })` or `relation_unlink({ fromId, relationType, toId })`.
93
+ - CLI fallback: `agent-issues link <fromId> <relationType> <toId> --json` or `agent-issues unlink <fromId> <relationType> <toId> --json`.
94
+
95
+ ### Plan Entry Read
96
+
97
+ **Kind:** Read.
98
+
99
+ - MCP: `plan_entry_list({ planId })` or `plan_entry_history({ entryId })`.
100
+ - CLI fallback: `agent-issues plan-entry list <planId> --json` or `agent-issues plan-entry history <entryId> --json`.
101
+
102
+ ### Plan Entry Write
103
+
104
+ **Kind:** Write.
105
+
106
+ - MCP: `plan_entry_create({ planId, role, body, scopeDirection?, referencedEntityIds?, supersededEntryIds? })`, `plan_entry_edit({ entryId, body, expectedRevision, expectedContentHash })`, or `plan_entry_delete({ entryId, expectedRevision, expectedContentHash })`.
107
+ - CLI fallback: `agent-issues plan-entry add <planId> --role <role> --body-file - [--scope-direction <included|excluded>] [--reference <entity>] [--supersedes <entry>] --json`, `agent-issues plan-entry edit <planId> <entryId> --body-file - --json`, or `agent-issues plan-entry delete <planId> <entryId> --json`.
108
+
109
+ ### Plan Entry Issue Link
110
+
111
+ **Kind:** Write.
112
+
113
+ - MCP: `plan_entry_issue_link({ entryId, issueId })` or `plan_entry_issue_unlink({ entryId, issueId })`.
114
+ - CLI fallback: `agent-issues link <planEntryId> informs <issueId> --json` or `agent-issues unlink <planEntryId> informs <issueId> --json`.
115
+ - The MCP operation accepts an issue target only. For existing Plan-entry-to-PRD provenance, MCP is unavailable; use `agent-issues link <planEntryId> informs <prdId> --json` or its unlink fallback.
116
+
117
+ ### Issue Comment Read
118
+
119
+ **Kind:** Read.
120
+
121
+ - MCP: `comment_list({ issueId, before?, all? })` or `comment_history({ commentId })`.
122
+ - CLI fallback: `agent-issues comment list <issueId> [--before <cursor>] [--all] --json` or `agent-issues comment history <commentId> --json`.
123
+
124
+ ### Issue Comment Write
125
+
126
+ **Kind:** Write.
127
+
128
+ - MCP: `comment_create({ issueId, body, referencedIssueIds? })`, `comment_edit({ commentId, body, referencedIssueIds?, expectedRevision, expectedContentHash })`, or `comment_delete({ commentId, expectedRevision, expectedContentHash })`.
129
+ - CLI fallback: `agent-issues comment add <issueId> --body-file - [--reference <issue>] --json`, `agent-issues comment edit <issueId> <commentId> --body-file - [--reference <issue>] --json`, or `agent-issues comment delete <issueId> <commentId> --json`.
130
+
131
+ ### Revision Read
132
+
133
+ **Kind:** Read.
134
+
135
+ - MCP: `entity_history({ entityId, revision })`, `context_revision({ scopeRef?, revision })`, or `context_term_revision({ scopeRef?, term, revision })`.
136
+ - CLI fallback: `agent-issues history <entityId> --revision <revision> --json`, `agent-issues history --context <scope> --revision <revision> --json`, or `agent-issues history --context <scope> --term <term> --revision <revision> --json`.
137
+
138
+ ### Entity Restore
139
+
140
+ **Kind:** Destructive write.
141
+
142
+ - MCP: first call `entity_restore_inspect({ entityId, revision })`, then call `entity_restore({ entityId, revision, confirmationToken })` with its token.
143
+ - CLI fallback: `agent-issues restore <entityId> --revision <revision> --json`.
144
+
145
+ ### Context Restore
146
+
147
+ **Kind:** Destructive write.
148
+
149
+ - MCP: unavailable.
150
+ - CLI fallback: `agent-issues restore --context <scope> --revision <revision> --json` or `agent-issues restore --context <scope> --term <term> --revision <revision> --json`.
151
+
152
+ ### Handoff Read
153
+
154
+ **Kind:** Read.
155
+
156
+ - MCP: `entity_list({ kind: "handoff" })`, `relation_query({ entityId: handoffId, direction: "outgoing", types: ["handsOff"] })`, then `entity_show({ reference: handoffId })`.
157
+ - CLI fallback: `agent-issues list handoff --json`, `agent-issues relations <handoffId> --direction outgoing --type handsOff --json`, then `agent-issues show <handoffId> --json`.
158
+
159
+ ### Handoff Write
160
+
161
+ **Kind:** Write.
162
+
163
+ - MCP: `entity_create({ kind: "handoff", title, body, links: [{ relationType: "handsOff", targetId: focusId }] })`.
164
+ - CLI fallback: `agent-issues create handoff --title "<title>" --body-file - --link handsOff <focusId> --json`.
165
+
166
+ ### Host Operations
167
+
168
+ **Kind:** Host.
169
+
170
+ These operations have no MCP equivalent. Use the CLI: `install-mcp`, `list-mcp`, `uninstall-mcp`, `install-agent`, `list-agent`, `uninstall-agent`, `install-skills`, `list-skills`, `uninstall-skills`, and `site`.
171
+
172
+ ## Record body recipes
173
+
174
+ Before you create or replace authored body content, identify the record type and read its matching recipe in [`recipes`](./recipes/README.md).
175
+
176
+ - When the catalog has a recipe for the record type, use that recipe for the body. This applies to context summaries, context terms, entities, handoffs, issue comments, and Wayfinder records.
177
+ - Do this before the **Entity Create And Edit** recipe, **Context Write** recipe, **Plan Entry Write** recipe, **Issue Comment Write** recipe, or **Handoff Write** recipe creates or replaces a body.
178
+ - Tracker actions that do not create or replace a body do not need a recipe.
179
+
180
+ ## Current contracts replace obsolete tests
181
+
182
+ Do not keep old behavior or compatibility paths only because an old test expects them. When the active issue or a relevant ADR replaces behavior, update or remove the old implementation and its tests. Keep them only when a current compatibility or migration requirement says so.
183
+
184
+ ## Resolve scope efficiently
185
+
186
+ Use compact, server-selected reads for routine discovery and graph navigation:
187
+
188
+ - Run the **Entity List** recipe to find candidates by kind. Narrow by status, parent, or limit when the scope is known.
189
+ - Run the **Relation Query** recipe with direction and type filters when the skill needs a specific edge set.
190
+ - Run the **Entity Read** recipe only when the skill needs an authored body or full stored record.
191
+ - Run the **Initiative Read** recipe only for a planned initiative-wide view. Do not use it for routine discovery or blocker checks.
192
+ - Prefer the structured MCP result directly. Do not parse presentation text or add downstream filtering that an MCP input can express.
193
+
194
+ To resume work, run the **Handoff Read** recipe.
195
+
196
+ ## Context is database-backed
197
+
198
+ The canonical glossary lives in the `agent-issues` database. Do not treat a raw `CONTEXT.md` or `CONTEXT-MAP.md` file as a source of truth.
199
+
200
+ - Run the **Context Read** recipe before you use project-specific terms.
201
+ - Run the **Context Read** recipe with its search or conflict input for project-wide discovery and before you standardize an ambiguous term.
202
+ - Run the **Context Write** recipe to create missing project or initiative context with authored title and body content.
203
+ - Run the **Context Write** recipe to save resolved terms right away or remove obsolete terms when the current glossary replaces them.
204
+ - Keep the shared context free of implementation detail. It is a glossary, not a specification and not a scratch pad.
205
+
206
+ ## Preserve continuity
207
+
208
+ When work must resume in another session, run the **Handoff Write** recipe to create a graph entity that targets the active issue, user story, PRD, ADR, or initiative. Do not create a sidecar handoff file.
package/skills/ai-agent-issues/SKILL.md ADDED
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: ai-agent-issues
3
+ description: Internal orientation guide for agents working in repos that use agent-issues. Use when you need to understand the tracker model, MCP tool selection, or workflow before you act.
4
+ argument-hint: Which part of agent-issues do you need to review before you continue?
5
+ ---
6
+
7
+ Follow the shared [language standard](../agent-issues-language.md).
8
+ Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
9
+
10
+ # Agent-Issues Tooling Guide
11
+
12
+ This is an internal reference skill for the agent. Use it before you continue with real work, when you need more information about how `agent-issues` operates.
13
+
14
+ Do not start this skill only because the repository uses `agent-issues`. Start it when you lack operational context: which tracker action to use, how entities relate, how statuses change, or which `ai-*` skill owns the next step.
15
+
16
+ ## What to do
17
+
18
+ Start from the named recipes in the shared operating contract before you guess. Each recipe specifies the MCP tool, required input fields, and exact CLI fallback. Use available MCP tool names, descriptions, and typed inputs to validate the recipe against the running server.
19
+
20
+ Once you have this information, act. Do not keep explaining the task to yourself. Match the task to the smallest tracker action or `ai-*` skill that moves the work forward.
21
+
22
+ ## Core mental model
23
+
24
+ `agent-issues` tracks work as a graph. It does not track work as loose markdown files.
25
+
26
+ - `initiative`: the top-level workstream.
27
+ - `plan`: the planning record that tracks questions and decisions before it becomes ready for PRD conversion.
28
+ - `prd`: the plan or product requirement for an initiative.
29
+ - `userStory`: the user-visible slice that the PRD commits to.
30
+ - `issue`: the unit of work you can execute.
31
+ - `adr`: a hard-to-reverse architecture decision.
32
+ - `context`: the database-backed glossary for shared, project-scoped, or initiative-scoped terms.
33
+
34
+ Issue comments are database records owned by an issue, not graph entities. Use comment tracker actions to read, create, edit, delete, and inspect comment history. Send authored text in the MCP body field.
35
+
36
+ An issue is not always a flat leaf. An issue can `decompose` into sub-issues.
37
+
38
+ - Create a sub-issue with another issue as parent.
39
+ - Move a sub-issue by changing its structural parent.
40
+ - Link `fixes` from leaf issues to user stories. Parent issues group work and can own sub-issues.
41
+
42
+ ## Debt records
43
+
44
+ Debt records are reference-only records for accepted cost or risk. They do not represent committed work.
45
+
46
+ - A debt record has one project, epic, initiative, or issue owner. PRDs and user stories cannot own debt records.
47
+ - Debt lifecycle states are open, resolved, and archived. Lifecycle changes are manual and reversible.
48
+ - An epic, initiative, or issue can resolve debt. Resolver state does not change debt lifecycle state.
49
+ - Use the [Debt Recipe](../recipes/debt.md) before an authored debt body write. Keep category, priority, lifecycle, ownership, and graph relations outside the body.
50
+
51
+ Run the **Entity List** recipe to find records by kind and narrow by status, parent, or limit. Run the **Relation Query** recipe with direction and type filters. Run the **Entity Read** recipe only when you need authored content or a full record. Run the **Initiative Read** recipe only for a planned initiative-wide view.
52
+
53
+ For an entity's complete working context, run the **Relation Query** recipe once without direction or type filters. It includes the entity's full body and directly related records in both directions. Add filters only when a smaller result is needed. **Entity List** recipe results can include `openBlockers`, so candidate blocked state is visible without a relation query per candidate.
54
+
55
+ ## Initiative reads
56
+
57
+ For real work, start with compact discovery and edge inspection. Use authored or initiative-wide content only when the task needs it:
58
+
59
+ - To resume a workstream, run the **Handoff Read** recipe. Its selected handoff body carries the session context.
60
+ - Use filtered compact lists and relations to move from the target to the active issue and its blockers.
61
+ - Run the **Initiative Read** recipe only when the task needs the whole initiative graph and authored records.
62
+ - Run the **Context Read** recipe with it, so your language and plan match the glossary.
63
+ - If a term remains unclear, run the **Context Read** recipe with search or conflict input for project-wide discovery.
64
+ - Run a narrower **Entity Read** recipe or **Relation Query** recipe only when the task needs one entity or edge set.
65
+
66
+ Default steps:
67
+
68
+ 1. Run the **Entity List** recipe to find candidates.
69
+ 2. Run the **Relation Query** recipe to navigate.
70
+ 3. Run the **Entity Read** recipe for authored content when needed.
71
+ 4. Run the **Initiative Read** recipe only when the whole initiative is a planned input.
72
+
73
+ Do not fetch full records and trim them with routine downstream filters. Use compact MCP inputs and structured results, or track the recurring capability gap.
74
+
75
+ ## Tracker action selection
76
+
77
+ Use the exact named recipe for the job:
78
+
79
+ - Find entities: **Entity List** recipe, **Entity Read** recipe, **Relation Query** recipe, or **Initiative Read** recipe.
80
+ - Change tracked data: **Entity Create And Edit** recipe, **Entity State And Structure** recipe, **Entity Relations** recipe, **Entity Restore** recipe, or **Context Restore** recipe.
81
+ - Read revision history: **Revision Read** recipe. Record issue discussion: **Issue Comment Read** recipe or **Issue Comment Write** recipe.
82
+ - Manage vocabulary: **Context Read** recipe or **Context Write** recipe.
83
+ - Create or edit Plan entries: **Plan Entry Write** recipe. Read Plan entries: **Plan Entry Read** recipe. Link Plan entries: **Plan Entry Issue Link** recipe.
84
+ - Preserve continuity: **Handoff Read** recipe or **Handoff Write** recipe.
85
+ - Use **Host Operations** recipe only for site lifecycle, agent or skill installation, and MCP installation.
86
+
87
+ ## Workflow map
88
+
89
+ When you must choose the next packaged skill, pick it clearly:
90
+
91
+ 1. `ai-domain-modeling` to sharpen terms, boundaries, glossary context, and architecture decisions.
92
+ 2. `ai-grill-with-docs` to challenge and sharpen a plan one question at a time, with domain modeling.
93
+ 3. `ai-plan` for the same domain-modeling result at a faster pace, through batches of questions.
94
+ 4. `ai-to-prd` to capture the plan as a PRD and user stories.
95
+ 5. `ai-to-issues` to break the plan into issues you can execute.
96
+ 6. `ai-handoff` to record where the work stands for the next session.
97
+ 7. `ai-prepare` to resolve an initiative, issue, user story, or handoff and load its context, then stop for a conversation fork before the build starts.
98
+ 8. `ai-start-work` as the single-session alternative: it also selects the next workable issue, but it drives straight into a build skill without forking.
99
+ 9. `ai-tdd` to build one issue through a red-green-refactor loop, either started fresh after an `ai-prepare` fork or handed off directly by `ai-start-work`.
100
+ 10. `ai-implement` as the alternative to `ai-tdd` for the same fork point or hand-off: thin, independently-verified vertical slices for changes that do not fit a red-green-refactor loop (broad refactors, config/infrastructure changes, multi-file migrations).
101
+ 11. `ai-migrate-docs` to import existing documentation into the tracker.
102
+
103
+ If you are unsure where the work sits in the workflow, inspect entity and relation summaries first. Use `show <initiativeId>` only if you must see the whole initiative to choose the workflow.
104
+
105
+ ## Prepare-then-fork
106
+
107
+ Prefer `ai-prepare` over `ai-start-work` for real build sessions. Do not plan and build in the same conversation. `ai-prepare` gathers context and reports a briefing, then the conversation forks before `ai-tdd` or `ai-implement` starts the build in a fresh conversation with a small context. This keeps a long build loop from growing the cost of a session that also carries the earlier planning and discovery. Use `ai-start-work` only when the user explicitly wants one continuous session.
108
+
109
+ To save a handoff, run the **Handoff Write** recipe. Run the **Entity Create And Edit** recipe to fix its title or body.
110
+
111
+ ## Initiative default
112
+
113
+ For new feature planning, assume a new initiative by default.
114
+
115
+ - A new grilling session for a new feature normally needs a new initiative.
116
+ - A new PRD for a new feature normally needs a new initiative.
117
+ - Reuse an existing initiative only when the user asks for that directly, or when the work is clearly a continuation of an initiative that is already tracked.
118
+
119
+ Do not add new feature work to an existing initiative only because the themes seem close.
120
+
121
+ ## Working rules
122
+
123
+ - Act from real tracker results, not from memory.
124
+ - Keep `agent-issues` as the source of truth. Do not invent tracker state.
125
+ - If the task depends on a tenant or scope, provide the tenant or entity identifier directly to the named recipe.
126
+ - Do not turn this skill into a tutorial unless the user asks directly for an explanation of the tooling.
127
+ - If the next step is to execute rather than to explain, hand off right away to the matching `ai-*` skill.
package/skills/ai-domain-modeling/ADR-FORMAT.md ADDED
@@ -0,0 +1,48 @@
1
+ # ADR Format
2
+
3
+ An ADR is an `adr` entity in `agent-issues`. It is not a file, unless the user asks for one directly.
4
+ Use the [ADR recipe](../../recipes/adr.md) for its body.
5
+
6
+ ## Template
7
+
8
+ Use the ADR title for the short decision name. Store the explanation in the entity body.
9
+
10
+ Suggested body shape:
11
+
12
+ ```md
13
+ {1-3 sentences: what is the context, what did we decide, and why.}
14
+ ```
15
+
16
+ This is enough. The value is in the record: a decision was made, and why.
17
+
18
+ ## Optional sections
19
+
20
+ Add these sections only when they add real value:
21
+
22
+ - `Status` frontmatter (`current | superseded | archived`)
23
+ - `Considered Options`
24
+ - `Consequences`
25
+
26
+ ## Identity
27
+
28
+ Let `agent-issues` assign the ADR ID. Do not create a separate numbering scheme outside the tracker.
29
+
30
+ ## When to offer an ADR
31
+
32
+ All three of these must be true:
33
+
34
+ 1. The decision is hard to reverse.
35
+ 2. The decision is surprising without context.
36
+ 3. The decision came from a real trade-off.
37
+
38
+ If a decision is easy to reverse, skip it. If it is not surprising, no one will ask why. If there was no real alternative, there is nothing useful to record.
39
+
40
+ ### What qualifies
41
+
42
+ - Architecture shape.
43
+ - Integration patterns between contexts.
44
+ - Technology choices that create lock-in.
45
+ - Boundary and scope decisions.
46
+ - Deliberate moves away from the obvious path.
47
+ - Constraints not visible in the code.
48
+ - Rejected alternatives, when the rejection is not obvious.
package/skills/ai-domain-modeling/CONTEXT-FORMAT.md ADDED
@@ -0,0 +1,54 @@
1
+ # Context Record Format
2
+
3
+ The canonical glossary lives in the `agent-issues` database. It does not live in a raw file.
4
+
5
+ Project context contains project-wide terms. Initiative context is the database equivalent of a `CONTEXT.md` file inside an initiative folder.
6
+ Use the [Context Summary recipe](../../recipes/context-summary.md) for a context body and the [Context Term recipe](../../recipes/context-term.md) for a term definition.
7
+
8
+ Run the **Context Read** recipe to read the relevant project or initiative glossary.
9
+
10
+ For project-wide discovery across shared and initiative scopes, run the **Context Read** recipe with search input.
11
+
12
+ Before you add or rename a term, run the **Context Read** recipe with conflict input to check whether the same label already exists in another scope.
13
+
14
+ Run the **Context Read** recipe with directory input only when you need the raw list of stored scopes.
15
+
16
+ Run the **Context Write** recipe to set up or update shared context with direct title and body text. Run it again to add or update a term with its definition and `avoid` terms as structured input.
17
+
18
+ ## Structure
19
+
20
+ ```json
21
+ {
22
+ "context": {
23
+ "key": "INIT1",
24
+ "scopeKind": "initiative",
25
+ "scopeEntityId": "INIT1",
26
+ "scopeLabel": "Payments",
27
+ "title": "Payments Context",
28
+ "summary": "Glossary of initiative-specific terms for Payments.",
29
+ "exists": true
30
+ },
31
+ "terms": [
32
+ {
33
+ "term": "Order",
34
+ "definition": "A customer request accepted and tracked by the system.",
35
+ "avoid": ["Purchase", "Transaction"]
36
+ },
37
+ {
38
+ "term": "Invoice",
39
+ "definition": "A request for payment sent to a customer after delivery.",
40
+ "avoid": ["Bill", "Payment request"]
41
+ }
42
+ ]
43
+ }
44
+ ```
45
+
46
+ ## Rules
47
+
48
+ - Be decisive. When more than one word exists for the same idea, pick the best one. List the others under `avoid`.
49
+ - Keep each definition short: one or two sentences. Define what the term is, not what it does.
50
+ - Include only terms specific to this project's context. Do not include general programming concepts.
51
+ - Group terms under subheadings when a natural cluster forms. If all terms belong to one area, a flat list is fine.
52
+ - Keep initiative context in the database. Do not copy it into a raw markdown file.
53
+
54
+ The `agent-issues` context model is initiative-scoped by default, with an optional shared default context. Read the relevant initiative context first. Use project-wide search only when you need to resolve which term is correct. Then update the scoped glossary, one term at a time, as the vocabulary becomes precise.
package/skills/ai-domain-modeling/SKILL.md ADDED
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: ai-domain-modeling
3
+ description: Builds and sharpens the tracked domain model. It resolves terms, tests boundaries with real scenarios, checks the model against the code, and records glossary terms and architecture decisions. Use it when the user wants to define domain language, refine a model, record an ADR, or when another skill needs active domain modeling.
4
+ ---
5
+
6
+ Follow the shared [language standard](../agent-issues-language.md).
7
+ Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
8
+
9
+ # Domain Modeling
10
+
11
+ Actively build and sharpen the project's domain model while you design. This skill changes the model. It challenges terms, tests edge cases, and records resolved language and decisions. If you only read initiative context for known vocabulary, you do not need this skill.
12
+
13
+ ## During the session
14
+
15
+ ### Challenge against the glossary
16
+
17
+ The user can use a term that conflicts with the relevant glossary or the **Context Read** recipe with conflict input. When this happens, point it out right away.
18
+
19
+ ### Sharpen fuzzy language
20
+
21
+ The user can use a vague or overloaded term. When this happens, propose one precise term.
22
+
23
+ ### Discuss concrete scenarios
24
+
25
+ When you discuss domain relationships, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force precision about the boundaries between concepts.
26
+
27
+ ### Cross-reference with code
28
+
29
+ When the user states how something works, check whether the code agrees. If you find a conflict, point it out.
30
+
31
+ ### Update context inline
32
+
33
+ When you resolve a term, run the **Context Write** recipe to update the database-backed context right away. Do not batch glossary updates. Use the rules in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
34
+
35
+ ### Offer ADRs only when needed
36
+
37
+ Offer to create an ADR only when all three of these are true:
38
+
39
+ 1. The decision is hard to reverse.
40
+ 2. The decision is surprising without context.
41
+ 3. The decision came from a real trade-off.
42
+
43
+ If any of the three is not true, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
44
+
45
+ When an ADR is needed, run the **Entity Create And Edit** recipe to create or update the `adr` entity under the relevant initiative. Do not create a markdown ADR file unless the user asks for one directly. If the ADR limits implementation work, run the **Entity Relations** recipe to link it to the affected issues with `constrains`.
package/skills/ai-grill-with-docs/SKILL.md ADDED
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: ai-grill-with-docs
3
+ description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
4
+ ---
5
+
6
+ Follow the shared [language standard](../agent-issues-language.md).
7
+ Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
8
+ Run this interview with the `ai-domain-modeling` skill.
9
+
10
+ ## Persist Plan State
11
+
12
+ At the start of a new grilling effort, run the **Entity Read** recipe for the active initiative. Run the **Entity Create And Edit** recipe to create one initiative-owned Plan with a stable Goal and Context body. If the user gives an explicit Plan reference, resume that Plan instead. Do not infer a Plan to resume or create a duplicate Plan.
13
+
14
+ Use the **Plan Entry Write** recipe to record planning state as it changes:
15
+
16
+ - Record each design question as a `question` entry before asking it.
17
+ - Record each durable user answer before continuing. When an answer resolves a design question, add a `decision` entry that supersedes the question reference.
18
+ - Record each durable fact from code or tool output before it affects later planning. Use the approved role that describes the fact.
19
+ - Replace a changed entry by superseding it. A decision targets a question or decision. Edit only corrections.
20
+ - Add no entry for transient conversation that does not change planning state.
21
+
22
+ Run the **Entity State And Structure** recipe to set the Plan to `ready` only after the planning frontier is empty and the user confirms shared understanding. A ready Plan can retain only explicit implementation-discovery questions.
23
+
24
+ Interview the user closely about the plan until you reach a shared understanding. Walk down each branch of the design tree. Resolve the dependencies between decisions one by one. For each question, give your recommended answer.
25
+
26
+ Ask one question at a time. Wait for the user's answer before you ask the next question. Do not ask more than one question at a time. This confuses the user.
27
+
28
+ If you can answer a question by exploring the codebase, explore the codebase instead.
package/skills/ai-handoff/SKILL.md ADDED
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: ai-handoff
3
+ description: Compact the current conversation into a handoff document for another agent to pick up, anchored to the active agent-issues records.
4
+ argument-hint: What will the next session be used for?
5
+ ---
6
+
7
+ Follow the shared [language standard](../agent-issues-language.md).
8
+ Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
9
+
10
+ Write a handoff that lets a new agent continue the work without rebuilding the state from scratch. Do not create a file, including a temp file or a workspace artifact.
11
+ Use the [Handoff recipe](../recipes/handoff.md) for the tracked handoff body.
12
+
13
+ The handoff must include:
14
+
15
+ - The tracked entity IDs, titles, and statuses that define the current scope.
16
+ - The relevant blockers from `blocks` relations.
17
+ - The relevant user stories or ADR constraints linked to the active issue.
18
+ - The files or artifacts to read next, given by path instead of copied text.
19
+ - A `suggested skills` section for the next agent.
20
+
21
+ Do not copy content that already exists in a PRD, an ADR, a plan, an issue, a commit, or a diff. Reference it by path or ID instead.
22
+
23
+ Remove sensitive information such as API keys, passwords, or personal data.
24
+
25
+ If the user gave arguments, treat them as a description of the next session's focus. Shape the handoff to match.
26
+
27
+ ## Save the handoff in the tracker
28
+
29
+ Once you write the handoff body, save it in `agent-issues` so the next agent can retrieve it. Do not stop at returning text in your response.
30
+
31
+ Run the **Handoff Write** recipe to create a handoff with direct title and body text, then link it with `handsOff` to the active issue, PRD, ADR, or initiative. The returned handoff reference is the continuation target.
32
+
33
+ After you save the handoff, return this continuation prompt in a code block, with the returned handoff ID (for example, `HO7`):
34
+
35
+ ```text
36
+ Continue from handoff <handoffId>.
37
+ ```
38
+
39
+ To fix a saved handoff, run the **Entity Create And Edit** recipe to update its title or body.
40
+
41
+ If you need more text beyond the saved handoff, put it in your response only.