sequant 1.14.0 → 1.14.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "Structured workflow system for Claude Code - GitHub issue resolution with spec, exec, test, and QA phases",
-  "version": "1.14.0",
+  "version": "1.14.2",
   "author": {
     "name": "admarble",
     "email": "github@admarble.com"

package/README.md

@@ -223,6 +223,7 @@ See [Customization Guide](docs/guides/customization.md) for all options.
 - [Complete Workflow](docs/guides/workflow.md) — Full workflow including post-QA patterns
 - [Getting Started](docs/getting-started/installation.md)
 - [What We've Built](docs/internal/what-weve-built.md) — Comprehensive project overview
+- [What Is Sequant](docs/concepts/what-is-sequant.md) — Elevator pitch, pipeline diagram, architecture
 - [Workflow Concepts](docs/concepts/workflow-phases.md)
 - [Run Command](docs/reference/run-command.md)
 - [Git Workflows](docs/guides/git-workflows.md)

package/dist/bin/cli.js

@@ -138,6 +138,7 @@ program
     .option("--qa-gate", "Wait for QA pass before starting next issue in chain (requires --chain)")
     .option("--base <branch>", "Base branch for worktree creation (default: main or settings.run.defaultBase)")
     .option("--no-mcp", "Disable MCP server injection in headless mode")
+    .option("--resume", "Resume from last completed phase (reads phase markers from GitHub)")
     .action(runCommand);
 program
     .command("logs")

package/dist/src/commands/run.d.ts

@@ -37,6 +37,22 @@ export declare function getWorktreeDiffStats(worktreePath: string): {
     filesChanged: number;
     linesAdded: number;
 };
+/**
+ * Filter phases based on resume status.
+ *
+ * When `resume` is true, calls `getResumablePhasesForIssue` to determine
+ * which phases have already completed (via GitHub issue comment markers)
+ * and removes them from the execution list.
+ *
+ * @param issueNumber - GitHub issue number
+ * @param phases - The phases to potentially filter
+ * @param resume - Whether the --resume flag is set
+ * @returns Object with filtered phases and any skipped phases
+ */
+export declare function filterResumedPhases(issueNumber: number, phases: Phase[], resume: boolean): {
+    phases: Phase[];
+    skipped: Phase[];
+};
 /**
  * Create a checkpoint commit in the worktree after QA passes
  * This allows recovery in case later issues in the chain fail
@@ -103,6 +119,11 @@ interface RunOptions {
      * Resolution priority: this CLI flag → settings.run.mcp → default (true)
      */
     noMcp?: boolean;
+    /**
+     * Resume from last completed phase.
+     * Reads phase markers from GitHub issue comments and skips completed phases.
+     */
+    resume?: boolean;
 }
 /**
  * Main run command

package/dist/src/commands/run.js

@@ -20,6 +20,7 @@ import { getMcpServersConfig } from "../lib/system.js";
 import { checkVersionCached, getVersionWarning } from "../lib/version-check.js";
 import { MetricsWriter } from "../lib/workflow/metrics-writer.js";
 import { determineOutcome, } from "../lib/workflow/metrics-schema.js";
+import { getResumablePhasesForIssue } from "../lib/workflow/phase-detection.js";
 import { ui, colors } from "../lib/cli-ui.js";
 import { PhaseSpinner } from "../lib/phase-spinner.js";
 /**
@@ -159,6 +160,26 @@ export function getWorktreeDiffStats(worktreePath) {
         linesAdded: insertionsMatch ? parseInt(insertionsMatch[1], 10) : 0,
     };
 }
+/**
+ * Filter phases based on resume status.
+ *
+ * When `resume` is true, calls `getResumablePhasesForIssue` to determine
+ * which phases have already completed (via GitHub issue comment markers)
+ * and removes them from the execution list.
+ *
+ * @param issueNumber - GitHub issue number
+ * @param phases - The phases to potentially filter
+ * @param resume - Whether the --resume flag is set
+ * @returns Object with filtered phases and any skipped phases
+ */
+export function filterResumedPhases(issueNumber, phases, resume) {
+    if (!resume) {
+        return { phases: [...phases], skipped: [] };
+    }
+    const resumable = getResumablePhasesForIssue(issueNumber, phases);
+    const skipped = phases.filter((p) => !resumable.includes(p));
+    return { phases: resumable, skipped };
+}
 /**
  * Create or reuse a worktree for an issue
  * @param baseBranch - Optional branch to use as base instead of origin/main (for chain mode)
@@ -1631,6 +1652,20 @@ async function runIssueWithLogging(issueNumber, config, logWriter, stateManager,
             console.log(chalk.gray(`    Phases adjusted: ${phases.join(" → ")}`));
         }
     }
+    // Resume: filter out completed phases if --resume flag is set
+    if (options.resume) {
+        const resumeResult = filterResumedPhases(issueNumber, phases, true);
+        if (resumeResult.skipped.length > 0) {
+            console.log(chalk.gray(`    Resume: skipping completed phases: ${resumeResult.skipped.join(", ")}`));
+            phases = resumeResult.phases;
+        }
+        // Also skip spec if it was auto-detected as completed
+        if (specAlreadyRan &&
+            resumeResult.skipped.length === 0 &&
+            resumeResult.phases.length === 0) {
+            console.log(chalk.gray(`    Resume: all phases already completed`));
+        }
+    }
     // Add testgen phase if requested (and spec was in the phases)
     if (options.testgen &&
         (phases.includes("spec") || specAlreadyRan) &&

package/dist/src/index.d.ts

@@ -18,7 +18,8 @@ export type { SequantConfig } from "./lib/config.js";
 export { StateManager, getStateManager } from "./lib/workflow/state-manager.js";
 export type { StateManagerOptions } from "./lib/workflow/state-manager.js";
 export { createEmptyState, createIssueState, createPhaseState, STATE_FILE_PATH, WORKFLOW_PHASES, } from "./lib/workflow/state-schema.js";
-export type { WorkflowState, IssueState, PhaseState, Phase, PhaseStatus, IssueStatus, PRInfo, LoopState, } from "./lib/workflow/state-schema.js";
+export type { WorkflowState, IssueState, PhaseState, Phase, PhaseStatus, IssueStatus, PRInfo, LoopState, PhaseMarker, } from "./lib/workflow/state-schema.js";
+export { formatPhaseMarker, parsePhaseMarkers, detectPhaseFromComments, getPhaseMap, getCompletedPhasesFromComments, getResumablePhases, isPhaseCompletedOrPast, getIssuePhase, getCompletedPhases, getResumablePhasesForIssue, } from "./lib/workflow/phase-detection.js";
 export { createStateHook, isOrchestrated, getOrchestrationContext, } from "./lib/workflow/state-hook.js";
 export type { StateHook, StateHookOptions } from "./lib/workflow/state-hook.js";
 export { rebuildStateFromLogs, cleanupStaleEntries, } from "./lib/workflow/state-utils.js";

package/dist/src/index.js

@@ -14,6 +14,8 @@ export { copyTemplates, listTemplateFiles, getTemplateContent, processTemplate,
 // Workflow state exports
 export { StateManager, getStateManager } from "./lib/workflow/state-manager.js";
 export { createEmptyState, createIssueState, createPhaseState, STATE_FILE_PATH, WORKFLOW_PHASES, } from "./lib/workflow/state-schema.js";
+// Phase detection exports
+export { formatPhaseMarker, parsePhaseMarkers, detectPhaseFromComments, getPhaseMap, getCompletedPhasesFromComments, getResumablePhases, isPhaseCompletedOrPast, getIssuePhase, getCompletedPhases, getResumablePhasesForIssue, } from "./lib/workflow/phase-detection.js";
 export { createStateHook, isOrchestrated, getOrchestrationContext, } from "./lib/workflow/state-hook.js";
 export { rebuildStateFromLogs, cleanupStaleEntries, } from "./lib/workflow/state-utils.js";
 // Content analysis exports

package/dist/src/lib/workflow/phase-detection.d.ts

@@ -0,0 +1,114 @@
+/**
+ * GitHub-based workflow phase detection for smart resumption.
+ *
+ * Reads phase markers from GitHub issue comments to detect workflow state
+ * across machines, sessions, and users. Enables skills and `sequant run`
+ * to resume from where they left off.
+ *
+ * Phase markers are embedded as HTML comments in issue comment bodies:
+ * ```
+ * <!-- SEQUANT_PHASE: {"phase":"exec","status":"completed","timestamp":"..."} -->
+ * ```
+ */
+import { type Phase, type PhaseMarker } from "./state-schema.js";
+/**
+ * Format a phase marker as an HTML comment string for embedding in GitHub comments.
+ *
+ * @param marker - The phase marker data
+ * @returns HTML comment string like `<!-- SEQUANT_PHASE: {...} -->`
+ */
+export declare function formatPhaseMarker(marker: PhaseMarker): string;
+/**
+ * Parse all phase markers from a single comment body.
+ *
+ * @param commentBody - The full body text of a GitHub comment
+ * @returns Array of parsed phase markers (empty if none found)
+ */
+export declare function parsePhaseMarkers(commentBody: string): PhaseMarker[];
+/**
+ * Detect the latest phase from an array of comment bodies.
+ *
+ * Scans all comments for phase markers and returns the most recent one
+ * based on the timestamp field.
+ *
+ * @param comments - Array of objects with a `body` string field
+ * @returns The latest phase marker, or null if no markers found
+ */
+export declare function detectPhaseFromComments(comments: {
+    body: string;
+}[]): PhaseMarker | null;
+/**
+ * Get all phase markers from issue comments, grouped by phase.
+ *
+ * Returns the latest marker for each phase that has been recorded.
+ *
+ * @param comments - Array of comment bodies
+ * @returns Map of phase → latest marker for that phase
+ */
+export declare function getPhaseMap(comments: {
+    body: string;
+}[]): Map<Phase, PhaseMarker>;
+/**
+ * Get list of phases that have been completed for an issue.
+ *
+ * @param comments - Array of comment bodies
+ * @returns Array of phase names that have status "completed"
+ */
+export declare function getCompletedPhasesFromComments(comments: {
+    body: string;
+}[]): Phase[];
+/**
+ * Determine which phases to run based on completed phases and requested phases.
+ *
+ * Filters out phases that are already completed. If a phase failed,
+ * it is kept in the list (for retry).
+ *
+ * @param requestedPhases - The phases the user wants to run
+ * @param comments - Array of comment bodies from the issue
+ * @returns Filtered array of phases that still need to run
+ */
+export declare function getResumablePhases(requestedPhases: readonly string[], comments: {
+    body: string;
+}[]): string[];
+/**
+ * Check if a specific phase has been reached or passed.
+ *
+ * Uses WORKFLOW_PHASES ordering to determine if the target phase
+ * is at or before the latest completed phase.
+ *
+ * @param targetPhase - The phase to check
+ * @param comments - Array of comment bodies
+ * @returns true if targetPhase has been completed or a later phase has been completed
+ */
+export declare function isPhaseCompletedOrPast(targetPhase: Phase, comments: {
+    body: string;
+}[]): boolean;
+/**
+ * Get the current phase status for an issue from GitHub comments.
+ *
+ * Calls `gh` CLI to fetch comments and parse phase markers.
+ *
+ * @param issueNumber - GitHub issue number
+ * @returns Latest phase marker, or null if no markers found or on error
+ */
+export declare function getIssuePhase(issueNumber: number): PhaseMarker | null;
+/**
+ * Get completed phases for an issue from GitHub comments.
+ *
+ * Calls `gh` CLI to fetch comments and extract completed phases.
+ *
+ * @param issueNumber - GitHub issue number
+ * @returns Array of completed phase names, or empty array on error
+ */
+export declare function getCompletedPhases(issueNumber: number): Phase[];
+/**
+ * Get resumable phases for an issue from GitHub comments.
+ *
+ * Convenience wrapper that fetches comments via `gh` CLI and
+ * filters requested phases by completed status.
+ *
+ * @param issueNumber - GitHub issue number
+ * @param requestedPhases - The phases the user wants to run
+ * @returns Filtered phases that still need to run
+ */
+export declare function getResumablePhasesForIssue(issueNumber: number, requestedPhases: readonly string[]): string[];

package/dist/src/lib/workflow/phase-detection.js

@@ -0,0 +1,215 @@
+/**
+ * GitHub-based workflow phase detection for smart resumption.
+ *
+ * Reads phase markers from GitHub issue comments to detect workflow state
+ * across machines, sessions, and users. Enables skills and `sequant run`
+ * to resume from where they left off.
+ *
+ * Phase markers are embedded as HTML comments in issue comment bodies:
+ * ```
+ * <!-- SEQUANT_PHASE: {"phase":"exec","status":"completed","timestamp":"..."} -->
+ * ```
+ */
+import { execSync } from "child_process";
+import { PhaseMarkerSchema, WORKFLOW_PHASES, } from "./state-schema.js";
+/** Regex to extract phase marker JSON from HTML comments */
+const PHASE_MARKER_REGEX = /<!-- SEQUANT_PHASE: (\{[^}]+\}) -->/g;
+/**
+ * Format a phase marker as an HTML comment string for embedding in GitHub comments.
+ *
+ * @param marker - The phase marker data
+ * @returns HTML comment string like `<!-- SEQUANT_PHASE: {...} -->`
+ */
+export function formatPhaseMarker(marker) {
+    return `<!-- SEQUANT_PHASE: ${JSON.stringify(marker)} -->`;
+}
+/**
+ * Parse all phase markers from a single comment body.
+ *
+ * @param commentBody - The full body text of a GitHub comment
+ * @returns Array of parsed phase markers (empty if none found)
+ */
+export function parsePhaseMarkers(commentBody) {
+    const markers = [];
+    // Reset regex state for reuse
+    PHASE_MARKER_REGEX.lastIndex = 0;
+    let match;
+    while ((match = PHASE_MARKER_REGEX.exec(commentBody)) !== null) {
+        try {
+            const parsed = JSON.parse(match[1]);
+            const result = PhaseMarkerSchema.safeParse(parsed);
+            if (result.success) {
+                markers.push(result.data);
+            }
+        }
+        catch {
+            // Malformed JSON — skip silently
+        }
+    }
+    return markers;
+}
+/**
+ * Detect the latest phase from an array of comment bodies.
+ *
+ * Scans all comments for phase markers and returns the most recent one
+ * based on the timestamp field.
+ *
+ * @param comments - Array of objects with a `body` string field
+ * @returns The latest phase marker, or null if no markers found
+ */
+export function detectPhaseFromComments(comments) {
+    const allMarkers = [];
+    for (const comment of comments) {
+        const markers = parsePhaseMarkers(comment.body);
+        allMarkers.push(...markers);
+    }
+    if (allMarkers.length === 0) {
+        return null;
+    }
+    // Sort by timestamp descending, return latest
+    allMarkers.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    return allMarkers[0];
+}
+/**
+ * Get all phase markers from issue comments, grouped by phase.
+ *
+ * Returns the latest marker for each phase that has been recorded.
+ *
+ * @param comments - Array of comment bodies
+ * @returns Map of phase → latest marker for that phase
+ */
+export function getPhaseMap(comments) {
+    const phaseMap = new Map();
+    for (const comment of comments) {
+        const markers = parsePhaseMarkers(comment.body);
+        for (const marker of markers) {
+            const existing = phaseMap.get(marker.phase);
+            if (!existing ||
+                new Date(marker.timestamp).getTime() >
+                    new Date(existing.timestamp).getTime()) {
+                phaseMap.set(marker.phase, marker);
+            }
+        }
+    }
+    return phaseMap;
+}
+/**
+ * Get list of phases that have been completed for an issue.
+ *
+ * @param comments - Array of comment bodies
+ * @returns Array of phase names that have status "completed"
+ */
+export function getCompletedPhasesFromComments(comments) {
+    const phaseMap = getPhaseMap(comments);
+    const completed = [];
+    for (const phase of WORKFLOW_PHASES) {
+        const marker = phaseMap.get(phase);
+        if (marker && marker.status === "completed") {
+            completed.push(phase);
+        }
+    }
+    return completed;
+}
+/**
+ * Determine which phases to run based on completed phases and requested phases.
+ *
+ * Filters out phases that are already completed. If a phase failed,
+ * it is kept in the list (for retry).
+ *
+ * @param requestedPhases - The phases the user wants to run
+ * @param comments - Array of comment bodies from the issue
+ * @returns Filtered array of phases that still need to run
+ */
+export function getResumablePhases(requestedPhases, comments) {
+    const completedPhases = new Set(getCompletedPhasesFromComments(comments));
+    return requestedPhases.filter((phase) => !completedPhases.has(phase));
+}
+/**
+ * Check if a specific phase has been reached or passed.
+ *
+ * Uses WORKFLOW_PHASES ordering to determine if the target phase
+ * is at or before the latest completed phase.
+ *
+ * @param targetPhase - The phase to check
+ * @param comments - Array of comment bodies
+ * @returns true if targetPhase has been completed or a later phase has been completed
+ */
+export function isPhaseCompletedOrPast(targetPhase, comments) {
+    const phaseMap = getPhaseMap(comments);
+    const targetIndex = WORKFLOW_PHASES.indexOf(targetPhase);
+    // Check if target phase itself is completed
+    const targetMarker = phaseMap.get(targetPhase);
+    if (targetMarker && targetMarker.status === "completed") {
+        return true;
+    }
+    // Check if any later phase is completed (implies target was completed)
+    for (let i = targetIndex + 1; i < WORKFLOW_PHASES.length; i++) {
+        const laterPhase = WORKFLOW_PHASES[i];
+        const laterMarker = phaseMap.get(laterPhase);
+        if (laterMarker && laterMarker.status === "completed") {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get the current phase status for an issue from GitHub comments.
+ *
+ * Calls `gh` CLI to fetch comments and parse phase markers.
+ *
+ * @param issueNumber - GitHub issue number
+ * @returns Latest phase marker, or null if no markers found or on error
+ */
+export function getIssuePhase(issueNumber) {
+    try {
+        const output = execSync(`gh issue view ${issueNumber} --json comments --jq '[.comments[].body]'`, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+        const bodies = JSON.parse(output);
+        const comments = bodies.map((body) => ({ body }));
+        return detectPhaseFromComments(comments);
+    }
+    catch {
+        // GitHub CLI failure — fall through to normal execution
+        return null;
+    }
+}
+/**
+ * Get completed phases for an issue from GitHub comments.
+ *
+ * Calls `gh` CLI to fetch comments and extract completed phases.
+ *
+ * @param issueNumber - GitHub issue number
+ * @returns Array of completed phase names, or empty array on error
+ */
+export function getCompletedPhases(issueNumber) {
+    try {
+        const output = execSync(`gh issue view ${issueNumber} --json comments --jq '[.comments[].body]'`, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+        const bodies = JSON.parse(output);
+        const comments = bodies.map((body) => ({ body }));
+        return getCompletedPhasesFromComments(comments);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get resumable phases for an issue from GitHub comments.
+ *
+ * Convenience wrapper that fetches comments via `gh` CLI and
+ * filters requested phases by completed status.
+ *
+ * @param issueNumber - GitHub issue number
+ * @param requestedPhases - The phases the user wants to run
+ * @returns Filtered phases that still need to run
+ */
+export function getResumablePhasesForIssue(issueNumber, requestedPhases) {
+    try {
+        const output = execSync(`gh issue view ${issueNumber} --json comments --jq '[.comments[].body]'`, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+        const bodies = JSON.parse(output);
+        const comments = bodies.map((body) => ({ body }));
+        return getResumablePhases(requestedPhases, comments);
+    }
+    catch {
+        // On error, return all phases (no filtering)
+        return [...requestedPhases];
+    }
+}

package/dist/src/lib/workflow/state-schema.d.ts

@@ -60,6 +60,35 @@ export declare const PhaseSchema: z.ZodEnum<{
     merger: "merger";
 }>;
 export type Phase = z.infer<typeof PhaseSchema>;
+/**
+ * Phase marker stored in GitHub issue comments for cross-session detection.
+ *
+ * Embedded as HTML comments: `<!-- SEQUANT_PHASE: {...} -->`
+ */
+export declare const PhaseMarkerSchema: z.ZodObject<{
+    phase: z.ZodEnum<{
+        loop: "loop";
+        verify: "verify";
+        spec: "spec";
+        exec: "exec";
+        qa: "qa";
+        "security-review": "security-review";
+        testgen: "testgen";
+        test: "test";
+        merger: "merger";
+    }>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        skipped: "skipped";
+        completed: "completed";
+        in_progress: "in_progress";
+        failed: "failed";
+    }>;
+    timestamp: z.ZodString;
+    pr: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PhaseMarker = z.infer<typeof PhaseMarkerSchema>;
 /**
  * Individual phase state within an issue
  */

package/dist/src/lib/workflow/state-schema.js

@@ -68,6 +68,23 @@ export const PhaseSchema = z.enum([
     "loop",
     "merger",
 ]);
+/**
+ * Phase marker stored in GitHub issue comments for cross-session detection.
+ *
+ * Embedded as HTML comments: `<!-- SEQUANT_PHASE: {...} -->`
+ */
+export const PhaseMarkerSchema = z.object({
+    /** The workflow phase */
+    phase: PhaseSchema,
+    /** Phase completion status */
+    status: PhaseStatusSchema,
+    /** ISO 8601 timestamp */
+    timestamp: z.string().datetime(),
+    /** PR number if created during this phase */
+    pr: z.number().int().positive().optional(),
+    /** Error message if phase failed */
+    error: z.string().optional(),
+});
 /**
  * Individual phase state within an issue
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "1.14.0",
+  "version": "1.14.2",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {

package/templates/skills/exec/SKILL.md

@@ -37,7 +37,7 @@ allowed-tools:
   - mcp__context7__*  # Library documentation lookup - falls back to web search if unavailable
   - mcp__sequential-thinking__*  # Complex reasoning - falls back to standard analysis if unavailable
   # Task management
-  - Task
+  - Task(general-purpose)
   - TodoWrite
 ---
 
@@ -56,6 +56,55 @@ When invoked as `/exec`, your job is to:
 5. Iterate until the AC appear satisfied or clear blockers are reached.
 6. Draft a progress update for the GitHub issue.
 
+## Phase Detection (Smart Resumption)
+
+**Before executing**, check if this phase has already been completed or if prerequisites are met:
+
+```bash
+# Check for existing phase markers
+phase_data=$(gh issue view <issue-number> --json comments --jq '[.comments[].body]' | \
+  grep -o '{[^}]*}' | grep '"phase"' | tail -1)
+
+if [[ -n "$phase_data" ]]; then
+  phase=$(echo "$phase_data" | jq -r '.phase')
+  status=$(echo "$phase_data" | jq -r '.status')
+
+  # Skip if exec is already completed
+  if [[ "$phase" == "exec" && "$status" == "completed" ]]; then
+    echo "⏭️ Exec phase already completed. Skipping."
+    # Exit early — no work needed
+  fi
+
+  # Resume if exec previously failed
+  if [[ "$phase" == "exec" && "$status" == "failed" ]]; then
+    echo "🔄 Exec phase previously failed. Resuming from failure point."
+    # Continue execution — will retry the implementation
+  fi
+fi
+```
+
+**Behavior:**
+- If `exec:completed` → Skip with message
+- If `exec:failed` → Resume (retry implementation)
+- If `spec:completed` (no exec marker) → Normal execution
+- If no markers found → Normal execution (fresh start)
+- If detection fails (API error) → Fall through to normal execution
+
+**Phase Marker Emission:**
+
+When posting the progress update comment to GitHub, append a phase marker at the end:
+
+```markdown
+<!-- SEQUANT_PHASE: {"phase":"exec","status":"completed","timestamp":"<ISO-8601>","pr":<PR_NUMBER>} -->
+```
+
+If exec fails, emit a failure marker:
+```markdown
+<!-- SEQUANT_PHASE: {"phase":"exec","status":"failed","timestamp":"<ISO-8601>","error":"<error message>"} -->
+```
+
+Include this marker in every `gh issue comment` that represents phase completion or failure.
+
 ## Behavior
 
 Invocation:

package/templates/skills/fullsolve/SKILL.md

@@ -13,7 +13,7 @@ allowed-tools:
   - Grep
   - Bash
   - TodoWrite
-  - Task
+  - Skill  # For invoking child skills (/spec, /exec, /test, /qa)
   # Optional MCP tools (enhanced functionality if available)
   - mcp__chrome-devtools__*  # Browser testing - falls back to manual checklist if unavailable
   - mcp__sequential-thinking__*  # Complex reasoning - falls back to standard analysis if unavailable
@@ -90,6 +90,52 @@ When invoked as `/fullsolve <issue-number>`, execute the complete issue resoluti
 /fullsolve 218 --max-iterations 5 # Override max fix iterations
 ```
 
+## Phase Detection (Smart Resumption)
+
+**Before starting any phase**, detect the current workflow state from GitHub issue comments to enable smart resumption:
+
+```bash
+# Get all phase markers from issue comments
+comments_json=$(gh issue view <issue-number> --json comments --jq '[.comments[].body]')
+markers=$(echo "$comments_json" | grep -o '{[^}]*}' | grep '"phase"')
+
+if [[ -n "$markers" ]]; then
+  echo "Phase markers detected:"
+  echo "$markers" | jq -r '"  \(.phase): \(.status)"'
+
+  # Determine resume point
+  latest_completed=$(echo "$markers" | jq -r 'select(.status == "completed") | .phase' | tail -1)
+  latest_failed=$(echo "$markers" | jq -r 'select(.status == "failed") | .phase' | tail -1)
+
+  echo "Latest completed: ${latest_completed:-none}"
+  echo "Latest failed: ${latest_failed:-none}"
+fi
+```
+
+**Resume Logic:**
+
+| Detected State | Action |
+|---------------|--------|
+| No markers | Start from Phase 1 (spec) — fresh start |
+| `spec:completed` | Skip to Phase 2 (exec) |
+| `exec:completed` | Skip to Phase 3 (test) or Phase 4 (qa) |
+| `exec:failed` | Resume at Phase 2 (exec) — retry |
+| `test:completed` | Skip to Phase 4 (qa) |
+| `qa:completed` | Skip to Phase 5 (PR) |
+| `qa:failed` | Resume at Phase 4 (qa) — retry with /loop |
+| All completed | Skip to PR creation (if no PR exists) |
+
+**Backward Compatibility:**
+- Issues without markers → treat as fresh start (no phase detection)
+- If detection fails (API error) → fall through to standard Phase 0 checks
+
+**Phase Marker Emission:**
+
+When posting progress comments after each phase, append the appropriate marker:
+```markdown
+<!-- SEQUANT_PHASE: {"phase":"<phase>","status":"<completed|failed>","timestamp":"<ISO-8601>"} -->
+```
+
 ## Phase 0: Pre-flight Checks
 
 **CRITICAL after context restoration:** Before starting any work, verify the current git state to avoid duplicate work.

package/templates/skills/qa/SKILL.md

@@ -19,7 +19,7 @@ allowed-tools:
   - Bash(semgrep:*)
   - Bash(npx semgrep:*)
   - Bash(npx tsx scripts/semgrep-scan.ts:*)
-  - Task
+  - Task(general-purpose)
   - AgentOutputTool
 ---
 
@@ -37,6 +37,52 @@ When invoked as `/qa`, your job is to:
 4. Assess whether the change is "A+ status" or needs more work.
 5. Draft a GitHub review/QA comment summarizing findings and recommendations.
 
+## Phase Detection (Smart Resumption)
+
+**Before executing**, check if the exec phase has been completed (prerequisite for QA):
+
+```bash
+# Check for existing phase markers
+comments_json=$(gh issue view <issue-number> --json comments --jq '[.comments[].body]')
+exec_completed=$(echo "$comments_json" | \
+  grep -o '{[^}]*}' | grep '"phase"' | \
+  jq -r 'select(.phase == "exec" and .status == "completed")' 2>/dev/null)
+
+if [[ -z "$exec_completed" ]]; then
+  # Check if any exec marker exists at all
+  exec_any=$(echo "$comments_json" | \
+    grep -o '{[^}]*}' | grep '"phase"' | \
+    jq -r 'select(.phase == "exec")' 2>/dev/null)
+
+  if [[ -n "$exec_any" ]]; then
+    echo "⚠️ Exec phase not completed (status: $(echo "$exec_any" | jq -r '.status')). Run /exec first."
+  else
+    echo "ℹ️ No phase markers found — proceeding with QA (may be a fresh issue or legacy workflow)."
+  fi
+fi
+```
+
+**Behavior:**
+- If `exec:completed` marker found → Normal QA execution
+- If `exec:failed` or `exec:in_progress` → Warn "Exec not complete, run /exec first" (but don't block — QA may still be useful for partial review)
+- If no markers found → Normal execution (backward compatible)
+- If detection fails (API error) → Fall through to normal execution
+
+**Phase Marker Emission:**
+
+When posting the QA review comment to GitHub, append a phase marker at the end:
+
+```markdown
+<!-- SEQUANT_PHASE: {"phase":"qa","status":"completed","timestamp":"<ISO-8601>"} -->
+```
+
+If QA determines AC_NOT_MET, emit:
+```markdown
+<!-- SEQUANT_PHASE: {"phase":"qa","status":"failed","timestamp":"<ISO-8601>","error":"AC_NOT_MET"} -->
+```
+
+Include this marker in every `gh issue comment` that represents QA completion.
+
 ## Behavior
 
 Invocation:

package/templates/skills/security-review/SKILL.md

@@ -9,7 +9,6 @@ allowed-tools:
   - Read
   - Glob
   - Grep
-  - Task
   - Bash(git diff:*)
   - Bash(git status:*)
   - Bash(git log:*)

package/templates/skills/spec/SKILL.md

@@ -13,7 +13,7 @@ allowed-tools:
   - Bash(gh label:*)
   - Bash(git worktree:*)
   - Bash(git -C:*)
-  - Task
+  - Task(Explore)
   - AgentOutputTool
 ---
 
@@ -30,6 +30,44 @@ When invoked as `/spec`, your job is to:
 3. Identify ambiguities, gaps, or risks.
 4. Draft a GitHub issue comment summarizing AC + the agreed plan.
 
+## Phase Detection (Smart Resumption)
+
+**Before executing**, check if this phase has already been completed by reading phase markers from issue comments:
+
+```bash
+# Check for existing phase markers
+phase_data=$(gh issue view <issue-number> --json comments --jq '[.comments[].body]' | \
+  grep -o '{[^}]*}' | grep '"phase"' | tail -1)
+
+if [[ -n "$phase_data" ]]; then
+  phase=$(echo "$phase_data" | jq -r '.phase')
+  status=$(echo "$phase_data" | jq -r '.status')
+
+  # Skip if spec is already completed or a later phase is completed
+  if [[ "$phase" == "spec" && "$status" == "completed" ]] || \
+     [[ "$phase" == "exec" || "$phase" == "test" || "$phase" == "qa" ]]; then
+    echo "⏭️ Spec phase already completed (detected: $phase:$status). Skipping."
+    # Exit early — no work needed
+  fi
+fi
+```
+
+**Behavior:**
+- If `spec:completed` or a later phase is detected → Skip with message
+- If `spec:failed` → Re-run spec (retry)
+- If no markers found → Normal execution (fresh start)
+- If detection fails (API error) → Fall through to normal execution
+
+**Phase Marker Emission:**
+
+When posting the spec plan comment to GitHub, append a phase marker at the end:
+
+```markdown
+<!-- SEQUANT_PHASE: {"phase":"spec","status":"completed","timestamp":"<ISO-8601>"} -->
+```
+
+Include this marker in every `gh issue comment` that represents phase completion.
+
 ## Behavior
 
 When called like `/spec 123`:

package/templates/skills/testgen/SKILL.md

@@ -17,6 +17,7 @@ allowed-tools:
   - Bash(git worktree list:*)
   - Bash(ls:*)
   - Bash(mkdir:*)
+  - Task(general-purpose)
 ---
 
 # Test Generation Command