@gitkraken/compose-tools 0.1.0

package/dist/tasks/compose-group/prompt.js

@@ -0,0 +1,162 @@
+import{groupingResultSchema as e}from"../group/schema.js";import{z as t}from"zod";const n=JSON.stringify(t.toJSONSchema(e),null,2),r=`
+In addition to the \`branches\` field, include an \`analysis\` field at the top level:
+
+\`\`\`json
+{
+  "analysis": {
+    "concerns": ["description of theme 1", "description of theme 2"],
+    "key_dependencies": ["theme 1 defines types that theme 2 imports"]
+  },
+  "branches": [ ... ]
+}
+\`\`\`
+`,i=`5. Write a commit message for each commit:
+   - First line: concise summary, 50 chars max, third-person singular present tense ("Fixes", "Adds", "Improves")
+   - Then a blank line followed by details focusing on "why" not "what"
+   - Informal yet professional tone`;function a(e,t=`branches`,n,r,i){return i?t===`commits`?u(e,n):d(e,n):t===`commits`?o(e,n,r):s(e,n,r)}function o(e,t,a){let o=e?.promptFragment?`5. Write a commit message for each commit following the repository's conventions (see below).
+6. Write a detailed explanation for each commit as if explaining to a reviewer.
+
+${e.promptFragment}`:`${i}
+6. Write a detailed explanation for each commit as if explaining to a reviewer`,s=l(t?.commitGranularity);return`You are an advanced AI programming assistant tasked with analyzing and organizing code changes into commits.
+
+${a?`## Step 1: Analysis`:`## Step 1: Internal Analysis`}
+
+Before grouping, analyze the changes to understand:
+- **Concerns** — what distinct themes, features, or purposes exist across the hunks
+- **Dependencies** — which hunks provide things (define functions, types, files) that other hunks consume (import, call, reference)
+- **Ordering constraints** — if hunk A defines something hunk B uses, they should be in the same commit or A's commit should come before B's
+
+${a?"Output this analysis as a JSON field named `analysis` alongside your `branches` field. The `analysis` field should contain:\n- `concerns`: array of strings, each describing a distinct theme or feature in the changes\n- `key_dependencies`: array of strings, each describing an ordering dependency between concerns":`Do NOT output this analysis. Use it internally to inform your grouping decisions.`}
+
+## Step 2: Group hunks into commits
+
+1. Group hunks into logical units that make sense together and can be applied atomically
+2. Use each hunk only once. Ensure all hunks are assigned to exactly one commit
+3. Ensure each commit is self-contained and atomic
+4. Each commit must have a unique ID (e.g., "commit-1", "commit-2")
+5. Every commit must contain at least one hunk. Do not produce empty commits — if you want to split a theme across multiple commits, each resulting commit needs its own hunks
+${o}
+${s}
+
+## Required Output Format
+
+Output your organization as JSON inside a <output> tag matching this schema:
+
+\`\`\`json
+${n}
+\`\`\`
+${a?r:``}
+Wrap all commits in a single branch object with id "default", name "", title "", and description "".
+
+Remember:
+- Every hunk must be assigned to exactly one commit
+- Every commit must contain at least one hunk (no empty commits)
+- Use exactly one branch with id "default", name "", title "", and description ""
+- Return only the <output> tag and no other text.`}function s(e,t,a){let o=e?.promptFragment?`5. Write a commit message for each commit following the repository's conventions (see below).
+6. Write a detailed explanation for each commit as if explaining to a reviewer.
+
+${e.promptFragment}`:`${i}
+6. Write a detailed explanation for each commit as if explaining to a reviewer`,s=c(t?.branchSplitting,e),u=l(t?.commitGranularity);return`You are an advanced AI programming assistant tasked with analyzing and organizing code changes into commits and branches.
+
+${a?`## Step 1: Analysis`:`## Step 1: Internal Analysis`}
+
+Before grouping, analyze the changes to understand:
+- **Concerns** — what distinct themes, features, or purposes exist across the hunks
+- **Dependencies** — which hunks provide things (define functions, types, files) that other hunks consume (import, call, reference)
+- **Ordering constraints** — if hunk A defines something hunk B uses, they should be in the same commit or A's commit should come before B's
+- **Merge-order preference** — even if two concerns compile independently, would merging one without the other be confusing or incomplete?
+
+${a?"Output this analysis as a JSON field named `analysis` alongside your `branches` field. The `analysis` field should contain:\n- `concerns`: array of strings, each describing a distinct theme or feature in the changes\n- `key_dependencies`: array of strings, each describing an ordering dependency between concerns":`Do NOT output this analysis. Use it internally to inform your grouping decisions.`}
+
+## Step 2: Organize hunks into commits and branches
+
+Your job has two levels:
+
+**Level 1: Commits** — group hunks into logical, atomic commits.
+**Level 2: Branches** — group commits into branches, where each branch is a cohesive unit of work suitable for one pull request.
+
+### Commit guidelines
+
+1. Group hunks into logical units that make sense together and can be applied atomically
+2. Use each hunk only once. Ensure all hunks are assigned to exactly one commit
+3. Ensure each commit is self-contained and atomic
+4. Each commit must have a unique ID (e.g., "commit-1", "commit-2")
+5. Every commit must contain at least one hunk. Do not produce empty commits — if you want to split a theme across multiple commits, each resulting commit needs its own hunks
+${o}
+${u}
+
+### Branch guidelines
+
+${s}
+
+## Required Output Format
+
+Output your organization as JSON inside a <output> tag matching this schema:
+
+\`\`\`json
+${n}
+\`\`\`
+${a?r:``}
+Remember:
+- Every hunk must be assigned to exactly one commit in exactly one branch
+- Every commit must contain at least one hunk (no empty commits)
+- Return only the <output> tag and no other text.`}function c(e,t){let n=`Each branch must have a descriptive name, a short PR-style title (under 72 characters, imperative mood), and at least one commit.`,r=`- Each commit belongs to exactly one branch.
+${t?.promptFragment?`- ${n} Follow the repository's branch naming conventions (see above).`:`- ${n}`}
+- Changes addressing the same pattern across different files belong in ONE branch.`,i=`- Consider merge-order preference, not just code dependencies. Even if two concerns compile independently, they may need to be in the same branch if merging one without the other would be confusing or incomplete.`;return e===`conservative`?`${r}\n- Default to a single branch. Only create multiple branches when concerns are completely unrelated.\n${i}\n- When in doubt, use fewer branches.`:e===`aggressive`?`${r}\n- Create separate branches for each distinct concern.\n${i}\n- Prefer more branches over fewer.`:`${r}\n- Create separate branches when concerns are genuinely independent — meaning a reviewer would gain nothing from seeing them together.\n- Keep changes in the same branch when they form a coherent story.\n${i}\n- When in doubt: "Would a reviewer want to see these together?"`}function l(e){return e===`consolidated`?`
+Prefer fewer, larger commits. Combine related changes into a single commit when they serve the same purpose.`:e===`granular`?`
+Prefer more, smaller commits. Each distinct change should be its own commit.`:``}function u(e,t){return`Organize code hunks into clean, atomic commits.
+
+## Rules
+
+1. Group related hunks by purpose. All hunks of a renamed file must share a commit.
+2. Every hunk index (0 to N-1) in exactly one commit — no gaps, no duplicates.
+3. Each commit needs a unique ID (e.g. "commit-1", "commit-2").
+4. Every commit must have at least one hunk. No empty commits.
+5. ${e?.promptFragment?`Write commit messages following the repository's conventions (see below). Write a one-sentence explanation per commit.
+
+${e.promptFragment}`:`Write commit messages: first line under 50 chars, imperative mood ("Add", "Fix", "Update"). Write a one-sentence explanation per commit.`}
+${l(t?.commitGranularity)}
+
+## Output
+
+JSON inside <output> tags. Use one branch with id "default", name "", title "", description "".
+
+\`\`\`
+{"branches":[{"id":"default","name":"","title":"","description":"","commits":[{"id":"commit-1","message":"Add feature X","explanation":"Brief reason.","hunks":[0,1,2]}]}]}
+\`\`\`
+
+CRITICAL: Every hunk index must appear exactly once across all commits. Every commit must contain at least one hunk. Missing hunks, duplicate hunks, or empty commits will fail validation. Return only the <output> tag.`}function d(e,t){let n=e?.promptFragment?`Write commit messages following the repository's conventions (see below). Write a one-sentence explanation per commit.
+
+${e.promptFragment}`:`Write commit messages: first line under 50 chars, third-person singular present tense ("Fixes", "Adds", "Improves"). Write a one-sentence explanation per commit.`,r=c(t?.branchSplitting,e);return`Organize code hunks into clean, atomic commits and branches.
+
+## Commit rules
+
+1. Group related hunks by purpose. All hunks of a renamed file must share a commit.
+2. Every hunk index (0 to N-1) in exactly one commit — no gaps, no duplicates.
+3. Each commit needs a unique ID (e.g., "commit-1", "commit-2").
+4. Every commit must have at least one hunk. No empty commits.
+5. ${n}
+${l(t?.commitGranularity)}
+
+## Branch guidelines
+
+${r}
+
+## Output
+
+JSON inside <output> tags. Each branch needs a unique ID and non-empty name.
+
+\`\`\`
+{"branches":[{"id":"branch-1","name":"feat/example","title":"Add example","description":"Brief.","commits":[{"id":"commit-1","message":"Add X","explanation":"Reason.","hunks":[0,1]}]}]}
+\`\`\`
+
+CRITICAL: Every hunk index must appear exactly once across all commits in all branches. Every commit must contain at least one hunk. Missing hunks, duplicate hunks, or empty commits will fail validation. Each branch must have a unique ID and non-empty name.
+
+Return only the <output> tag and no other text.`}function f(e){let{hunks:t,commitMessages:n,commitOrder:r,branchName:i,baseBranch:a,issueUrl:o,pullRequestUrl:s,instructions:c,condensed:l}=e,u=JSON.stringify(l?t.map(e=>({index:e.index,fileName:e.fileName,hunkHeader:e.hunkHeader,additions:e.additions,deletions:e.deletions,...e.isBinary?{isBinary:!0}:{},...e.isRename?{isRename:!0}:{},...e.originalFileName?{originalFileName:e.originalFileName}:{}})):t.map(e=>({index:e.index,fileName:e.fileName,hunkHeader:e.hunkHeader,content:e.content,...e.isBinary?{isBinary:!0}:{},...e.isRename?{isRename:!0}:{},...e.originalFileName?{originalFileName:e.originalFileName}:{}}))),d=`Organize these ${t.length} code hunks (indices 0 to ${t.length-1}) into commits. Every index must appear exactly once.
+
+<hunks>
+${u}
+</hunks>`,f=[];return i&&f.push(`Branch: ${i}`),a&&f.push(`Base: ${a}`),o&&f.push(`Issue: ${o}`),s&&f.push(`PR: ${s}`),f.length>0&&(d+=`\n\nContext:\n${f.join(`
+`)}`),n?.length&&(d+=`\n\nOriginal commit messages (match their style):\n<commit_messages>\n${JSON.stringify(n)}\n</commit_messages>`),r?.length&&(d+=`\n\nOriginal commit order:\n${JSON.stringify(r)}`),c&&(d+=`\n\nAdditional instructions:\n${c}`),d+=`
+
+Return only the <output> tag and no other text.`,d}export{a as buildComposeGroupSystemPrompt,f as buildComposeGroupUserPrompt};

package/dist/tasks/compose-group/types.d.ts

@@ -0,0 +1,62 @@
+import { ProgressEvent, TokenUsage } from "../../ai/types.js";
+import { ComposeHunk, PromptOverride } from "../types.js";
+import { ConventionDescriptor } from "../../git/utils/conventions.js";
+import { OnAfterModelCall, OnBeforeModelCall, OnBeforePrompt } from "../ai-loop.js";
+import { GroupingResult, GroupingStrategy } from "../group/types.js";
+import { ComposeSession } from "../session.js";
+import { AiModelPort } from "@gitkraken/shared-tools";
+
+//#region src/tasks/compose-group/types.d.ts
+/**
+ * Input for the compose-group task (balanced mode).
+ *
+ * Combines the context from analyze (branch/issue/commit order) with the
+ * grouping parameters from group, allowing the AI to reason about concerns
+ * and dependencies internally before producing a GroupingResult.
+ */
+interface ComposeGroupInput {
+  hunks: ComposeHunk[];
+  commitMessages?: string[];
+  /** Commit SHAs in their original order — gives the AI chronological context. */
+  commitOrder?: string[];
+  branchName?: string;
+  baseBranch?: string;
+  issueUrl?: string;
+  pullRequestUrl?: string;
+  instructions?: string;
+  conventions?: ConventionDescriptor;
+  /** "commits" = flat commit list. "branches" = AI decides branches (default). */
+  mode?: 'commits' | 'branches';
+  /** Controls how aggressively the AI splits branches and commits. */
+  strategy?: GroupingStrategy;
+  /** Branch names that already exist — used to detect collisions during validation. */
+  existingBranchNames?: Set<string>;
+  /** When true, the AI outputs its analysis (concerns, dependencies) alongside grouping. */
+  includeAnalysis?: boolean;
+  /** When true, uses a minimal prompt without analysis instructions. For fast single-call compose. */
+  lightweight?: boolean;
+  /** When true, sends only hunk metadata (fileName, hunkHeader, counts) without diff content. */
+  condensed?: boolean;
+  model: AiModelPort;
+  /** Prior session to resume from. When `completedSteps.composeGroup` is present, skip the AI call. */
+  session?: ComposeSession;
+  maxRetries?: number;
+  onProgress?: (event: ProgressEvent) => void;
+  signal?: AbortSignal;
+  onBeforeModelCall?: OnBeforeModelCall;
+  onAfterModelCall?: OnAfterModelCall;
+  onBeforePrompt?: OnBeforePrompt;
+  /** Optional prompt override. When set, replaces or decorates the built-in prompts. */
+  promptOverride?: PromptOverride;
+}
+/** Same output type as the standard group task. */
+type ComposeGroupOutput = {
+  result: GroupingResult;
+  session: ComposeSession;
+  usage?: TokenUsage;
+  attempts: number;
+  durationMs: number;
+  callIds: string[];
+};
+//#endregion
+export { ComposeGroupInput, ComposeGroupOutput };

package/dist/tasks/compose-group/types.js

@@ -0,0 +1 @@
+export{};

package/dist/tasks/group/group.d.ts

@@ -0,0 +1,6 @@
+import { GroupInput, GroupOutput } from "./types.js";
+
+//#region src/tasks/group/group.d.ts
+declare function group(input: GroupInput): Promise<GroupOutput>;
+//#endregion
+export { group };

package/dist/tasks/group/group.js

@@ -0,0 +1 @@
+import{TaskInputError as e}from"../../errors/task.js";import{runAiLoop as t}from"../ai-loop.js";import{applyUserPromptOverride as n}from"../types.js";import{validateGroupResponse as r}from"./validator.js";import{buildGroupContinuationPrompt as i,buildGroupSystemPrompt as a,buildGroupUserPrompt as o}from"./prompt.js";async function s(s){let c=s.hunks,l=s.mode??`branches`;if((!c||c.length===0)&&!s.session)throw new e(`No hunks provided: supply 'hunks' or run analyze() first with a session`);if(s.session?.completedSteps.group)return{result:s.session.completedSteps.group,session:s.session,attempts:0,durationMs:0,callIds:[]};let u=n(s.session?i(s,l):o({hunks:c,commitMessages:s.commitMessages,instructions:s.instructions,mode:l}),s.promptOverride),d=c?.length??s.session?.completedSteps.analyze?.hunkAnnotations.length??0;if(d===0)throw new e(`Cannot validate grouping: no hunk count available from input or session`);let f=await t({model:s.model,systemPrompt:s.session?void 0:s.promptOverride?.system??a(s.conventions,l,s.strategy),userPrompt:u,session:s.session,maxRetries:s.maxRetries,onProgress:s.onProgress,signal:s.signal,onBeforeModelCall:s.onBeforeModelCall,onAfterModelCall:s.onAfterModelCall,onBeforePrompt:s.onBeforePrompt,validate:e=>r(e,d,l,s.existingBranchNames),taskName:`group`}),p=s.session?.completedSteps??{},m={...f.session,completedSteps:{...p,group:f.result}};return{result:f.result,session:m,usage:f.usage,attempts:f.attempts,durationMs:f.durationMs,callIds:f.callIds}}export{s as group};

package/dist/tasks/group/prompt.d.ts

@@ -0,0 +1,15 @@
+import { ComposeHunk } from "../types.js";
+import { ConventionDescriptor } from "../../git/utils/conventions.js";
+import { GroupInput, GroupingStrategy } from "./types.js";
+
+//#region src/tasks/group/prompt.d.ts
+declare function buildGroupSystemPrompt(conventions?: ConventionDescriptor, mode?: 'commits' | 'branches', strategy?: GroupingStrategy): string;
+declare function buildGroupUserPrompt(params: {
+  hunks: ComposeHunk[];
+  commitMessages?: string[];
+  instructions?: string;
+  mode?: 'commits' | 'branches';
+}): string;
+declare function buildGroupContinuationPrompt(input: GroupInput, mode: 'commits' | 'branches'): string;
+//#endregion
+export { buildGroupContinuationPrompt, buildGroupSystemPrompt, buildGroupUserPrompt };

package/dist/tasks/group/prompt.js

@@ -0,0 +1,158 @@
+import{groupingResultSchema as e}from"./schema.js";import{z as t}from"zod";const n=JSON.stringify(t.toJSONSchema(e),null,2),r=`5. Write a commit message for each commit:
+   - First line: concise summary, 50 chars max, third-person singular present tense ("Fixes", "Adds", "Improves")
+   - Then a blank line followed by details focusing on "why" not "what"
+   - Informal yet professional tone`,i=`Each branch must have a descriptive name, a short PR-style title (under 72 characters, imperative mood), and at least one commit.`;function a(e,t=`branches`,n){return t===`commits`?o(e,n):s(e,n)}function o(e,t){return`You are an advanced AI programming assistant tasked with organizing code changes into commits. You will be working with individual code hunks.
+
+## Commit guidelines
+
+1. Group hunks into logical units that make sense together and can be applied atomically
+2. Use each hunk only once. Ensure all hunks are assigned to exactly one commit
+3. Ensure each commit is self-contained and atomic
+4. Each commit must have a unique ID (e.g., "commit-1", "commit-2")
+5. Every commit must contain at least one hunk. Do not produce empty commits
+${e?.promptFragment?`5. Write a commit message for each commit following the repository's conventions (see below).
+6. Write a detailed explanation for each commit as if explaining to a reviewer.
+
+${e.promptFragment}`:`${r}
+6. Write a detailed explanation for each commit as if explaining to a reviewer`}
+${l(t?.commitGranularity)}
+
+## Required Output Format
+
+Output your organization as JSON inside a <output> tag matching this schema:
+
+\`\`\`json
+${n}
+\`\`\`
+
+Wrap all commits in a single branch object with id "default", name "", title "", and description "".
+
+Remember:
+- Every hunk must be assigned to exactly one commit
+- Every commit must contain at least one hunk (no empty commits)
+- Use exactly one branch with id "default", name "", title "", and description ""
+- Return only the <output> tag and no other text.`}function s(e,t){let i=e?.promptFragment?`5. Write a commit message for each commit following the repository's conventions (see below).
+6. Write a detailed explanation for each commit as if explaining to a reviewer.
+
+${e.promptFragment}`:`${r}
+6. Write a detailed explanation for each commit as if explaining to a reviewer`,a=c(t?.branchSplitting,e);return`You are an advanced AI programming assistant tasked with organizing code changes into commits and branches. You will be working with individual code hunks.
+
+Your job has two levels:
+
+**Level 1: Commits** — group hunks into logical, atomic commits.
+**Level 2: Branches** — group commits into branches, where each branch is a cohesive unit of work suitable for one pull request.
+
+## Commit guidelines
+
+1. Group hunks into logical units that make sense together and can be applied atomically
+2. Use each hunk only once. Ensure all hunks are assigned to exactly one commit
+3. Ensure each commit is self-contained and atomic
+4. Each commit must have a unique ID (e.g., "commit-1", "commit-2")
+5. Every commit must contain at least one hunk. Do not produce empty commits
+${i}
+${l(t?.commitGranularity)}
+
+## Branch guidelines
+
+${a}
+
+## Required Output Format
+
+Output your organization as JSON inside a <output> tag matching this schema:
+
+\`\`\`json
+${n}
+\`\`\`
+
+Remember:
+- Every hunk must be assigned to exactly one commit in exactly one branch
+- Every commit must contain at least one hunk (no empty commits)
+- Return only the <output> tag and no other text.`}function c(e,t){let n=`- Each commit belongs to exactly one branch.
+${t?.promptFragment?`- ${i} Follow the repository's branch naming conventions (see above).`:`- ${i}`}
+- Changes addressing the same pattern across different files belong in ONE branch. For example, applying the same bug fix to multiple functions, or updating similar config across modules — these are the same concern even if the files are different.`,r=`- Consider merge-order preference, not just code dependencies. Even if two concerns compile independently, they may need to be in the same branch or stacked branches if merging one without the other would be confusing or incomplete (e.g., documentation that describes utilities introduced in other commits should be in the same branch or stacked after those utilities).`;return e===`conservative`?`${n}
+- Default to a single branch. Only create multiple branches when concerns are completely unrelated — different domains, different purposes, and no merge-order preference between them.
+${r}
+- When in doubt, use fewer branches.`:e===`aggressive`?`${n}
+- Create separate branches for each distinct concern. If changes touch different features, different subsystems, or solve different problems, they should be in separate branches even if they are in a related domain.
+${r}
+- Prefer more branches over fewer. Each PR should be as focused as possible.`:`${n}
+- Create separate branches when concerns are genuinely independent — meaning they address different problems or features, and a reviewer would gain nothing from seeing them together in one PR. Two commits that each add a separate utility function unrelated to each other are good candidates for independent branches.
+- Keep changes in the same branch when they form a coherent story that benefits from being reviewed together, even if they could technically stand alone.
+${r}
+- When in doubt, consider: "Would a reviewer want to see these changes together, or would separating them make review easier?" If separating helps, split.`}function l(e){return e===`consolidated`?`
+Prefer fewer, larger commits. Combine related changes into a single commit when they serve the same purpose. A commit can touch many files if they are all part of the same logical change.`:e===`granular`?`
+Prefer more, smaller commits. Each distinct change should be its own commit, even if multiple changes serve a similar purpose. Aim for commits that touch as few files as possible.`:``}function u(e){let{hunks:t,commitMessages:n,instructions:r,mode:i=`branches`}=e,a=JSON.stringify(t.map(e=>({index:e.index,fileName:e.fileName,hunkHeader:e.hunkHeader,content:e.content,...e.isBinary?{isBinary:!0}:{},...e.isRename?{isRename:!0}:{},...e.originalFileName?{originalFileName:e.originalFileName}:{}}))),o=`${i===`commits`?`Examine the following ${t.length} code hunks (indices 0 to ${t.length-1}) and organize them into commits. Every index must appear exactly once.`:`Examine the following ${t.length} code hunks (indices 0 to ${t.length-1}) and organize them into commits and branches. Every index must appear exactly once.`}
+
+<hunks>
+${a}
+</hunks>`;return n?.length&&(o+=`
+
+The following commit messages are from the original commits. Use them to understand intent and match their style:
+
+<commit_messages>
+${JSON.stringify(n)}
+</commit_messages>`),r&&(o+=`
+
+Carefully follow these additional instructions, but do not deviate from the output structure:
+${r}`),o+=`\n\n${i===`commits`?`Now organize the hunks into commits.`:`Now organize the hunks into commits and branches.`} Return only the <output> tag and no other text.`,o}function d(e,t){let n;return n=t===`commits`?`Based on your analysis of the changes, now organize the hunks into commits. Each hunk must be assigned to exactly one commit.`:f(e.strategy),e.conventions?.promptFragment&&(n+=`\n\n${e.conventions.promptFragment}`),e.commitMessages?.length&&(n+=`\n\nMatch the style of these original commit messages:\n${JSON.stringify(e.commitMessages)}`),e.instructions&&(n+=`\n\nAdditional instructions:\n${e.instructions}`),t===`commits`?n+=`
+
+Return your grouping as JSON inside <output> tags. Wrap all commits in a single branch with id "default", name "", title "", description "":
+<output>
+{
+  "branches": [
+    {
+      "id": "default",
+      "name": "",
+      "title": "",
+      "description": "",
+      "commits": [
+        {
+          "id": "[commit id]",
+          "message": "[commit message]",
+          "explanation": "[explanation]",
+          "hunks": [0, 1, 2]
+        }
+      ]
+    }
+  ]
+}
+</output>
+
+Return only the <output> tag and no other text.`:n+=`
+
+Return your grouping as JSON inside <output> tags:
+<output>
+{
+  "branches": [
+    {
+      "id": "[branch id]",
+      "name": "[branch name]",
+      "title": "[short PR title]",
+      "description": "[branch description]",
+      "commits": [
+        {
+          "id": "[commit id]",
+          "message": "[commit message]",
+          "explanation": "[explanation]",
+          "hunks": [0, 1, 2]
+        }
+      ]
+    }
+  ]
+}
+</output>
+
+Return only the <output> tag and no other text.`,n}function f(e){let t=e?.branchSplitting??`balanced`,n=`Based on your analysis of the changes, now organize the hunks into commits and branches. Each hunk must be assigned to exactly one commit, and each commit belongs to exactly one branch.`,r=`Consider merge-order preference: even if two concerns compile independently, they should be in the same branch or stacked if merging one without the other would be incomplete or confusing (e.g., documentation for utilities should be with or after those utilities).`;return t===`conservative`?`${n}
+
+Default to a single branch. Only create multiple branches when concerns are completely unrelated — different domains, different purposes, no merge-order preference.
+${r}
+When in doubt, use fewer branches.`:t===`aggressive`?`${n}
+
+Create separate branches for each distinct concern. If changes address different features or subsystems, give each its own branch. Prefer more branches over fewer — each PR should be as focused as possible.
+${r}`:`${n}
+
+Create separate branches when concerns are genuinely independent — different problems or features where a reviewer would gain nothing from seeing them together in one PR. For example, a utility function addition and an unrelated error handling improvement are good candidates for separate branches.
+
+Keep changes in the same branch when they form a coherent story that benefits from joint review, or when there is a merge-order preference between them.
+${r}
+When in doubt, consider: "Would a reviewer want to see these together, or would separating them make review easier?"`}export{d as buildGroupContinuationPrompt,a as buildGroupSystemPrompt,u as buildGroupUserPrompt};

package/dist/tasks/group/schema.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+//#region src/tasks/group/schema.d.ts
+declare const groupingResultSchema: z.ZodObject<{
+  branches: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    commits: z.ZodArray<z.ZodObject<{
+      id: z.ZodString;
+      message: z.ZodString;
+      explanation: z.ZodString;
+      hunks: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+//#endregion
+export { groupingResultSchema };

package/dist/tasks/group/schema.js

@@ -0,0 +1 @@
+import{z as e}from"zod";const t=e.object({id:e.string().describe(`Unique commit ID (e.g. commit-1)`),message:e.string().describe(`Commit message`),explanation:e.string().describe(`Detailed explanation of the commit`),hunks:e.array(e.number().int().describe(`Hunk index`)).describe(`Hunk indices included in this commit`)}),n=e.object({id:e.string().min(1).describe(`Unique branch ID`),name:e.string().describe(`Branch name (empty string for commits-only mode)`),title:e.string().describe(`Short PR-style title for this branch (under 72 chars, imperative mood, e.g. 'Add user authentication')`),description:e.string().describe(`What this branch accomplishes`),commits:e.array(t).min(1).describe(`Commits in this branch`)}),r=e.object({branches:e.array(n).min(1).describe(`Branches containing grouped commits`)});export{r as groupingResultSchema};

package/dist/tasks/group/types.d.ts

@@ -0,0 +1,61 @@
+import { ProgressEvent, TokenUsage } from "../../ai/types.js";
+import { BranchGroup, ComposeHunk, PromptOverride } from "../types.js";
+import { ConventionDescriptor } from "../../git/utils/conventions.js";
+import { OnAfterModelCall, OnBeforeModelCall, OnBeforePrompt } from "../ai-loop.js";
+import { AnalysisResult } from "../analyze/types.js";
+import { ComposeSession } from "../session.js";
+import { AiModelPort } from "@gitkraken/shared-tools";
+
+//#region src/tasks/group/types.d.ts
+interface GroupingStrategy {
+  /**
+   * How aggressively to split changes into separate branches.
+   * - "conservative": default to one branch; only split when concerns are completely unrelated
+   * - "balanced": split when concerns are independent, even if they touch a similar domain (default)
+   * - "aggressive": maximize branch count; any distinct concern gets its own branch
+   */
+  branchSplitting?: 'conservative' | 'balanced' | 'aggressive';
+  /**
+   * How aggressively to split changes into multiple commits vs consolidating.
+   * - "consolidated": fewer, larger commits; combine related changes
+   * - "balanced": natural grouping by logical unit of work (default)
+   * - "granular": maximize commit count; each distinct change gets its own commit
+   */
+  commitGranularity?: 'consolidated' | 'balanced' | 'granular';
+}
+interface GroupInput {
+  hunks?: ComposeHunk[];
+  analysis?: AnalysisResult;
+  commitMessages?: string[];
+  instructions?: string;
+  conventions?: ConventionDescriptor;
+  /** "commits" = flat commit list (no branch naming). "branches" = AI decides branches (default). */
+  mode?: 'commits' | 'branches';
+  /** Controls how aggressively the AI splits branches and commits. */
+  strategy?: GroupingStrategy;
+  /** Branch names that already exist in the repo — used to detect collisions during validation. */
+  existingBranchNames?: Set<string>;
+  model: AiModelPort;
+  session?: ComposeSession;
+  maxRetries?: number;
+  onProgress?: (event: ProgressEvent) => void;
+  signal?: AbortSignal;
+  onBeforeModelCall?: OnBeforeModelCall;
+  onAfterModelCall?: OnAfterModelCall;
+  onBeforePrompt?: OnBeforePrompt;
+  /** Optional prompt override. When set, replaces or decorates the built-in prompts. */
+  promptOverride?: PromptOverride;
+}
+interface GroupingResult {
+  branches: BranchGroup[];
+}
+interface GroupOutput {
+  result: GroupingResult;
+  session: ComposeSession;
+  usage?: TokenUsage;
+  attempts: number;
+  durationMs: number;
+  callIds: string[];
+}
+//#endregion
+export { GroupInput, GroupOutput, GroupingResult, GroupingStrategy };

package/dist/tasks/group/types.js

@@ -0,0 +1 @@
+export{};

package/dist/tasks/group/validator.d.ts

@@ -0,0 +1,7 @@
+import { ValidationResult } from "../ai-loop.js";
+import { GroupingResult } from "./types.js";
+
+//#region src/tasks/group/validator.d.ts
+declare function validateGroupResponse(responseText: string, totalHunks: number, mode?: 'commits' | 'branches', existingBranchNames?: Set<string>): ValidationResult<GroupingResult>;
+//#endregion
+export { validateGroupResponse };

package/dist/tasks/group/validator.js

@@ -0,0 +1,53 @@
+import{extractOutputTag as e}from"../ai-loop.js";import{groupingResultSchema as t}from"./schema.js";function n(n,a,o=`branches`,s){let c=null;try{if(c=e(n),!c)return r([`No <output> tag found in response`],i(o));let l=JSON.parse(c),u=t.safeParse(l);if(!u.success)return r(u.error.issues.map(e=>`${e.path.join(`.`)}: ${e.message}`),i(o));let d=u.data,f=[],p=new Set,m=[],h=new Set,g=[],_=[],v=new Set,y=new Set;for(let e of d.branches){if(v.has(e.id))return r([`Duplicate branch ID: '${e.id}'`],i(o));if(v.add(e.id),o===`branches`&&e.name.length===0)return r([`Branch '${e.id}': missing or empty 'name'`],i(o));if(o===`branches`&&e.name.length>0){if(y.has(e.name))return r([`Duplicate branch name: '${e.name}'`],`Multiple branches use the name '${e.name}'. Each branch must have a unique name. Please rename one of them.`);if(y.add(e.name),s?.has(e.name))return r([`Branch name '${e.name}' already exists in the repository`],`The branch name '${e.name}' already exists in the repository. Please choose a different name for branch '${e.id}'.`)}let t=[];for(let n of e.commits){h.has(n.id)&&g.push(n.id),h.add(n.id);let e=[];for(let t of n.hunks)p.has(t)&&m.push(t),p.add(t),e.push(t);e.length===0&&_.push(n.id),t.push({id:n.id,message:n.message,explanation:n.explanation,hunkIndices:e})}f.push({id:e.id,name:e.name,title:e.title,description:e.description,commits:t})}if(g.length>0)return r([`Duplicate commit IDs: ${g.join(`, `)}`],`Some commit IDs appear multiple times. Each must be unique.\n\nDuplicates: ${g.join(`, `)}`);if(_.length>0)return r([`Empty commits (no hunks assigned): ${_.join(`, `)}`],`Every commit must contain at least one hunk. These commits have an empty \`hunks\` array: ${_.join(`, `)}.
+
+Either assign at least one hunk to each of these commits, or remove them entirely. If a commit's purpose is already covered by another commit, remove the duplicate. If a commit is supposed to cover specific hunks, assign those hunk indices to it. Every hunk index still needs to appear in exactly one commit.`);let b=new Set(Array.from({length:a},(e,t)=>t)),x=[...b].filter(e=>!p.has(e)),S=[...p].filter(e=>!b.has(e));if(m.length>0||x.length>0||S.length>0){let e=[],t=[];return m.length>0&&(e.push(`Duplicate hunks (assigned to multiple commits): ${m.join(`, `)}`),t.push(`Duplicate hunks: ${m.join(`, `)}`)),x.length>0&&(e.push(`Missing hunks (not assigned to any commit): ${x.join(`, `)}`),t.push(`Missing hunks: ${x.join(`, `)}`)),S.length>0&&(e.push(`Extra hunks (index out of range): ${S.join(`, `)}`),t.push(`Extra hunks: ${S.join(`, `)}`)),r(t,`There are ${a} hunks (indices 0 to ${a-1}). Every index must appear in exactly one commit — no duplicates, no gaps, no out-of-range indices.
+
+Your response has these problems:
+${e.map(e=>`- ${e}`).join(`
+`)}
+
+Fix these specific issues and return the corrected JSON inside <output> tags.`)}return{valid:!0,result:{branches:f}}}catch(e){let t=e instanceof Error?e.message:String(e),a=(c??n).substring(0,200);return r([`Failed to parse response as valid JSON: ${t}`,`Response preview: ${a}`],i(o))}}function r(e,t){return{valid:!1,errors:e,retryFeedback:t}}function i(e){return e===`commits`?`Your response has an invalid structure. Please return JSON inside <output> tags. Use a single branch with id "default", name "", description "":
+<output>
+{
+  "branches": [
+    {
+      "id": "default",
+      "name": "",
+      "title": "",
+      "description": "",
+      "commits": [
+        {
+          "id": "[commit id]",
+          "message": "[commit message]",
+          "explanation": "[explanation]",
+          "hunks": [0, 1, 2]
+        }
+      ]
+    }
+  ]
+}
+</output>
+
+Return only the <output> tag and no other text.`:`Your response has an invalid structure. Please return JSON inside <output> tags:
+<output>
+{
+  "branches": [
+    {
+      "id": "[branch id]",
+      "name": "[branch name]",
+      "title": "[short PR title]",
+      "description": "[branch description]",
+      "commits": [
+        {
+          "id": "[commit id]",
+          "message": "[commit message]",
+          "explanation": "[explanation]",
+          "hunks": [0, 1, 2]
+        }
+      ]
+    }
+  ]
+}
+</output>
+
+Return only the <output> tag and no other text.`}export{n as validateGroupResponse};

package/dist/tasks/index.d.ts

@@ -0,0 +1,15 @@
+import { BranchGroup, BranchOrdering, BranchPartition, CommitDetail, CommitSuggestion, ComposeHunk, ComposeTaskName, PromptOverride } from "./types.js";
+import { AnalysisResult, AnalyzeInput, AnalyzeOutput, Concern, ConcernDependency, HunkAnnotation, HunkOrderingConstraint } from "./analyze/types.js";
+import { GroupInput, GroupOutput, GroupingResult, GroupingStrategy } from "./group/types.js";
+import { OrderInput, OrderOutput, OrderingResult } from "./order/types.js";
+import { QuickComposeInput, QuickComposeOutput, QuickComposeResult } from "./quick-compose/types.js";
+import { ComposeSession } from "./session.js";
+import { PartitionInput, PartitionOutput, PartitionResult, PartitionStrategy } from "./partition/types.js";
+import { analyze } from "./analyze/analyze.js";
+import { ComposeGroupInput, ComposeGroupOutput } from "./compose-group/types.js";
+import { composeGroup } from "./compose-group/compose-group.js";
+import { group } from "./group/group.js";
+import { order } from "./order/order.js";
+import { partition } from "./partition/partition.js";
+import { quickCompose } from "./quick-compose/quick-compose.js";
+export { type AnalysisResult, type AnalyzeInput, type AnalyzeOutput, type BranchGroup, type BranchOrdering, type BranchPartition, type CommitDetail, type CommitSuggestion, type ComposeGroupInput, type ComposeGroupOutput, type ComposeHunk, type ComposeSession, type ComposeTaskName, type Concern, type ConcernDependency, type GroupInput, type GroupOutput, type GroupingResult, type GroupingStrategy, type HunkAnnotation, type HunkOrderingConstraint, type OrderInput, type OrderOutput, type OrderingResult, type PartitionInput, type PartitionOutput, type PartitionResult, type PartitionStrategy, type PromptOverride, type QuickComposeInput, type QuickComposeOutput, type QuickComposeResult, analyze, composeGroup, group, order, partition, quickCompose };

package/dist/tasks/index.js

@@ -0,0 +1 @@
+import{analyze as e}from"./analyze/analyze.js";import{composeGroup as t}from"./compose-group/compose-group.js";import{group as n}from"./group/group.js";import{order as r}from"./order/order.js";import{partition as i}from"./partition/partition.js";import{quickCompose as a}from"./quick-compose/quick-compose.js";export{e as analyze,t as composeGroup,n as group,r as order,i as partition,a as quickCompose};

package/dist/tasks/order/order.d.ts

@@ -0,0 +1,6 @@
+import { OrderInput, OrderOutput } from "./types.js";
+
+//#region src/tasks/order/order.d.ts
+declare function order(input: OrderInput): Promise<OrderOutput>;
+//#endregion
+export { order };

package/dist/tasks/order/order.js

@@ -0,0 +1 @@
+import{TaskInputError as e}from"../../errors/task.js";import{runAiLoop as t}from"../ai-loop.js";import{applyUserPromptOverride as n}from"../types.js";import{buildOrderContinuationPrompt as r,buildOrderSystemPrompt as i,buildOrderUserPrompt as a}from"./prompt.js";import{validateOrderResponse as o}from"./validator.js";async function s(s){let c=s.branches??s.session?.completedSteps.group?.branches;if((!c||c.length===0)&&!s.session)throw new e(`No branches provided: supply 'branches' or run group() first with a session`);if(s.session?.completedSteps.order)return{result:s.session.completedSteps.order,session:s.session,attempts:0,durationMs:0,callIds:[]};let l=(c??[]).map(e=>({branchId:e.id,commitIds:e.commits.map(e=>e.id)})),u=n(s.session?r(s):a({branches:c,hunks:s.hunks,instructions:s.instructions}),s.promptOverride),d=await t({model:s.model,systemPrompt:s.session?void 0:s.promptOverride?.system??i(),userPrompt:u,session:s.session,maxRetries:s.maxRetries,onProgress:s.onProgress,signal:s.signal,onBeforeModelCall:s.onBeforeModelCall,onAfterModelCall:s.onAfterModelCall,onBeforePrompt:s.onBeforePrompt,validate:e=>o(e,l),taskName:`order`}),f=s.session?.completedSteps??{},p={...d.session,completedSteps:{...f,order:d.result}};return{result:d.result,session:p,usage:d.usage,attempts:d.attempts,durationMs:d.durationMs,callIds:d.callIds}}export{s as order};

package/dist/tasks/order/prompt.d.ts

@@ -0,0 +1,13 @@
+import { BranchGroup, ComposeHunk } from "../types.js";
+import { OrderInput } from "./types.js";
+
+//#region src/tasks/order/prompt.d.ts
+declare function buildOrderSystemPrompt(): string;
+declare function buildOrderUserPrompt(params: {
+  branches: BranchGroup[];
+  hunks?: ComposeHunk[];
+  instructions?: string;
+}): string;
+declare function buildOrderContinuationPrompt(input: OrderInput): string;
+//#endregion
+export { buildOrderContinuationPrompt, buildOrderSystemPrompt, buildOrderUserPrompt };