@kendoo.agentdesk/agentdesk 0.14.5 → 0.15.0

package/README.md

@@ -81,7 +81,7 @@ agentdesk update                       Update to the latest version
 |------|-------------|
 | `--description`, `-d` | Task description or requirements |
 | `--cwd` | Working directory (defaults to current) |
-| `--phased` | Run in phased mode (INTAKE → PLAN → EXECUTION) — each phase runs as a separate Claude process for better context handling. Also available as a toggle in the dashboard when starting a session. |
+| `--phased` | Run in phased mode (INTAKE → PLAN → EXECUTION → REVIEW → SUMMARY) — each phase runs as a separate Claude process for better context handling. Also available as a toggle in the dashboard when starting a session. |
 | `--child-strategy` | How to handle child tasks: `inline` (default) or `branch` |
 
 ## Configuration
@@ -157,19 +157,23 @@ You can also toggle screenshots per session when starting a task from the Web UI
 
 ### Model per phase
 
-In phased mode (`INTAKE → PLAN → EXECUTION`), you can pick a different Claude model per phase from project settings. Useful when you want a stronger model for planning and implementation but a cheaper one for intake.
+In phased mode (`INTAKE → PLAN → EXECUTION → REVIEW → SUMMARY`), you can pick a different Claude model per phase from project settings. Useful when you want a stronger model for planning and implementation but a cheaper one for the lighter phases.
 
 ```json
 {
   "phaseModels": {
     "INTAKE": "sonnet",
     "PLAN": "opus",
-    "EXECUTION": "opus"
+    "EXECUTION": "opus",
+    "REVIEW": "haiku",
+    "SUMMARY": "haiku"
   }
 }
 ```
 
-Valid values: `"default"` (Claude Code's default), `"opus"`, `"sonnet"`, `"haiku"`. Non-phased runs use the `EXECUTION` model.
+Valid values: `"default"`, `"opus"`, `"sonnet"`, `"haiku"`. `"default"` resolves to Claude Code's default for `INTAKE`/`PLAN`/`EXECUTION` and to `haiku` for `REVIEW`/`SUMMARY`. Non-phased runs use the `EXECUTION` model.
+
+The `REVIEW` phase is a read-only completeness check (no code changes) — it verifies the implementation meets requirements, flags missed documentation updates or silently-deferred scope. If gaps are found, the orchestrator loops back to `EXECUTION` once before moving on. The `SUMMARY` phase writes the final tracker comments and session protocol.
 
 ## How It Works
 
@@ -177,7 +181,7 @@ All agents collaborate in a single Claude process — each with distinct roles,
 
 1. You run `agentdesk team TASK-ID` in your project directory
 2. AgentDesk detects your project type, reads `CLAUDE.md`, and discovers existing agents
-3. The orchestrator manages 5 phases: **Intake** > **Brainstorm** > **Planning** > **Execution** > **Review**
+3. The orchestrator manages 5 phases: **Intake** > **Plan** > **Execution** > **Review** > **Summary**
 4. Agents discuss, disagree, and build on each other's ideas within a shared context
 5. The session streams live to [agentdesk.live](https://agentdesk.live) where you can watch and send messages to the team
 6. Token usage is tracked and displayed per session

package/bin/agentdesk.mjs

@@ -71,7 +71,7 @@ if (!command || command === "help" || command === "--help") {
   Options:
     --description, -d    Task description or requirements
     --cwd                Working directory (defaults to current)
-    --phased             Run in phased mode (INTAKE → PLAN → EXECUTION)
+    --phased             Run in phased mode (INTAKE → PLAN → EXECUTION → REVIEW → SUMMARY)
     --child-strategy     How to handle child tasks: "inline" (default) or "branch"
 
 

package/cli/config.mjs

@@ -42,10 +42,11 @@ const DEFAULTS = {
   // Capture screenshots for UI tasks (default: on)
   screenshots: true,
 
-  // Model per phase — override Claude Code's default per phase.
-  // Keys: INTAKE, PLAN, EXECUTION. Values: "default" | "opus" | "sonnet" | "haiku".
-  // Missing entry or "default" = use Claude Code's default model.
-  // Example: { "PLAN": "opus", "EXECUTION": "opus" }
+  // Model per phase — override the phase default.
+  // Keys: INTAKE, PLAN, EXECUTION, REVIEW, SUMMARY. Values: "default" | "opus" | "sonnet" | "haiku".
+  // Missing entry or "default" falls back to the phase default
+  // (sonnet for INTAKE/PLAN/EXECUTION, haiku for REVIEW/SUMMARY).
+  // Example: { "PLAN": "opus", "EXECUTION": "opus", "REVIEW": "sonnet" }
   phaseModels: {},
 
   // Extra prompt instructions appended to the team prompt

package/cli/orchestrator.mjs

@@ -44,19 +44,29 @@ function timestamp() {
     .map(n => String(n).padStart(2, "0")).join(":");
 }
 
+// Phase-specific fallback when the user hasn't set a model override.
+// REVIEW and SUMMARY default to haiku (fast + cheap — no heavy reasoning needed).
+// INTAKE/PLAN/EXECUTION default to Claude Code's default (sonnet).
+function defaultForPhase(phase) {
+  if (phase === "REVIEW" || phase === "SUMMARY") return "haiku";
+  return null;
+}
+
 // Resolve --model args for a given phase based on project settings.
-// phaseModels is { INTAKE?, PLAN?, EXECUTION? } with values "opus"|"sonnet"|"haiku"|"default".
+// phaseModels is { INTAKE?, PLAN?, EXECUTION?, REVIEW?, SUMMARY? } with values "opus"|"sonnet"|"haiku"|"default".
 // Returns [] when no override (so Claude Code picks its default).
 function modelArgsForPhase(phase, phaseModels) {
-  const choice = phaseModels?.[phase];
-  if (!choice || choice === "default") return [];
-  // Claude Code accepts short aliases: opus, sonnet, haiku
+  let choice = phaseModels?.[phase];
+  if (!choice || choice === "default") choice = defaultForPhase(phase);
+  if (!choice) return [];
   return ["--model", choice];
 }
 
-// Display label for a phase's model ("opus"|"sonnet"|"haiku"|"default").
+// Display label for a phase's model.
 function modelLabelForPhase(phase, phaseModels) {
-  return phaseModels?.[phase] || "default";
+  const override = phaseModels?.[phase];
+  if (override && override !== "default") return override;
+  return defaultForPhase(phase) || "default";
 }
 
 export async function runOrchestrator({
@@ -262,18 +272,29 @@ export async function runPhasedOrchestrator({
     cliVersion: CLI_VERSION,
   });
 
-  const phases = ["INTAKE", "PLAN", "EXECUTION"];
   const sessionMemoryPath = join(cwd, ".agentdesk", "session-memory.md");
+  const reviewVerdictPath = join(cwd, ".agentdesk", "review-verdict.md");
+  const MAX_REVIEW_RETRIES = 1; // One execution redo after a failed review, then force SUMMARY.
   let totalInputTokens = 0, totalOutputTokens = 0, totalSteps = 0;
   let handoff = false;
+  let reviewRetries = 0;
+
+  // Ordered queue of phases; REVIEW may re-enqueue EXECUTION before SUMMARY.
+  const queue = ["INTAKE", "PLAN", "EXECUTION", "REVIEW", "SUMMARY"];
+
+  while (queue.length > 0) {
+    const phase = queue.shift();
 
-  for (const phase of phases) {
-    // Read session memory from previous phase
     let sessionMemory = "";
     try {
       if (existsSync(sessionMemoryPath)) sessionMemory = readFileSync(sessionMemoryPath, "utf-8").trim();
     } catch {}
 
+    // Clear any stale verdict before entering REVIEW so we don't read a previous run's result.
+    if (phase === "REVIEW") {
+      try { if (existsSync(reviewVerdictPath)) unlinkSync(reviewVerdictPath); } catch {}
+    }
+
     emit({ type: "phase:change", phase, model: modelLabelForPhase(phase, config?.phaseModels) });
 
     const prompt = buildPhasedPrompt({
@@ -285,42 +306,55 @@ export async function runPhasedOrchestrator({
     const modelArgs = modelArgsForPhase(phase, config?.phaseModels);
     const result = await runSinglePhase({ prompt, cwd, env, teamNames, emit, modelArgs });
 
-    // Allow daemon to track the child process for cancellation
     if (onChild) onChild(result.child);
 
     totalInputTokens += result.inputTokens;
     totalOutputTokens += result.outputTokens;
     totalSteps += result.steps;
 
-    // Check if session memory was written
     const hasMemory = existsSync(sessionMemoryPath);
 
-    if (result.exitCode !== 0) {
-      if (!hasMemory) {
-        // No memory written — can't continue, handoff
-        handoff = true;
-
-        let branch = "", diffStat = "";
-        try { branch = execSync("git branch --show-current", { cwd, encoding: "utf-8" }).trim(); } catch {}
-        try { diffStat = execSync("git diff --stat HEAD", { cwd, encoding: "utf-8" }).trim(); } catch {}
-
-        const resumePath = join(cwd, ".agentdesk-resume.md");
-        try {
-          writeFileSync(resumePath, [
-            `# AgentDesk Resume — ${taskId}`,
-            ``, `Session: ${sessionUrl}`, `Phase: ${phase}`,
-            `Date: ${new Date().toISOString()}`,
-            ``, `## Branch`, branch || "(none)",
-            ``, `## Uncommitted changes`, diffStat || "(none)",
-            ``, `## Notes`, `Phased session interrupted during ${phase}.`,
-          ].join("\n"));
-        } catch {}
-        break;
+    if (result.exitCode !== 0 && !hasMemory) {
+      handoff = true;
+
+      let branch = "", diffStat = "";
+      try { branch = execSync("git branch --show-current", { cwd, encoding: "utf-8" }).trim(); } catch {}
+      try { diffStat = execSync("git diff --stat HEAD", { cwd, encoding: "utf-8" }).trim(); } catch {}
+
+      const resumePath = join(cwd, ".agentdesk-resume.md");
+      try {
+        writeFileSync(resumePath, [
+          `# AgentDesk Resume — ${taskId}`,
+          ``, `Session: ${sessionUrl}`, `Phase: ${phase}`,
+          `Date: ${new Date().toISOString()}`,
+          ``, `## Branch`, branch || "(none)",
+          ``, `## Uncommitted changes`, diffStat || "(none)",
+          ``, `## Notes`, `Phased session interrupted during ${phase}.`,
+        ].join("\n"));
+      } catch {}
+      break;
+    }
+
+    // After REVIEW, check the verdict file. NEEDS_MORE_WORK -> loop back to EXECUTION (up to MAX_REVIEW_RETRIES).
+    if (phase === "REVIEW") {
+      let verdict = "";
+      try {
+        if (existsSync(reviewVerdictPath)) verdict = readFileSync(reviewVerdictPath, "utf-8").trim();
+      } catch {}
+
+      const needsMoreWork = /^NEEDS_MORE_WORK\b/i.test(verdict);
+      if (needsMoreWork && reviewRetries < MAX_REVIEW_RETRIES) {
+        reviewRetries++;
+        emit({ type: "agent:message", agent: "Jane", tag: "SAY",
+          message: `Review flagged gaps — returning to EXECUTION (retry ${reviewRetries}/${MAX_REVIEW_RETRIES}).` });
+        queue.unshift("EXECUTION", "REVIEW"); // redo execution, then review again
       }
-      // Memory exists — continue to next phase despite non-zero exit
     }
   }
 
+  // Clean up internal marker files regardless of outcome
+  try { if (existsSync(reviewVerdictPath)) unlinkSync(reviewVerdictPath); } catch {}
+
   const duration = `${((Date.now() - startTime) / 1000).toFixed(1)}s`;
 
   if (handoff) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kendoo.agentdesk/agentdesk",
-  "version": "0.14.5",
+  "version": "0.15.0",
   "description": "AI team orchestrator for Claude Code — run collaborative agent sessions from your terminal",
   "type": "module",
   "bin": {

package/prompts/phased.md

@@ -362,24 +362,7 @@ After completing work, agents post brief comments.
 
 {{EXECUTION_STEPS}}
 
----
-
-## SUMMARY
-
-Jane dictates the summary content; Dennis executes the tracker commands:
-1. Verify Bart posted the PR link. If not, Dennis posts it now.
-2. Dennis transitions the task to "In Review".
-3. Jane dictates the final summary text (product outcome in non-technical terms). Dennis posts the comment with:
-   - **What was done**: Brief summary of changes
-   - **What was omitted**: Anything skipped or deferred
-   - **Manual steps**: Actions the developer must perform
-   - **PR link**
-   - **Session link**: {{SESSION_URL}}
-
-Print:
-echo "Team Session Complete."
-echo "Task: {{TASK_ID}}"
-echo "Status: Ready for review."
+Do NOT post final tracker summaries or transition state here — the SUMMARY phase owns all final tracker writes.
 
 ## SESSION MEMORY UPDATE (MANDATORY)
 
@@ -395,8 +378,171 @@ Before finishing, update `.agentdesk/session-memory.md`:
 - <test results>
 - <issues found and fixed>
 
+## Next Phase: REVIEW
+- <anything the reviewer should pay extra attention to>
+```
+{{/PHASE_EXECUTION}}
+
+{{#PHASE_REVIEW}}
+You are running **Phase 4: REVIEW** of a phased team session with {{AGENT_COUNT}} agents.
+
+Task: {{TASK_ID}}
+{{TASK_LINK}}
+
+The agents are:
+
+{{AGENT_LIST}}
+
+You role-play all {{AGENT_COUNT}} agents. Jane leads. Be concise.
+
+Speaking order:
+{{SPEAKING_ORDER}}
+
+## GROUND RULES
+
+{{GROUND_RULES}}
+
+## CRITICAL: NO CODE CHANGES IN THIS PHASE
+
+This is a hard constraint:
+
+- Do NOT call Edit, Write, or any tool that modifies code, configuration, or documentation files.
+- Read-only tools are allowed: Read, Glob, Grep, and Bash for read-only commands (`git diff`, `git log`, `gh pr view`, `ls`, etc.).
+- The REVIEW phase ONLY identifies gaps and writes a verdict. Dennis does NOT fix anything here — if work is needed, it happens back in EXECUTION.
+- This is NOT a QA round. Unit tests and Bart's QA already ran in EXECUTION. Focus on higher-level completeness.
+
+## YOUR MISSION: REVIEW
+
+Re-read the session memory and the actual implementation (`git diff`, changed files). Then the team assesses:
+
+1. **Jane (product):** Does the implementation meet the acceptance criteria stated in INTAKE? Is any requirement missed or silently deferred?
+2. **Dennis (engineering):** Does the code match the PLAN? Are there obvious gaps — partially-implemented helpers, dead branches, TODOs left in place, error paths not wired up?
+3. **Sam (quality):** Are there hidden cross-cutting concerns the team missed — docs that should be updated (README, CLAUDE.md, guide/help text), changelog entries, config schema bumps, migration notes, dependent callers?
+4. **Bart (PR):** Is the PR description accurate? Does it reference the task? Are screenshots attached where expected?
+
+After each agent contributes, Jane calls the verdict.
+
+## VERDICT FILE (MANDATORY)
+
+You MUST write `.agentdesk/review-verdict.md` using the Write tool. The FIRST LINE of the file is one of:
+
+- `APPROVED` — implementation meets the bar; proceed to SUMMARY.
+- `NEEDS_MORE_WORK` — gaps identified; the orchestrator will loop back to EXECUTION.
+
+Then, on the following lines, list the findings (empty list for APPROVED):
+
+```markdown
+APPROVED
+or
+NEEDS_MORE_WORK
+
+## Findings
+- <specific, actionable item>
+- <specific, actionable item>
+
+## Out of scope (deferred to future work)
+- <items noted but intentionally NOT addressed now>
+```
+
+Be strict but not pedantic. Do NOT flag stylistic preferences or speculative refactors — only actual gaps against the task requirements and the PLAN.
+
+## SESSION MEMORY UPDATE (MANDATORY)
+
+Also update `.agentdesk/session-memory.md`:
+
+```markdown
+## Review
+- Verdict: APPROVED | NEEDS_MORE_WORK
+- Findings: <bulleted summary of gaps, or "none">
+- Out of scope: <items explicitly deferred>
+```
+{{/PHASE_REVIEW}}
+
+{{#PHASE_SUMMARY}}
+You are running **Phase 5: SUMMARY** of a phased team session with {{AGENT_COUNT}} agents.
+
+Task: {{TASK_ID}}
+{{TASK_LINK}}
+
+The agents are:
+
+{{AGENT_LIST}}
+
+Jane dictates the narrative; Dennis executes the tracker writes.
+
+## GROUND RULES
+
+{{GROUND_RULES}}
+
+## RULES
+
+- Do NOT modify code, tests, or configuration. This phase writes messages only.
+- Read-only exploration (`git diff`, `git log`, `gh pr view`) is allowed to gather accurate numbers for the summary.
+
+{{#LINEAR}}
+## LINEAR INTEGRATION
+
+- Endpoint: https://api.linear.app/graphql
+- Auth header: Authorization: $LINEAR_API_KEY
+
+### Tracker actions for SUMMARY
+
+1. Verify Bart posted the PR link in EXECUTION. If not, Dennis posts it now via `attachmentCreate`.
+2. Dennis transitions the task to "In Review":
+   ```
+   mutation { issueUpdate(id: "$ISSUE_ID", input: { stateId: "$IN_REVIEW_STATE_ID" }) { success } }
+   ```
+3. Dennis posts the final session-end comment with session link: {{SESSION_URL}}
+{{/LINEAR}}
+
+{{#JIRA}}
+## JIRA INTEGRATION
+
+- Endpoint: {{JIRA_BASE_URL}}/rest/api/3/issue/{{TASK_ID}}
+- Auth: Basic auth with $JIRA_EMAIL:$JIRA_API_TOKEN
+- Use `inlineCard` nodes for URLs in ADF format.
+
+### Tracker actions for SUMMARY
+
+1. Verify PR link is attached; attach it now if missing.
+2. Transition the task to "In Review".
+3. Post the final session-end comment with inlineCard session link: {{SESSION_URL}}
+{{/JIRA}}
+
+{{#GITHUB}}
+## GITHUB ISSUES INTEGRATION
+
+- Comment: `gh issue comment {{TASK_ID}} --body "..."`
+
+### Tracker actions for SUMMARY
+
+1. Ensure the PR references the issue ("Closes #{{TASK_ID}}").
+2. Post the final session-end comment with session link: {{SESSION_URL}}
+{{/GITHUB}}
+
+## YOUR MISSION: SUMMARY
+
+Jane dictates the final summary content (product outcome in non-technical terms). Dennis executes all tracker writes. The summary comment must include:
+
+- **What was done**: Brief, outcome-focused summary of the changes
+- **What was omitted / deferred**: Anything from REVIEW's "Out of scope" list, plus anything the team explicitly skipped
+- **Manual steps**: Actions the developer must perform (migrations, config, deploys)
+- **PR link**
+- **Session link**: {{SESSION_URL}}
+
+Then print:
+echo "Team Session Complete."
+echo "Task: {{TASK_ID}}"
+echo "Status: Ready for review."
+
+## SESSION MEMORY UPDATE (MANDATORY)
+
+Finalize `.agentdesk/session-memory.md`:
+
+```markdown
 ## Final Status
 - <task status>
-- <any remaining work>
+- <PR link>
+- <deferred items>
 ```
-{{/PHASE_EXECUTION}}
+{{/PHASE_SUMMARY}}