@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/workflow/guided-mode-injector.js

@@ -0,0 +1,191 @@
+/**
+ * Guided Mode System Prompt Injector
+ *
+ * Injects guided workflow context into the agent's system prompt.
+ * Two types of injection:
+ * - Static: General rules about guided mode behavior (added to base system prompt)
+ * - Dynamic: Current project/item/step state (injected per-session)
+ */
+import { STEP_ORDER, getStepCriteria, formatStepDisplay, getStepDescription } from './step-criteria.js';
+/**
+ * Static system prompt addition for guided mode.
+ * Added to base system prompt when a project uses guided mode.
+ */
+export const GUIDED_MODE_SYSTEM_PROMPT = `
+## Guided Workflow Mode
+
+When a project uses **guided mode**, follow these rules:
+
+1. **Work Item Focus**: Always work on the current work item unless the user explicitly requests otherwise
+2. **Step Cycle**: Progress through steps in order: ${STEP_ORDER.join(' → ')}
+3. **Step Transitions**: Use \`workitem_advance_step\` tool when the criteria for the current step are met
+4. **Visibility**: Announce step transitions clearly in conversation so the user sees progress
+5. **Flexibility**: The user can always interrupt - acknowledge and respect their requests
+6. **Test Failures**: After 2 failed test attempts, ask the user how to proceed (skip, retry, switch item)
+
+### Step Criteria
+
+- **PLAN**: Requirements understood, approach designed, target files identified
+- **IMPLEMENT**: Code written, no placeholder TODOs left, lint passes
+- **TEST**: All tests pass (or user overrides after 2 failures)
+- **COMMIT**: Changes committed with proper message, commit hash captured
+- **REVIEW**: User confirms ready for next item
+
+### Detour Handling
+
+If the user wants to work on something else mid-cycle:
+1. Acknowledge their request
+2. Optionally suggest finishing the current item (gentle challenge)
+3. If they insist, accommodate gracefully
+4. Options: pause current item, switch to different item, or switch to flexible mode
+`.trim();
+/**
+ * Generate dynamic context injection for current workflow state.
+ * Injected on startup and when project/step changes.
+ */
+export function generateDynamicContext(options) {
+    const { project, currentItem, backlogCount, inProgressCount, completedCount } = options;
+    // Base project context
+    let context = `
+## Current Workflow State
+
+**Project:** ${project.displayName} (Mode: ${project.workflowMode})
+**Lifecycle:** ${project.lifecycleState}
+**Progress:** ${String(completedCount)} completed, ${String(inProgressCount)} in progress, ${String(backlogCount)} in backlog
+`.trim();
+    // Add current item context if in guided mode with active item
+    if (project.workflowMode === 'guided' && currentItem) {
+        context += `
+
+### Current Work Item
+
+**Item:** ${currentItem.itemId} "${currentItem.title}"
+**Type:** ${currentItem.type}
+**Priority:** ${currentItem.priority}
+**Status:** ${currentItem.status}
+**Step:** ${currentItem.guidedStep ? formatStepDisplay(currentItem.guidedStep) : 'Not started'}
+${currentItem.description ? `\n**Description:**\n${currentItem.description}` : ''}
+
+### Instructions
+
+${getStepInstructions(currentItem.guidedStep)}`;
+    }
+    else if (project.workflowMode === 'guided') {
+        context += `
+
+### No Active Work Item
+
+Use \`workitem_next\` to get the highest priority item from the backlog, or ask the user which item to work on.
+Once an item is selected, set its status to 'in_progress' and begin the guided cycle.`;
+    }
+    else {
+        // Flexible mode
+        context += `
+
+### Flexible Mode
+
+Work on tasks as requested by the user. Work items are tracked but the step cycle is not enforced.
+You can still use \`workitem_advance_step\` if you want to track progress through steps.`;
+    }
+    return context;
+}
+/**
+ * Get step-specific instructions for the agent
+ */
+function getStepInstructions(step) {
+    if (!step) {
+        return `No step active. Use \`workitem_advance_step\` to start at PLAN step.`;
+    }
+    const criteria = getStepCriteria(step);
+    const stepDesc = getStepDescription(step);
+    let instructions = `You are in **${step.toUpperCase()}** step: ${stepDesc}
+
+**Exit Criteria:**
+${criteria.exitCriteria.map((c) => `- ${c}`).join('\n')}
+
+**When complete:** Use \`workitem_advance_step\` with a reason explaining why criteria are met.`;
+    // Add step-specific hints
+    switch (step) {
+        case 'plan':
+            instructions += `
+
+**Actions:**
+1. Read and understand the requirements
+2. Design the approach (what files to create/modify)
+3. Consider edge cases and potential issues
+4. Document the plan in conversation`;
+            break;
+        case 'implement':
+            instructions += `
+
+**Actions:**
+1. Create/modify files according to the plan
+2. Ensure code is complete (no TODOs unless intentional)
+3. Run lint if available and fix any issues
+4. Review your changes before advancing`;
+            break;
+        case 'test':
+            instructions += `
+
+**Actions:**
+1. Run the test suite
+2. If tests fail, analyze and fix the issues
+3. Re-run tests after fixes
+4. After 2 failed attempts, ask user how to proceed
+
+**Note:** Track failed attempts. After 2 failures, offer options:
+- Try again (you'll fix the issue)
+- Skip tests and continue to commit
+- Switch to flexible mode for this item
+- Work on a different item`;
+            break;
+        case 'commit':
+            instructions += `
+
+**Actions:**
+1. Stage the relevant changes
+2. Create a descriptive commit message
+3. Run git commit
+4. Capture the commit hash
+5. Use \`workitem_update\` to store the commit_hash on the item`;
+            break;
+        case 'review':
+            instructions += `
+
+**Actions:**
+1. Summarize what was accomplished
+2. Ask user if they're ready for the next item
+3. Wait for user confirmation before proceeding
+
+**On user confirmation:**
+- Use \`workitem_advance_step\` to complete this item
+- Then use \`workitem_next\` to get the next item`;
+            break;
+    }
+    return instructions;
+}
+/**
+ * Generate a compact status line for footer display
+ */
+export function generateStatusLine(options) {
+    const { project, currentItem } = options;
+    if (!currentItem) {
+        return `${project.displayName} | ${project.workflowMode} mode | No active item`;
+    }
+    const stepDisplay = currentItem.guidedStep
+        ? currentItem.guidedStep.toUpperCase()
+        : 'READY';
+    return `${project.displayName} | ${currentItem.itemId} | ${stepDisplay}`;
+}
+/**
+ * Check if we should inject guided mode context
+ */
+export function shouldInjectGuidedContext(project) {
+    return project !== null && project.workflowMode === 'guided';
+}
+/**
+ * Combine static and dynamic prompts for full guided mode injection
+ */
+export function getFullGuidedPrompt(options) {
+    return `${GUIDED_MODE_SYSTEM_PROMPT}\n\n${generateDynamicContext(options)}`;
+}

package/dist/workflow/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Guided Workflow Module
+ *
+ * Provides step-by-step workflow tracking for guided mode.
+ */
+export { type StepCriteria, STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, getPreviousStep, getStepNumber, isValidTransition, getStepCriteria, getStepDescription, formatStepDisplay, } from './step-criteria.js';
+export { type StepAttempt, GuidedStepTracker, stepTracker, } from './step-tracker.js';
+export { type DynamicContextOptions, GUIDED_MODE_SYSTEM_PROMPT, generateDynamicContext, generateStatusLine, shouldInjectGuidedContext, getFullGuidedPrompt, } from './guided-mode-injector.js';

package/dist/workflow/index.js

@@ -0,0 +1,8 @@
+/**
+ * Guided Workflow Module
+ *
+ * Provides step-by-step workflow tracking for guided mode.
+ */
+export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, getPreviousStep, getStepNumber, isValidTransition, getStepCriteria, getStepDescription, formatStepDisplay, } from './step-criteria.js';
+export { GuidedStepTracker, stepTracker, } from './step-tracker.js';
+export { GUIDED_MODE_SYSTEM_PROMPT, generateDynamicContext, generateStatusLine, shouldInjectGuidedContext, getFullGuidedPrompt, } from './guided-mode-injector.js';

package/dist/workflow/step-criteria.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Step Criteria - Defines exit criteria for each guided workflow step
+ *
+ * Each step has:
+ * - Human-readable exit criteria (for system prompt)
+ * - Success indicators (what agent looks for)
+ * - Configuration (max attempts, auto-advance)
+ */
+import type { GuidedStep } from '../db/schema.js';
+/**
+ * Step criteria definition
+ */
+export interface StepCriteria {
+    /** The guided step */
+    step: GuidedStep;
+    /** Human-readable exit criteria for system prompt */
+    exitCriteria: string[];
+    /** What agent looks for to determine success */
+    successIndicators: string[];
+    /** Maximum attempts for retryable steps (like test) */
+    maxAttempts?: number;
+    /** Can agent advance automatically when criteria met? */
+    autoAdvance: boolean;
+    /** Hint for next action after advancing */
+    nextActionHint: string;
+}
+/**
+ * Step order - defines valid step progression
+ */
+export declare const STEP_ORDER: readonly GuidedStep[];
+/**
+ * Get the next step in the workflow
+ */
+export declare function getNextStep(current: GuidedStep | null): GuidedStep | 'complete';
+/**
+ * Get the previous step in the workflow
+ */
+export declare function getPreviousStep(current: GuidedStep): GuidedStep | null;
+/**
+ * Get step number (1-indexed for display)
+ */
+export declare function getStepNumber(step: GuidedStep): number;
+/**
+ * Check if step transition is valid (can only advance to next step)
+ */
+export declare function isValidTransition(from: GuidedStep | null, to: GuidedStep | 'complete'): boolean;
+/**
+ * Guided step criteria definitions
+ */
+export declare const GUIDED_STEP_CRITERIA: readonly StepCriteria[];
+/**
+ * Get criteria for a specific step
+ */
+export declare function getStepCriteria(step: GuidedStep): StepCriteria;
+/**
+ * Get human-readable step description for messages
+ */
+export declare function getStepDescription(step: GuidedStep): string;
+/**
+ * Format step for display (e.g., "IMPLEMENT (2 of 5)")
+ */
+export declare function formatStepDisplay(step: GuidedStep): string;

package/dist/workflow/step-criteria.js

@@ -0,0 +1,150 @@
+/**
+ * Step Criteria - Defines exit criteria for each guided workflow step
+ *
+ * Each step has:
+ * - Human-readable exit criteria (for system prompt)
+ * - Success indicators (what agent looks for)
+ * - Configuration (max attempts, auto-advance)
+ */
+/**
+ * Step order - defines valid step progression
+ */
+export const STEP_ORDER = ['plan', 'implement', 'test', 'commit', 'review'];
+/**
+ * Get the next step in the workflow
+ */
+export function getNextStep(current) {
+    if (current === null)
+        return 'plan';
+    const idx = STEP_ORDER.indexOf(current);
+    if (idx === -1 || idx >= STEP_ORDER.length - 1)
+        return 'complete';
+    return STEP_ORDER[idx + 1];
+}
+/**
+ * Get the previous step in the workflow
+ */
+export function getPreviousStep(current) {
+    const idx = STEP_ORDER.indexOf(current);
+    if (idx <= 0)
+        return null;
+    return STEP_ORDER[idx - 1];
+}
+/**
+ * Get step number (1-indexed for display)
+ */
+export function getStepNumber(step) {
+    return STEP_ORDER.indexOf(step) + 1;
+}
+/**
+ * Check if step transition is valid (can only advance to next step)
+ */
+export function isValidTransition(from, to) {
+    const nextStep = getNextStep(from);
+    return nextStep === to;
+}
+/**
+ * Guided step criteria definitions
+ */
+export const GUIDED_STEP_CRITERIA = [
+    {
+        step: 'plan',
+        exitCriteria: [
+            'Requirements understood and documented',
+            'Approach designed (files to create/modify identified)',
+            'Edge cases considered',
+        ],
+        successIndicators: [
+            'Agent has written a plan in conversation or document',
+            'Agent has identified target files',
+            'No blocking questions remain',
+        ],
+        autoAdvance: true,
+        nextActionHint: 'Start implementing the planned changes',
+    },
+    {
+        step: 'implement',
+        exitCriteria: [
+            'All planned code changes completed',
+            'No placeholder TODOs left',
+            'Code compiles/lints cleanly',
+        ],
+        successIndicators: [
+            'writeFile/edit tools have been called',
+            'Lint command passes (if available)',
+            'No obvious errors in code',
+        ],
+        autoAdvance: true,
+        nextActionHint: 'Run tests to verify the implementation',
+    },
+    {
+        step: 'test',
+        exitCriteria: [
+            'All tests pass',
+            'OR: User overrides after 2 failed attempts',
+        ],
+        successIndicators: [
+            'Test command exits with 0',
+            'All test assertions pass',
+        ],
+        maxAttempts: 2,
+        autoAdvance: true, // Only if tests pass
+        nextActionHint: 'Commit the changes with a proper message',
+    },
+    {
+        step: 'commit',
+        exitCriteria: [
+            'Changes committed with proper message',
+            'Commit hash captured',
+        ],
+        successIndicators: [
+            'git commit command succeeded',
+            'Commit hash in output',
+        ],
+        autoAdvance: true,
+        nextActionHint: 'Review and confirm ready for next item',
+    },
+    {
+        step: 'review',
+        exitCriteria: [
+            'User confirms ready for next item',
+            'OR: User wants to do something else',
+        ],
+        successIndicators: [
+            'User says "yes", "next", "continue"',
+            'User explicitly approves',
+        ],
+        autoAdvance: false, // Always wait for user
+        nextActionHint: 'Pick the next work item from backlog',
+    },
+];
+/**
+ * Get criteria for a specific step
+ */
+export function getStepCriteria(step) {
+    const criteria = GUIDED_STEP_CRITERIA.find((c) => c.step === step);
+    if (!criteria) {
+        throw new Error(`No criteria found for step: ${step}`);
+    }
+    return criteria;
+}
+/**
+ * Get human-readable step description for messages
+ */
+export function getStepDescription(step) {
+    const descriptions = {
+        plan: 'Planning - understanding requirements and designing approach',
+        implement: 'Implementing - writing code and making changes',
+        test: 'Testing - running tests and fixing failures',
+        commit: 'Committing - creating git commit with changes',
+        review: 'Reviewing - confirming completion and next steps',
+    };
+    return descriptions[step];
+}
+/**
+ * Format step for display (e.g., "IMPLEMENT (2 of 5)")
+ */
+export function formatStepDisplay(step) {
+    const num = getStepNumber(step);
+    return `${step.toUpperCase()} (${String(num)} of ${String(STEP_ORDER.length)})`;
+}

package/dist/workflow/step-tracker.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Step Tracker - In-memory tracking of step attempts
+ *
+ * Tracks attempts for retryable steps (like test) during a session.
+ * This is in-memory only - resets on CLI restart.
+ * Can be persisted to history table later if needed.
+ */
+import type { GuidedStep } from '../db/schema.js';
+/**
+ * Record of a single step attempt
+ */
+export interface StepAttempt {
+    /** When the attempt was made */
+    timestamp: Date;
+    /** Whether the attempt succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Additional context */
+    context?: string;
+}
+/**
+ * In-memory tracker for guided workflow step attempts
+ *
+ * Tracks attempts per item per step, enabling retry logic
+ * (e.g., "tests failed after 2 attempts, ask user").
+ */
+export declare class GuidedStepTracker {
+    /**
+     * Map: itemId -> step -> attempts[]
+     */
+    private readonly attempts;
+    /**
+     * Record an attempt for a step
+     */
+    recordAttempt(itemId: string, step: GuidedStep, success: boolean, error?: string, context?: string): void;
+    /**
+     * Get all attempts for a step
+     */
+    getAttempts(itemId: string, step: GuidedStep): StepAttempt[];
+    /**
+     * Get total attempt count for a step
+     */
+    getAttemptCount(itemId: string, step: GuidedStep): number;
+    /**
+     * Get failed attempt count for a step
+     */
+    getFailedAttemptCount(itemId: string, step: GuidedStep): number;
+    /**
+     * Get successful attempt count for a step
+     */
+    getSuccessfulAttemptCount(itemId: string, step: GuidedStep): number;
+    /**
+     * Check if we should escalate to user (max attempts exceeded)
+     */
+    shouldAskUser(itemId: string, step: GuidedStep, maxAttempts?: number): boolean;
+    /**
+     * Get remaining attempts before user escalation
+     */
+    getRemainingAttempts(itemId: string, step: GuidedStep): number | null;
+    /**
+     * Check if step has had any successful attempt
+     */
+    hasSucceeded(itemId: string, step: GuidedStep): boolean;
+    /**
+     * Get the last attempt for a step
+     */
+    getLastAttempt(itemId: string, step: GuidedStep): StepAttempt | null;
+    /**
+     * Reset attempts for a specific item (when starting fresh)
+     */
+    resetItem(itemId: string): void;
+    /**
+     * Reset attempts for a specific step (when user wants to retry)
+     */
+    resetStep(itemId: string, step: GuidedStep): void;
+    /**
+     * Clear all tracking data (e.g., on session end)
+     */
+    clear(): void;
+    /**
+     * Get a summary of attempts for an item (for display)
+     */
+    getItemSummary(itemId: string): Record<GuidedStep, {
+        total: number;
+        failed: number;
+    }> | null;
+}
+/**
+ * Singleton instance for the current session
+ */
+export declare const stepTracker: GuidedStepTracker;

package/dist/workflow/step-tracker.js

@@ -0,0 +1,141 @@
+/**
+ * Step Tracker - In-memory tracking of step attempts
+ *
+ * Tracks attempts for retryable steps (like test) during a session.
+ * This is in-memory only - resets on CLI restart.
+ * Can be persisted to history table later if needed.
+ */
+import { getStepCriteria } from './step-criteria.js';
+/**
+ * In-memory tracker for guided workflow step attempts
+ *
+ * Tracks attempts per item per step, enabling retry logic
+ * (e.g., "tests failed after 2 attempts, ask user").
+ */
+export class GuidedStepTracker {
+    /**
+     * Map: itemId -> step -> attempts[]
+     */
+    attempts = new Map();
+    /**
+     * Record an attempt for a step
+     */
+    recordAttempt(itemId, step, success, error, context) {
+        if (!this.attempts.has(itemId)) {
+            this.attempts.set(itemId, new Map());
+        }
+        const itemAttempts = this.attempts.get(itemId);
+        if (!itemAttempts)
+            return; // Should never happen, just added above
+        if (!itemAttempts.has(step)) {
+            itemAttempts.set(step, []);
+        }
+        const stepAttempts = itemAttempts.get(step);
+        if (!stepAttempts)
+            return; // Should never happen, just added above
+        stepAttempts.push({
+            timestamp: new Date(),
+            success,
+            error,
+            context,
+        });
+    }
+    /**
+     * Get all attempts for a step
+     */
+    getAttempts(itemId, step) {
+        return this.attempts.get(itemId)?.get(step) ?? [];
+    }
+    /**
+     * Get total attempt count for a step
+     */
+    getAttemptCount(itemId, step) {
+        return this.getAttempts(itemId, step).length;
+    }
+    /**
+     * Get failed attempt count for a step
+     */
+    getFailedAttemptCount(itemId, step) {
+        return this.getAttempts(itemId, step).filter((a) => !a.success).length;
+    }
+    /**
+     * Get successful attempt count for a step
+     */
+    getSuccessfulAttemptCount(itemId, step) {
+        return this.getAttempts(itemId, step).filter((a) => a.success).length;
+    }
+    /**
+     * Check if we should escalate to user (max attempts exceeded)
+     */
+    shouldAskUser(itemId, step, maxAttempts) {
+        const criteria = getStepCriteria(step);
+        const max = maxAttempts ?? criteria.maxAttempts;
+        if (max === undefined) {
+            // No retry limit defined for this step
+            return false;
+        }
+        return this.getFailedAttemptCount(itemId, step) >= max;
+    }
+    /**
+     * Get remaining attempts before user escalation
+     */
+    getRemainingAttempts(itemId, step) {
+        const criteria = getStepCriteria(step);
+        if (criteria.maxAttempts === undefined) {
+            return null; // No limit
+        }
+        return Math.max(0, criteria.maxAttempts - this.getFailedAttemptCount(itemId, step));
+    }
+    /**
+     * Check if step has had any successful attempt
+     */
+    hasSucceeded(itemId, step) {
+        return this.getSuccessfulAttemptCount(itemId, step) > 0;
+    }
+    /**
+     * Get the last attempt for a step
+     */
+    getLastAttempt(itemId, step) {
+        const attempts = this.getAttempts(itemId, step);
+        return attempts.length > 0 ? attempts[attempts.length - 1] : null;
+    }
+    /**
+     * Reset attempts for a specific item (when starting fresh)
+     */
+    resetItem(itemId) {
+        this.attempts.delete(itemId);
+    }
+    /**
+     * Reset attempts for a specific step (when user wants to retry)
+     */
+    resetStep(itemId, step) {
+        this.attempts.get(itemId)?.delete(step);
+    }
+    /**
+     * Clear all tracking data (e.g., on session end)
+     */
+    clear() {
+        this.attempts.clear();
+    }
+    /**
+     * Get a summary of attempts for an item (for display)
+     */
+    getItemSummary(itemId) {
+        const itemAttempts = this.attempts.get(itemId);
+        if (!itemAttempts) {
+            return null;
+        }
+        const summary = {};
+        for (const [step, attempts] of itemAttempts) {
+            summary[step] = {
+                total: attempts.length,
+                failed: attempts.filter((a) => !a.success).length,
+            };
+        }
+        return summary;
+    }
+}
+/**
+ * Singleton instance for the current session
+ */
+export const stepTracker = new GuidedStepTracker();