@iloom/cli 0.9.1 → 0.10.0

package/dist/prompts/plan-prompt.txt

@@ -79,6 +79,7 @@ After the subagent completes, include its context summary when sending the plan
 
 {{#if USE_GEMINI_REVIEWER}}
 **Reviewer: Gemini** - Use available Gemini MCP tools (look for tools with "gemini" in the name) to review your plan. Ask for feedback on:
+- **Complexity sizing** (each child issue should target SIMPLE: <5 files, <200 LOC, no cross-cutting changes, no architectural signals)
 - Proper scoping (1 issue = 1 loom = 1 PR)
 - Dependency identification and sequencing
 - Technical architecture and design decisions
@@ -92,6 +93,7 @@ After the subagent completes, include its context summary when sending the plan
 {{/if}}
 {{#if USE_CODEX_REVIEWER}}
 **Reviewer: Codex** - Use available Codex MCP tools (look for tools with "codex" in the name) to review your plan. Ask for feedback on:
+- **Complexity sizing** (each child issue should target SIMPLE: <5 files, <200 LOC, no cross-cutting changes, no architectural signals)
 - Proper scoping (1 issue = 1 loom = 1 PR)
 - Dependency identification and sequencing
 - Technical architecture and design decisions
@@ -105,6 +107,7 @@ After the subagent completes, include its context summary when sending the plan
 {{/if}}
 {{#unless USE_GEMINI_REVIEWER}}{{#unless USE_CODEX_REVIEWER}}
 **Reviewer: Claude** - Review the plan yourself, considering:
+- **Complexity sizing** (each child issue should target SIMPLE: <5 files, <200 LOC, no cross-cutting changes, no architectural signals)
 - Proper scoping (1 issue = 1 loom = 1 PR)
 - Dependency identification and sequencing
 - Technical architecture and design decisions
@@ -118,11 +121,19 @@ After the subagent completes, include its context summary when sending the plan
 
 ---
 
+## Formatting Rules
+
+**Always write in standard GitHub-flavored Markdown.** The MCP issue management tools handle any necessary format conversion automatically (e.g., Markdown to ADF for Jira). This means:
+- Use standard Markdown: `##` headings, `**bold**`, `| tables |`, `` ``` `` code blocks, `- bullet lists`
+- Use `<details><summary>` tags for collapsed/expandable sections — the converter handles these
+- Do NOT use platform-specific markup (e.g., Jira wiki syntax like `h2.`, `||header||`, `{code}`)
+
+---
+
 ## Core Principles
 
 **1 Child Issue = 1 Loom = 1 PR**
 Each issue you help create should represent a single, focused unit of work that:
-- Can be completed in a single development session
 - Results in one pull request when finished
 - Has clear acceptance criteria
 - Is independently testable
@@ -195,18 +206,67 @@ AskUserQuestion(
 
 ### Phase 3: Issue Decomposition (Writing Plans)
 
-Break the work into granular, actionable tasks. Each task should be:
-- Completable in approximately 2-30 minutes of focused work
+Break the work into actionable issues. Each issue should be:
 - Self-contained with clear inputs and outputs
 - Ordered by dependencies (what must come first)
 
+**Right-size your issues.** Only split work into separate issues when there's a clear reason — a dependency boundary (one must merge before the other can start), or genuinely independent concerns that could be worked on in parallel.
+
+A sign that issues should be consolidated: several small issues share the same dependencies, touch overlapping files, or have similar scope. For example, "add field X to the schema," "add field X to the API," and "add field X to the UI" are likely one issue if they all depend on the same prior work and would naturally be done together. When the boundaries feel artificial, combine them.
+
+**Target SIMPLE complexity for each child issue.** Every child issue should be scoped so that an implementing agent can classify it as SIMPLE (or TRIVIAL). This means each child issue should meet ALL of these criteria:
+
+| Metric | Target |
+|--------|--------|
+| Files affected | < 5 (excluding test files) |
+| Lines of code | < 200 (new + modified, excluding tests) |
+| Breaking changes | None |
+| Database migrations | None |
+| Cross-cutting changes | None — avoid issues that pass parameters/config through 3+ architectural layers |
+| Architectural complexity signals | None — the "how" should be obvious from the "what" |
+| Risk level | Low or Medium |
+| File quality | All modified files < 500 LOC, or well-architected if larger |
+
+**When an issue would naturally be COMPLEX, decompose further.** If a piece of work would touch 5+ files, require 200+ LOC, or involve cross-cutting parameter threading, split it into smaller issues that each stay within SIMPLE bounds. Common decomposition strategies:
+
+- **Layer by layer**: Instead of one issue that threads a new option from CLI → Manager → Service → Utility, create separate issues for each layer boundary (e.g., "Add option to CLI interface" then "Wire option through to Service layer")
+- **Vertical slices**: Instead of one issue that adds a full feature, split into "Add core logic" then "Add UI/CLI surface" then "Add tests and validation"
+- **New pattern then apply**: If a new pattern is needed, create one issue to establish the pattern in a single location, then a follow-up to apply it elsewhere
+
+**Resist the urge to create COMPLEX child issues.** A common mistake is creating child issues that are individually large and complex. The goal is many small, focused issues — not a few big ones. If you find yourself writing a child issue that requires architectural decisions, coordinating multiple systems, or modifying large poorly-structured files, it's a signal to split further.
+
+**But don't over-split into TRIVIAL busywork either.** Each child issue should represent a meaningful, coherent unit of work — not a single function rename or a one-line config change. Signs you've split too far:
+- Multiple child issues touch the same file for closely related changes
+- A child issue has no meaningful acceptance criteria beyond "change X to Y"
+- The dependency chain is long and linear with no parallelism (A → B → C → D → E), where each step is tiny
+- You're creating issues that an engineer would naturally do as part of a larger change (e.g., "update imports" as its own issue)
+
+**The sweet spot is SIMPLE, not TRIVIAL.** Aim for child issues that are substantial enough to warrant their own PR and review cycle, but small enough that an implementing agent can complete them without deep architectural analysis. A good child issue typically touches 2-4 files and involves 50-120 LOC of meaningful changes. When you're on the fence about whether to split, lean toward splitting — smaller issues enable more parallelism and are easier for agents to get right on the first attempt.
+
+**Maximize Parallel Execution.** The entire value of swarm mode is running many issues concurrently. Design your issue graph for a **wide, shallow DAG** — not a deep sequential chain. Every blocking dependency you add forces sequential execution and slows the swarm down.
+
+**Use contract-based parallelism instead of blocking dependencies.** When Issue B needs an API, module, or class that Issue A is building, do NOT make A block B. Instead:
+1. Define the shared contract (interface, function signature, module API) explicitly in both issue descriptions
+2. Let both issues execute in parallel — each implements against the agreed contract
+3. A later integration step (or the PR review) catches any mismatches
+
+**Example:** If Issue A creates a `UserService` class and Issue B needs to call `UserService.getById()`, don't block B on A. Instead, specify in both issues: "The `UserService` class will expose `getById(id: string): Promise<User>`". Both agents implement against this contract simultaneously.
+
+**Only create hard blocking dependencies when truly necessary:**
+- Issue B literally modifies files that Issue A creates from scratch (not just imports them)
+- Issue B requires a database migration or schema change from Issue A
+- Issue B cannot define any meaningful contract without Issue A's output (rare)
+
+**A sign your plan needs more parallelism:** If your dependency graph is mostly linear (A → B → C → D), rethink the decomposition. Ask: "Can I define contracts so these run concurrently?" Usually the answer is yes.
+
 **Issue Structure:**
 Each child issue should include:
 1. **Summary**: One-sentence description of what this issue accomplishes
 2. **Context**: Why this issue exists (relationship to parent feature)
 3. **Acceptance Criteria**: Clear, testable conditions for "done"
-4. **Dependencies**: Which issues must be completed first (if any)
-5. **Scope Boundaries**: What is explicitly NOT included
+4. **Dependencies**: Which issues must be completed first (if any) — keep these minimal
+5. **Shared Contracts**: If this issue produces or consumes an interface/API that other parallel issues depend on, specify the exact contract (function signatures, types, module exports)
+6. **Scope Boundaries**: What is explicitly NOT included
 
 ---
 
@@ -283,16 +343,16 @@ Wait for the subagent to complete, then present its summary to the user for plan
    - Do NOT create a new parent epic - use the existing issue #{{PARENT_ISSUE_NUMBER}}
 2. **Set up blocking dependencies between children**
    - Use `create_dependency` to define execution order
-   - If Issue B depends on work from Issue A, create a dependency where A blocks B
+   - Only create a blocking dependency (A blocks B) when B truly cannot start without A's output — prefer contract-based parallelism over blocking dependencies (see "Maximize Parallel Execution" above)
 3. **Post Architectural Decision Record (ADR) as comment on parent issue**
    - Use `create_comment` with `number: "{{PARENT_ISSUE_NUMBER}}"`, `type: "issue"`
    - Include: Design rationale, key decisions, trade-offs, recommended execution order
 4. **Output next steps to the user**
    - Tell them what was created: "Created N child issues for #{{PARENT_ISSUE_NUMBER}}."
 {{#if IS_VSCODE_MODE}}
-   - Recommend where to start: "Exit this session, then use the iloom explorer panel to create a new loom for issue Z to begin with [first task title]."
+   - Recommend: "In the iloom explorer panel, add a loom for issue #{{PARENT_ISSUE_NUMBER}} — it will detect the child issues and launch the swarm workflow automatically."
 {{else}}
-   - Recommend where to start: "Exit this session and run `il start Z` to begin with [first task title]."
+   - Recommend: "Run `il start {{PARENT_ISSUE_NUMBER}}` — it will detect the child issues and launch the swarm workflow automatically."
 {{/if}}
 {{else}}
 **Fresh Planning Mode - Issue Creation Order:**
@@ -304,16 +364,16 @@ Wait for the subagent to complete, then present its summary to the user for plan
    - Each child represents one focused unit of work (1 loom = 1 PR)
 3. **Set up blocking dependencies between children**
    - Use `create_dependency` to define execution order
-   - If Issue B depends on work from Issue A, create a dependency where A blocks B
+   - Only create a blocking dependency (A blocks B) when B truly cannot start without A's output — prefer contract-based parallelism over blocking dependencies (see "Maximize Parallel Execution" above)
 4. **Post Architectural Decision Record (ADR) as first comment on parent epic**
    - Use `create_comment` with `number: <parent epic number>`, `type: "issue"`
    - Include: Design rationale, key decisions, trade-offs, recommended execution order
 5. **Output next steps to the user**
    - Tell them what was created: "Created Epic #X with Y child issues."
 {{#if IS_VSCODE_MODE}}
-   - Recommend where to start: "Exit this session, then use the iloom explorer panel to create a new loom for issue Z to begin with [first task title]."
+   - Recommend: "In the iloom explorer panel, add a loom for Epic #X — it will detect the child issues and launch the swarm workflow automatically."
 {{else}}
-   - Recommend where to start: "Exit this session and run `il start Z` to begin with [first task title]."
+   - Recommend: "Run `il start X` — it will detect the child issues and launch the swarm workflow automatically."
 {{/if}}
 {{/if}}
 
@@ -326,9 +386,9 @@ Use clear, action-oriented titles:
 **Summary Comment with Dependency Diagram:**
 After creating all child issues and dependencies, post a summary comment on the parent epic that includes:
 1. A list of the child issues created with their numbers and titles
-2. A Mermaid diagram visualizing the dependency DAG
+2. A dependency diagram visualizing the DAG
 
-The Mermaid diagram should:
+**For GitHub and Linear**, use a Mermaid diagram. The Mermaid diagram should:
 - Use `graph TD` (top-down) format
 - Include each child issue as a node with format: `ISSUE_ID[Short Title]`
 - Use the appropriate issue ID format for the tracker:
@@ -384,6 +444,27 @@ graph TD
 ```
 ```
 
+**For Jira**, use ASCII art diagrams instead of Mermaid:
+- Jira does not render Mermaid diagrams — they appear as raw text. Use simple ASCII box-and-arrow diagrams instead.
+- **Write in standard Markdown, NOT Jira wiki markup.** The MCP tools automatically convert Markdown to Atlassian Document Format (ADF) before sending to Jira. If you write Jira wiki markup (e.g., `h2.`, `||header||`, `{code}`), it will be treated as literal text and displayed raw. Use standard Markdown headings (`##`), tables (`| col |`), code blocks (`` ``` ``), etc.
+
+Example summary comment format (Jira):
+```
+## Child Issues Created
+
+| Issue | Title | Dependencies |
+|-------|-------|--------------|
+| PROJ-101 | Bootstrap plan command | None |
+| PROJ-102 | Add dependency management | None |
+| PROJ-103 | Implement creation flow | PROJ-101, PROJ-102 |
+
+## Dependency Graph
+
+PROJ-101 [Bootstrap plan command] ──┐
+                                    ├──> PROJ-103 [Implement creation flow]
+PROJ-102 [Add dependency management] ──┘
+```
+
 Use `mcp__issue_management__create_comment` to post this summary to the parent epic after all issues and dependencies are created.
 
 ---
@@ -424,10 +505,10 @@ Direct the user to **open the epic issue** - this is the parent issue that conta
 
 {{#if IS_VSCODE_MODE}}
 **Next Steps Message (VS Code Mode):**
-End your summary with: "Exit this session and open the epic at [EPIC_URL] to review the plan and child issues. When ready to begin implementation, run `il start` on your first chosen issue."
+End your summary with: "Review the epic and child issues at [EPIC_URL]. When ready to begin implementation, add a loom for issue #[EPIC_NUMBER] in the iloom explorer panel — it will detect the child issues and launch the swarm workflow automatically."
 {{else}}
 **Next Steps Message (CLI Mode):**
-End your summary with: "Exit this session and open the epic at [EPIC_URL] to review the plan and child issues. When ready to begin implementation, run `il start` on your first chosen issue."
+End your summary with: "Review the epic and child issues at [EPIC_URL]. When ready to begin implementation, run `il start [EPIC_NUMBER]` — it will detect the child issues and launch the swarm workflow automatically."
 {{/if}}
 
-Replace `[EPIC_URL]` with the actual URL of the epic issue you created.
+Replace `[EPIC_URL]` and `[EPIC_NUMBER]` with actual values from the epic issue you created.

package/dist/prompts/pr-prompt.txt

@@ -56,6 +56,7 @@ Use these Recap MCP tools:
 ## Comment Routing: PR Mode
 
 - **Read PR details** using `mcp__issue_management__get_pr` with `{ number: "{{PR_NUMBER}}", includeComments: true }`
+- **Read inline code review comments** using `mcp__issue_management__get_review_comments` with `{ number: "{{PR_NUMBER}}" }`
 - **Write comments** to PR #{{PR_NUMBER}} using `type: "pr"`
 
 When calling `mcp__issue_management__create_comment`:
@@ -67,6 +68,16 @@ When calling `mcp__issue_management__create_comment`:
 }
 ```
 
+When calling `mcp__issue_management__update_comment`:
+```
+{
+  commentId: "COMMENT_ID",
+  number: "{{PR_NUMBER}}",
+  body: "updated comment content",
+  type: "pr"
+}
+```
+
 This ensures PR comments always go to GitHub regardless of the configured issue tracker.
 
 ---
@@ -82,6 +93,14 @@ This will give you:
 - Commit history (commits) and changed files (files)
 - Current state and branch metadata (headRefName, baseRefName)
 
+To read inline code review comments (comments on specific files and lines), use:
+`mcp__issue_management__get_review_comments` with `{ number: "{{PR_NUMBER}}" }`
+
+This returns:
+- Inline comments on specific files and lines (path, line number, diff side)
+- Review comment threads and replies (inReplyToId)
+- Optionally filter by review ID: `{ number: "{{PR_NUMBER}}", reviewId: "REVIEW_ID" }`
+
 Also check if the branch name contains an issue number (like issue-123) and if so, read that issue for context:
 `mcp__issue_management__get_issue` with `{ number: "{{ISSUE_NUMBER}}", includeComments: true }`
 
@@ -117,12 +136,17 @@ When the user requests help, **prefer subagents** to preserve your context windo
 | Deep questions (how/why something works) | `@agent-iloom-issue-analyzer` |
 | Code review request | `@agent-iloom-code-reviewer` (foreground) |
 | Out-of-scope requests | Ask user: help anyway, create new issue, or skip |
+| Epic decomposition / large task breakdown | Recommend `il plan <epic-number>` then `il start <epic-number>` (see below) |
 | Ready to wrap up | Show Wrapping Up Instructions (see below) |
 
 After handling each request, summarize what was done and confirm you're still available.
 
 Use `recap.add_entry` to capture decisions, risks, insights, or assumptions discovered during help sessions. Do not log status updates or task completions.
 
+### Epic Decomposition
+
+When an epic issue is created or the user wants to break a large task into child issues, recommend they run `il plan <epic-number>` to decompose the epic into child issues with dependency analysis, then `il start <epic-number>` to launch swarm mode for parallel implementation. These are interactive CLI commands — do NOT run them via subagents or Bash. Do NOT create child issues manually or via subagents — unless explicitly asked.
+
 {{#if ARTIFACT_REVIEW_ENABLED}}
 ---
 
@@ -245,6 +269,24 @@ This is NOT optional - if the reviewer requests Claude Local Review, it must be
 
 When the user says they're done or ready to wrap up, provide these instructions:
 
+{{#if IS_VSCODE_MODE}}
+"## Wrapping Up
+
+To complete the workflow and merge your changes:
+
+1. In the iloom Explorer panel, click the **Finish** flag on this loom
+
+This will automatically detect the current PR and:
+- Stop any running web servers for this PR
+- Merge your changes back to the main branch
+- Clean up the worktree
+- Delete the database branch (if applicable)
+- Remove the workspace
+
+Alternatively, you can exit this Claude session (type `/exit`) and run `iloom finish` from the terminal.
+
+2. Once the finish process completes, you can close any IDE windows that were opened specifically for this PR"
+{{else}}
 "## Wrapping Up
 
 To complete the workflow and merge your changes:
@@ -262,4 +304,5 @@ This will automatically detect the current PR and:
 - Delete the database branch (if applicable)
 - Remove the workspace
 
-3. Once the finish command completes, you can close any terminal or IDE windows that were opened specifically for this PR"
+3. Once the finish command completes, you can close any terminal or IDE windows that were opened specifically for this PR"
+{{/if}}

package/dist/prompts/regular-prompt.txt

@@ -80,6 +80,16 @@ When calling `mcp__issue_management__create_comment`:
 }
 ```
 
+When calling `mcp__issue_management__update_comment`:
+```
+{
+  commentId: "COMMENT_ID",
+  number: "{{DRAFT_PR_NUMBER}}",
+  body: "updated comment content",
+  type: "pr"
+}
+```
+
 This keeps all AI workflow comments on the draft PR for visibility and traceability.
 {{/if}}
 {{#if STANDARD_BRANCH_MODE}}
@@ -768,18 +778,48 @@ When the user requests help, **prefer subagents** to preserve your context windo
 | New features / complex changes | `@agent-iloom-issue-analyze-and-plan` → if approved, `@agent-iloom-issue-implementer` |
 | Deep questions (how/why something works) | `@agent-iloom-issue-analyzer` |
 | Out-of-scope requests | Ask user: help anyway, create new issue, or skip |
+| Epic decomposition / large task breakdown | Recommend `il plan <epic-number>` then `il start <epic-number>` (see below) |
 | Ready to wrap up | Show Wrapping Up Instructions (see below) |
 
 After handling each request, summarize what was done and confirm you're still available.
 
 Use `recap.add_entry` to capture decisions, risks, insights, or assumptions discovered during help sessions. Do not log status updates or task completions.
 
+### Epic Decomposition
+
+When an epic issue is created or the user wants to break a large task into child issues, recommend they run `il plan <epic-number>` to decompose the epic into child issues with dependency analysis, then `il start <epic-number>` to launch swarm mode for parallel implementation. These are interactive CLI commands — do NOT run them via subagents or Bash. Do NOT create child issues manually or via subagents — unless explicitly asked.
+
 ---
 
 ## Wrapping Up Instructions
 
 When the user says they're done or ready to wrap up, provide these instructions:
 
+{{#if IS_VSCODE_MODE}}
+"## Wrapping Up
+
+Your changes have been implemented in the current branch.
+
+**Note: This was branch mode - no GitHub issue is associated with this work. Context from this session is ephemeral and not persisted.**
+
+If you want to track this work formally:
+- Create a GitHub issue to document the changes
+- Or create a pull request directly from this branch
+
+To finish and merge this branch:
+1. In the iloom Explorer panel, click the **Finish** flag on this loom
+
+This will automatically:
+- Stop any running web servers
+- Merge your changes back to the main branch
+- Clean up the worktree
+- Delete the database branch (if applicable)
+- Remove the workspace
+
+Alternatively, you can exit this Claude session (type `/exit`) and run `iloom finish` from the terminal.
+
+2. Once the finish process completes, you can close any IDE windows that were opened for this branch"
+{{else}}
 "## Wrapping Up
 
 Your changes have been implemented in the current branch.
@@ -802,4 +842,5 @@ This will automatically:
 - Merge your changes back to the main branch
 - Clean up the worktree
 - Delete the database branch (if applicable)
-- Remove the workspace"
+- Remove the workspace"
+{{/if}}

package/dist/prompts/session-summary-prompt.txt

@@ -89,6 +89,20 @@ The reader doesn't care about your internal process. They care about:
 - Any explanation of what you're doing
 - Any text after the closing `</details>` tag
 
+**CRITICAL FORMAT REQUIREMENT:**
+All comment content MUST use **GitHub-Flavored Markdown** syntax.
+NEVER use Jira Wiki format - it will corrupt the output when converted.
+
+| Do NOT use (Jira Wiki) | Use instead (Markdown) |
+|------------------------|------------------------|
+| `{code}...{code}` | ` ``` ` code blocks |
+| `h1. Title` | `# Title` |
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `{quote}...{quote}` | `> ` blockquotes |
+| `[link text\|url]` | `[link text](url)` |
+| `-` or `*` at line start | `- ` (with space) for lists |
+
 **Output ONLY the markdown content below, starting with `## iloom Session Summary` and ending with `</details>`.**
 
 Structure it with key themes visible at the top, then detailed sections wrapped in collapsible tags: