@iloom/cli 0.9.2 → 0.10.1

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,79 @@ 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
+**Step 1: Identify work units, define shared contracts, and design the DAG.**
+
+Start by listing the work units at a high level (title + one sentence each). Then, before writing full issue descriptions, design the dependency graph:
+
+1. **Assume all issues run in parallel.** This is your starting point — not something you optimize toward later.
+2. **Define shared contracts to keep them parallel.** When Issue B needs an API, module, or type that Issue A is building, do NOT make A block B. Instead, define the shared contract (interface, function signature, module API) explicitly, and specify it in both issue descriptions. Both agents implement against the agreed contract simultaneously — a later integration step catches any mismatches.
+3. **Only add blocking dependencies you truly cannot eliminate with a contract.** Hard blockers are rare — they apply when Issue B literally modifies files that Issue A creates from scratch (not just imports them), or when Issue B requires a database migration from Issue A.
+4. **Check the shape.** Ask: "What is the widest, shallowest DAG I can create?" If the graph is mostly linear (A → B → C → D), rethink the decomposition. The shape of the graph matters as much as the content of individual issues, because a narrow graph kills swarm throughput.
+
+**Example:** If Issue A creates a `UserService` class and Issue B needs to call `UserService.getById()`, don't block B on A. Instead, specify the contract in both issues: "`UserService` exposes a `getById(id)` method that returns a user object." Both agents implement against this contract simultaneously.
+
+**Compilation errors are expected and OK.** When issues run in parallel against shared contracts, individual branches will have build errors — Issue B imports a module that Issue A hasn't merged yet. This is normal. The errors resolve when branches merge into the epic branch. Agents should not block on or try to fix compilation errors caused by missing contract implementations from parallel issues.
+
+**Step 2: Write full issue descriptions.** Now flesh out each node in your DAG. Each issue should be:
 - Self-contained with clear inputs and outputs
-- Ordered by dependencies (what must come first)
+- Connected to other issues via shared contracts (already defined in Step 1) rather than blocking dependencies
+
+**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 — no deep architectural decisions required to implement it |
+| 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.
+
+**CRITICAL: Issue bodies must NOT contain implementation details.** The implementing agent will discover the *how* through its own codebase research. Baking implementation instructions into the issue body causes agents to skip their research phase and treat your instructions as ground truth, which produces brittle implementations based on potentially stale assumptions.
+
+Implementation details include:
+- **Code snippets or pseudocode** — exact TypeScript interfaces, function bodies, logic sequences
+- **File paths** — `src/types/telemetry.ts`, `src/commands/plan.ts`, etc.
+- **Step-by-step implementation instructions** — "Add X to file Y, then call Z"
+- **Pre-written content** — exact documentation text, config blocks, or error messages to paste in
+- **Internal behavior descriptions** — conditional logic, specific APIs to call, error handling patterns
+
+A contract describes an *interface boundary* (what a function accepts and returns). Implementation detail describes *how* something works internally. Contracts belong in the issue body. Implementation detail does NOT.
+
+**The test:** For every sentence in the issue body, ask: "Does this tell the implementing agent *what* to build, or *how* to build it?" If it's how — remove it.
 
 **Issue Structure:**
-Each child issue should include:
+Each child issue should include ONLY these sections:
 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
+3. **Acceptance Criteria**: Clear, testable, outcome-focused conditions for "done" — describe the desired result, not the implementation mechanism (e.g., "auto-swarm pipeline events are observable" not "tracking calls fire at pipeline start and end")
+4. **Shared Contracts**: Specify the exact contracts defined in Step 1 that this issue produces or consumes (function signatures, types, module exports). A contract is an interface boundary — what one issue exposes for another to consume. Example: `PlanCommand.execute()` gains an optional `autoSwarm?: boolean` 7th parameter. NOT an implementation: do not describe what happens internally when `autoSwarm` is true — that is implementation detail, not a contract.
+5. **Hard Blocking Dependencies** *(minimize these)*: Which issues must be completed first, if any — each one should have been validated in Step 1 as not replaceable by a contract
+6. **Scope Boundaries**: What is explicitly NOT included
+
+Do NOT add "Implementation Details", "Technical Approach", or similar sections — these violate the rule above.
 
 ---
 
@@ -232,6 +304,19 @@ At the end of the planning session, you have MCP tools to create issues:
 - `mcp__issue_management__remove_dependency`: Remove a dependency between issues
   - Parameters: `blockingIssue`, `blockedIssue`
 
+{{#if AUTO_SWARM_MODE}}
+**Harness Signal Tool:**
+- `mcp__harness__signal`: Signal the auto-swarm harness when planning is complete
+  - Call this after all child issues and dependencies have been created
+  - Parameters: `type` ("done"), `data` (`{ "epicIssueNumber": "<parent issue number>", "childIssues": [<list of child issue numbers>] }`)
+{{/if}}
+
+**Validation Gate — Check Before Presenting Your Plan:**
+Before presenting the plan to the user, audit it against these questions:
+1. **For each blocking dependency:** "Can I replace this with a shared contract so both issues run in parallel?" If yes, rewrite the issues with an explicit contract and remove the dependency.
+2. **DAG shape check:** Is the graph wide and shallow, or narrow and linear? If your longest chain is more than 2 deep, re-examine whether intermediate dependencies are truly hard blockers.
+3. **Contract completeness:** Does every issue that produces or consumes a shared API specify the exact contract (function signatures, types, module exports) in its description?
+
 **Before Creating Issues:**
 1. Summarize the proposed issues and their relationships
 2. Ask for explicit confirmation: "Ready to create these issues?"
@@ -283,16 +368,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 +389,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 +411,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 +469,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.
 
 ---
@@ -395,6 +501,7 @@ Use `mcp__issue_management__create_comment` to post this summary to the parent e
 - Create issues without user confirmation
 - Over-engineer the decomposition (keep it pragmatic)
 - Assume requirements that weren't explicitly stated
+- Include implementation details in issue bodies (code snippets, file paths, step-by-step instructions, pre-written content)
 
 **Do:**
 - Use the conversation to refine understanding iteratively
@@ -420,14 +527,28 @@ Use `mcp__issue_management__create_comment` to post this summary to the parent e
 
 After creating issues successfully, you MUST end with a clear next steps message.
 
+{{#if AUTO_SWARM_MODE}}
+## Auto-Swarm Completion
+
+After creating all child issues and setting up dependencies:
+
+1. **Signal the harness** by calling the `mcp__harness__signal` tool:
+   ```json
+   { "type": "done", "data": { "epicIssueNumber": "{{PARENT_ISSUE_NUMBER}}", "childIssues": [list of child issue numbers created] } }
+   ```
+2. **Relay the harness response** to the user — the harness will respond with an instruction or acknowledgment. Display the content of the response to the user.
+3. **Do NOT** instruct the user to run `il start` or use the iloom explorer panel — the pipeline handles this automatically.
+
+{{else}}
 Direct the user to **open the epic issue** - this is the parent issue that contains all the child issues you just created. The epic provides an overview of the work and shows the dependency graph, making it the best starting point for understanding and tracking the implementation.
 
 {{#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.
+{{/if}}

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: