devsquad-ai 1.0.0

package/dist/features/background-agent/background-task-notification-template.d.ts

@@ -0,0 +1,10 @@
+import type { BackgroundTask } from "./types";
+export type BackgroundTaskNotificationStatus = "COMPLETED" | "CANCELLED" | "INTERRUPTED";
+export declare function buildBackgroundTaskNotificationText(input: {
+    task: BackgroundTask;
+    duration: string;
+    statusText: BackgroundTaskNotificationStatus;
+    allComplete: boolean;
+    remainingCount: number;
+    completedTasks: BackgroundTask[];
+}): string;

package/dist/features/background-agent/compaction-aware-message-resolver.d.ts

@@ -0,0 +1,3 @@
+import type { StoredMessage } from "../hook-message-injector";
+export declare function isCompactionAgent(agent: string | undefined): boolean;
+export declare function findNearestMessageExcludingCompaction(messageDir: string): StoredMessage | null;

package/dist/features/background-agent/concurrency.d.ts

@@ -0,0 +1,27 @@
+import type { BackgroundTaskConfig } from "../../config/schema";
+export declare class ConcurrencyManager {
+    private config?;
+    private counts;
+    private queues;
+    constructor(config?: BackgroundTaskConfig);
+    getConcurrencyLimit(model: string): number;
+    acquire(model: string): Promise<void>;
+    release(model: string): void;
+    /**
+     * Cancel all waiting acquires for a model. Used during cleanup.
+     */
+    cancelWaiters(model: string): void;
+    /**
+     * Clear all state. Used during manager cleanup/shutdown.
+     * Cancels all pending waiters.
+     */
+    clear(): void;
+    /**
+     * Get current count for a model (for testing/debugging)
+     */
+    getCount(model: string): number;
+    /**
+     * Get queue length for a model (for testing/debugging)
+     */
+    getQueueLength(model: string): number;
+}

package/dist/features/background-agent/constants.d.ts

@@ -0,0 +1,45 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { BackgroundTask, LaunchInput } from "./types";
+export declare const TASK_TTL_MS: number;
+export declare const MIN_STABILITY_TIME_MS: number;
+export declare const DEFAULT_STALE_TIMEOUT_MS = 180000;
+export declare const DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS = 600000;
+export declare const MIN_RUNTIME_BEFORE_STALE_MS = 30000;
+export declare const MIN_IDLE_TIME_MS = 5000;
+export declare const POLLING_INTERVAL_MS = 3000;
+export declare const TASK_CLEANUP_DELAY_MS: number;
+export declare const TMUX_CALLBACK_DELAY_MS = 200;
+export type ProcessCleanupEvent = NodeJS.Signals | "beforeExit" | "exit";
+export type OpencodeClient = PluginInput["client"];
+export interface MessagePartInfo {
+    sessionID?: string;
+    type?: string;
+    tool?: string;
+}
+export interface EventProperties {
+    sessionID?: string;
+    info?: {
+        id?: string;
+    };
+    [key: string]: unknown;
+}
+export interface BackgroundEvent {
+    type: string;
+    properties?: EventProperties;
+}
+export interface Todo {
+    content: string;
+    status: string;
+    priority: string;
+    id?: string;
+}
+export interface QueueItem {
+    task: BackgroundTask;
+    input: LaunchInput;
+}
+export interface SubagentSessionCreatedEvent {
+    sessionID: string;
+    parentID: string;
+    title: string;
+}
+export type OnSubagentSessionCreated = (event: SubagentSessionCreatedEvent) => Promise<void>;

package/dist/features/background-agent/duration-formatter.d.ts

@@ -0,0 +1 @@
+export declare function formatDuration(start: Date, end?: Date): string;

package/dist/features/background-agent/error-classifier.d.ts

@@ -0,0 +1,10 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isAbortedSessionError(error: unknown): boolean;
+export declare function getErrorText(error: unknown): string;
+export declare function extractErrorName(error: unknown): string | undefined;
+export declare function extractErrorMessage(error: unknown): string | undefined;
+interface EventPropertiesLike {
+    [key: string]: unknown;
+}
+export declare function getSessionErrorMessage(properties: EventPropertiesLike): string | undefined;
+export {};

package/dist/features/background-agent/fallback-retry-handler.d.ts

@@ -0,0 +1,16 @@
+import type { BackgroundTask } from "./types";
+import type { ConcurrencyManager } from "./concurrency";
+import type { OpencodeClient, QueueItem } from "./constants";
+export declare function tryFallbackRetry(args: {
+    task: BackgroundTask;
+    errorInfo: {
+        name?: string;
+        message?: string;
+    };
+    source: string;
+    concurrencyManager: ConcurrencyManager;
+    client: OpencodeClient;
+    idleDeferralTimers: Map<string, ReturnType<typeof setTimeout>>;
+    queuesByKey: Map<string, QueueItem[]>;
+    processKey: (key: string) => void;
+}): boolean;

package/dist/features/background-agent/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export { BackgroundManager, type SubagentSessionCreatedEvent, type OnSubagentSessionCreated } from "./manager";

package/dist/features/background-agent/manager.d.ts

@@ -0,0 +1,131 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { BackgroundTask, LaunchInput, ResumeInput } from "./types";
+import { TaskHistory } from "./task-history";
+import type { BackgroundTaskConfig, TmuxConfig } from "../../config/schema";
+interface EventProperties {
+    sessionID?: string;
+    info?: {
+        id?: string;
+    };
+    [key: string]: unknown;
+}
+interface Event {
+    type: string;
+    properties?: EventProperties;
+}
+export interface SubagentSessionCreatedEvent {
+    sessionID: string;
+    parentID: string;
+    title: string;
+}
+export type OnSubagentSessionCreated = (event: SubagentSessionCreatedEvent) => Promise<void>;
+export declare class BackgroundManager {
+    private tasks;
+    private notifications;
+    private pendingByParent;
+    private client;
+    private directory;
+    private pollingInterval?;
+    private pollingInFlight;
+    private concurrencyManager;
+    private shutdownTriggered;
+    private config?;
+    private tmuxEnabled;
+    private onSubagentSessionCreated?;
+    private onShutdown?;
+    private queuesByKey;
+    private processingKeys;
+    private completionTimers;
+    private idleDeferralTimers;
+    private notificationQueueByParent;
+    private enableParentSessionNotifications;
+    readonly taskHistory: TaskHistory;
+    constructor(ctx: PluginInput, config?: BackgroundTaskConfig, options?: {
+        tmuxConfig?: TmuxConfig;
+        onSubagentSessionCreated?: OnSubagentSessionCreated;
+        onShutdown?: () => void;
+        enableParentSessionNotifications?: boolean;
+    });
+    launch(input: LaunchInput): Promise<BackgroundTask>;
+    private processKey;
+    private startTask;
+    getTask(id: string): BackgroundTask | undefined;
+    getTasksByParentSession(sessionID: string): BackgroundTask[];
+    getAllDescendantTasks(sessionID: string): BackgroundTask[];
+    findBySession(sessionID: string): BackgroundTask | undefined;
+    private getConcurrencyKeyFromInput;
+    /**
+     * Track a task created elsewhere (e.g., from task) for notification tracking.
+     * This allows tasks created by other tools to receive the same toast/prompt notifications.
+     */
+    trackTask(input: {
+        taskId: string;
+        sessionID: string;
+        parentSessionID: string;
+        description: string;
+        agent?: string;
+        parentAgent?: string;
+        concurrencyKey?: string;
+    }): Promise<BackgroundTask>;
+    resume(input: ResumeInput): Promise<BackgroundTask>;
+    private checkSessionTodos;
+    handleEvent(event: Event): void;
+    private tryFallbackRetry;
+    markForNotification(task: BackgroundTask): void;
+    getPendingNotifications(sessionID: string): BackgroundTask[];
+    clearNotifications(sessionID: string): void;
+    /**
+     * Validates that a session has actual assistant/tool output before marking complete.
+     * Prevents premature completion when session.idle fires before agent responds.
+     */
+    private validateSessionHasOutput;
+    private clearNotificationsForTask;
+    /**
+     * Remove task from pending tracking for its parent session.
+     * Cleans up the parent entry if no pending tasks remain.
+     */
+    private cleanupPendingByParent;
+    cancelTask(taskId: string, options?: {
+        source?: string;
+        reason?: string;
+        abortSession?: boolean;
+        skipNotification?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Cancels a pending task by removing it from queue and marking as cancelled.
+     * Does NOT abort session (no session exists yet) or release concurrency slot (wasn't acquired).
+     */
+    cancelPendingTask(taskId: string): boolean;
+    private startPolling;
+    private stopPolling;
+    private registerProcessCleanup;
+    private unregisterProcessCleanup;
+    /**
+     * Get all running tasks (for compaction hook)
+     */
+    getRunningTasks(): BackgroundTask[];
+    /**
+     * Get all non-running tasks still in memory (for compaction hook)
+     */
+    getNonRunningTasks(): BackgroundTask[];
+    /**
+     * Safely complete a task with race condition protection.
+     * Returns true if task was successfully completed, false if already completed by another path.
+     */
+    private tryCompleteTask;
+    private notifyParentSession;
+    private formatDuration;
+    private isAbortedSessionError;
+    private hasRunningTasks;
+    private pruneStaleTasksAndNotifications;
+    private checkAndInterruptStaleTasks;
+    private pollRunningTasks;
+    /**
+     * Shutdown the manager gracefully.
+     * Cancels all pending concurrency waiters and clears timers.
+     * Should be called when the plugin is unloaded.
+     */
+    shutdown(): void;
+    private enqueueNotificationForParent;
+}
+export {};

package/dist/features/background-agent/opencode-client.d.ts

@@ -0,0 +1,2 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export type OpencodeClient = PluginInput["client"];

package/dist/features/background-agent/process-cleanup.d.ts

@@ -0,0 +1,8 @@
+interface CleanupTarget {
+    shutdown(): void;
+}
+export declare function registerManagerForCleanup(manager: CleanupTarget): void;
+export declare function unregisterManagerForCleanup(manager: CleanupTarget): void;
+/** @internal — test-only reset for module-level singleton state */
+export declare function _resetForTesting(): void;
+export {};

package/dist/features/background-agent/session-idle-event-handler.d.ts

@@ -0,0 +1,10 @@
+import type { BackgroundTask } from "./types";
+export declare function handleSessionIdleBackgroundEvent(args: {
+    properties: Record<string, unknown>;
+    findBySession: (sessionID: string) => BackgroundTask | undefined;
+    idleDeferralTimers: Map<string, ReturnType<typeof setTimeout>>;
+    validateSessionHasOutput: (sessionID: string) => Promise<boolean>;
+    checkSessionTodos: (sessionID: string) => Promise<boolean>;
+    tryCompleteTask: (task: BackgroundTask, source: string) => Promise<boolean>;
+    emitIdleEvent: (sessionID: string) => void;
+}): void;

package/dist/features/background-agent/spawner/parent-directory-resolver.d.ts

@@ -0,0 +1,6 @@
+import type { OpencodeClient } from "../constants";
+export declare function resolveParentDirectory(options: {
+    client: OpencodeClient;
+    parentSessionID: string;
+    defaultDirectory: string;
+}): Promise<string>;

package/dist/features/background-agent/spawner.d.ts

@@ -0,0 +1,14 @@
+import type { BackgroundTask, LaunchInput, ResumeInput } from "./types";
+import type { OpencodeClient, OnSubagentSessionCreated, QueueItem } from "./constants";
+import type { ConcurrencyManager } from "./concurrency";
+export interface SpawnerContext {
+    client: OpencodeClient;
+    directory: string;
+    concurrencyManager: ConcurrencyManager;
+    tmuxEnabled: boolean;
+    onSubagentSessionCreated?: OnSubagentSessionCreated;
+    onTaskError: (task: BackgroundTask, error: Error) => void;
+}
+export declare function createTask(input: LaunchInput): BackgroundTask;
+export declare function startTask(item: QueueItem, ctx: SpawnerContext): Promise<void>;
+export declare function resumeTask(task: BackgroundTask, input: ResumeInput, ctx: Pick<SpawnerContext, "client" | "concurrencyManager" | "onTaskError">): Promise<void>;

package/dist/features/background-agent/state.d.ts

@@ -0,0 +1,35 @@
+import type { BackgroundTask, LaunchInput } from "./types";
+import type { QueueItem } from "./constants";
+export declare class TaskStateManager {
+    readonly tasks: Map<string, BackgroundTask>;
+    readonly notifications: Map<string, BackgroundTask[]>;
+    readonly pendingByParent: Map<string, Set<string>>;
+    readonly queuesByKey: Map<string, QueueItem[]>;
+    readonly processingKeys: Set<string>;
+    readonly completionTimers: Map<string, ReturnType<typeof setTimeout>>;
+    getTask(id: string): BackgroundTask | undefined;
+    findBySession(sessionID: string): BackgroundTask | undefined;
+    getTasksByParentSession(sessionID: string): BackgroundTask[];
+    getAllDescendantTasks(sessionID: string): BackgroundTask[];
+    getRunningTasks(): BackgroundTask[];
+    getNonRunningTasks(): BackgroundTask[];
+    hasRunningTasks(): boolean;
+    getConcurrencyKeyFromInput(input: LaunchInput): string;
+    getConcurrencyKeyFromTask(task: BackgroundTask): string;
+    addTask(task: BackgroundTask): void;
+    removeTask(taskId: string): void;
+    trackPendingTask(parentSessionID: string, taskId: string): void;
+    cleanupPendingByParent(task: BackgroundTask): void;
+    markForNotification(task: BackgroundTask): void;
+    getPendingNotifications(sessionID: string): BackgroundTask[];
+    clearNotifications(sessionID: string): void;
+    clearNotificationsForTask(taskId: string): void;
+    addToQueue(key: string, item: QueueItem): void;
+    getQueue(key: string): QueueItem[] | undefined;
+    removeFromQueue(key: string, taskId: string): boolean;
+    setCompletionTimer(taskId: string, timer: ReturnType<typeof setTimeout>): void;
+    clearCompletionTimer(taskId: string): void;
+    clearAllCompletionTimers(): void;
+    clear(): void;
+    cancelPendingTask(taskId: string): boolean;
+}

package/dist/features/background-agent/task-history.d.ts

@@ -0,0 +1,18 @@
+import type { BackgroundTaskStatus } from "./types";
+export interface TaskHistoryEntry {
+    id: string;
+    sessionID?: string;
+    agent: string;
+    description: string;
+    status: BackgroundTaskStatus;
+    category?: string;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+export declare class TaskHistory {
+    private entries;
+    record(parentSessionID: string | undefined, entry: TaskHistoryEntry): void;
+    getByParentSession(parentSessionID: string): TaskHistoryEntry[];
+    clearSession(parentSessionID: string): void;
+    formatForCompaction(parentSessionID: string): string | null;
+}

package/dist/features/background-agent/task-poller.d.ts

@@ -0,0 +1,20 @@
+import type { BackgroundTaskConfig } from "../../config/schema";
+import type { BackgroundTask } from "./types";
+import type { ConcurrencyManager } from "./concurrency";
+import type { OpencodeClient } from "./opencode-client";
+export declare function pruneStaleTasksAndNotifications(args: {
+    tasks: Map<string, BackgroundTask>;
+    notifications: Map<string, BackgroundTask[]>;
+    onTaskPruned: (taskId: string, task: BackgroundTask, errorMessage: string) => void;
+}): void;
+export type SessionStatusMap = Record<string, {
+    type: string;
+}>;
+export declare function checkAndInterruptStaleTasks(args: {
+    tasks: Iterable<BackgroundTask>;
+    client: OpencodeClient;
+    config: BackgroundTaskConfig | undefined;
+    concurrencyManager: ConcurrencyManager;
+    notifyParentSession: (task: BackgroundTask) => Promise<void>;
+    sessionStatuses?: SessionStatusMap;
+}): Promise<void>;

package/dist/features/background-agent/types.d.ts

@@ -0,0 +1,90 @@
+import type { FallbackEntry } from "../../shared/model-requirements";
+export type BackgroundTaskStatus = "pending" | "running" | "completed" | "error" | "cancelled" | "interrupt";
+export interface TaskProgress {
+    toolCalls: number;
+    lastTool?: string;
+    lastUpdate: Date;
+    lastMessage?: string;
+    lastMessageAt?: Date;
+}
+export interface BackgroundTask {
+    id: string;
+    sessionID?: string;
+    parentSessionID: string;
+    parentMessageID: string;
+    description: string;
+    prompt: string;
+    agent: string;
+    status: BackgroundTaskStatus;
+    queuedAt?: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+    result?: string;
+    error?: string;
+    progress?: TaskProgress;
+    parentModel?: {
+        providerID: string;
+        modelID: string;
+    };
+    model?: {
+        providerID: string;
+        modelID: string;
+        variant?: string;
+    };
+    /** Fallback chain for runtime retry on model errors */
+    fallbackChain?: FallbackEntry[];
+    /** Number of fallback retry attempts made */
+    attemptCount?: number;
+    /** Active concurrency slot key */
+    concurrencyKey?: string;
+    /** Persistent key for re-acquiring concurrency on resume */
+    concurrencyGroup?: string;
+    /** Parent session's agent name for notification */
+    parentAgent?: string;
+    /** Parent session's tool restrictions for notification prompts */
+    parentTools?: Record<string, boolean>;
+    /** Marks if the task was launched from an unstable agent/category */
+    isUnstableAgent?: boolean;
+    /** Category used for this task (e.g., 'quick', 'visual-engineering') */
+    category?: string;
+    /** Last message count for stability detection */
+    lastMsgCount?: number;
+    /** Number of consecutive polls with stable message count */
+    stablePolls?: number;
+}
+export interface LaunchInput {
+    description: string;
+    prompt: string;
+    agent: string;
+    parentSessionID: string;
+    parentMessageID: string;
+    parentModel?: {
+        providerID: string;
+        modelID: string;
+    };
+    parentAgent?: string;
+    parentTools?: Record<string, boolean>;
+    model?: {
+        providerID: string;
+        modelID: string;
+        variant?: string;
+    };
+    /** Fallback chain for runtime retry on model errors */
+    fallbackChain?: FallbackEntry[];
+    isUnstableAgent?: boolean;
+    skills?: string[];
+    skillContent?: string;
+    category?: string;
+}
+export interface ResumeInput {
+    sessionId: string;
+    prompt: string;
+    parentSessionID: string;
+    parentMessageID: string;
+    parentModel?: {
+        providerID: string;
+        modelID: string;
+    };
+    parentAgent?: string;
+    parentTools?: Record<string, boolean>;
+}

package/dist/features/boulder-state/constants.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Boulder State Constants
+ */
+export declare const BOULDER_DIR = ".sisyphus";
+export declare const BOULDER_FILE = "boulder.json";
+export declare const BOULDER_STATE_PATH = ".sisyphus/boulder.json";
+export declare const NOTEPAD_DIR = "notepads";
+export declare const NOTEPAD_BASE_PATH = ".sisyphus/notepads";
+/** Prometheus plan directory pattern */
+export declare const PROMETHEUS_PLANS_DIR = ".sisyphus/plans";

package/dist/features/boulder-state/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./constants";
+export * from "./storage";

package/dist/features/boulder-state/storage.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Boulder State Storage
+ *
+ * Handles reading/writing boulder.json for active plan tracking.
+ */
+import type { BoulderState, PlanProgress } from "./types";
+export declare function getBoulderFilePath(directory: string): string;
+export declare function readBoulderState(directory: string): BoulderState | null;
+export declare function writeBoulderState(directory: string, state: BoulderState): boolean;
+export declare function appendSessionId(directory: string, sessionId: string): BoulderState | null;
+export declare function clearBoulderState(directory: string): boolean;
+/**
+ * Find Prometheus plan files for this project.
+ * Prometheus stores plans at: {project}/.sisyphus/plans/{name}.md
+ */
+export declare function findPrometheusPlans(directory: string): string[];
+/**
+ * Parse a plan file and count checkbox progress.
+ */
+export declare function getPlanProgress(planPath: string): PlanProgress;
+/**
+ * Extract plan name from file path.
+ */
+export declare function getPlanName(planPath: string): string;
+/**
+ * Create a new boulder state for a plan.
+ */
+export declare function createBoulderState(planPath: string, sessionId: string, agent?: string): BoulderState;

package/dist/features/boulder-state/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Boulder State Types
+ *
+ * Manages the active work plan state for Sisyphus orchestrator.
+ * Named after Sisyphus's boulder - the eternal task that must be rolled.
+ */
+export interface BoulderState {
+    /** Absolute path to the active plan file */
+    active_plan: string;
+    /** ISO timestamp when work started */
+    started_at: string;
+    /** Session IDs that have worked on this plan */
+    session_ids: string[];
+    /** Plan name derived from filename */
+    plan_name: string;
+    /** Agent type to use when resuming (e.g., 'atlas') */
+    agent?: string;
+}
+export interface PlanProgress {
+    /** Total number of checkboxes */
+    total: number;
+    /** Number of completed checkboxes */
+    completed: number;
+    /** Whether all tasks are done */
+    isComplete: boolean;
+}

package/dist/features/builtin-commands/commands.d.ts

@@ -0,0 +1,2 @@
+import type { BuiltinCommandName, BuiltinCommands } from "./types";
+export declare function loadBuiltinCommands(disabledCommands?: BuiltinCommandName[]): BuiltinCommands;

package/dist/features/builtin-commands/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./commands";

package/dist/features/builtin-commands/templates/handoff.d.ts

@@ -0,0 +1 @@
+export declare const HANDOFF_TEMPLATE = "# Handoff Command\n\n## Purpose\n\nUse /handoff when:\n- The current session context is getting too long and quality is degrading\n- You want to start fresh while preserving essential context from this session\n- The context window is approaching capacity\n\nThis creates a detailed context summary that can be used to continue work in a new session.\n\n---\n\n# PHASE 0: VALIDATE REQUEST\n\nBefore proceeding, confirm:\n- [ ] There is meaningful work or context in this session to preserve\n- [ ] The user wants to create a handoff summary (not just asking about it)\n\nIf the session is nearly empty or has no meaningful context, inform the user there is nothing substantial to hand off.\n\n---\n\n# PHASE 1: GATHER PROGRAMMATIC CONTEXT\n\nExecute these tools to gather concrete data:\n\n1. session_read({ session_id: \"$SESSION_ID\" }) \u2014 full session history\n2. todoread() \u2014 current task progress\n3. Bash({ command: \"git diff --stat HEAD~10..HEAD\" }) \u2014 recent file changes\n4. Bash({ command: \"git status --porcelain\" }) \u2014 uncommitted changes\n\nSuggested execution order:\n\n```\nsession_read({ session_id: \"$SESSION_ID\" })\ntodoread()\nBash({ command: \"git diff --stat HEAD~10..HEAD\" })\nBash({ command: \"git status --porcelain\" })\n```\n\nAnalyze the gathered outputs to understand:\n- What the user asked for (exact wording)\n- What work was completed\n- What tasks remain incomplete (include todo state)\n- What decisions were made\n- What files were modified or discussed (include git diff/stat + status)\n- What patterns, constraints, or preferences were established\n\n---\n\n# PHASE 2: EXTRACT CONTEXT\n\nWrite the context summary from first person perspective (\"I did...\", \"I told you...\").\n\nFocus on:\n- Capabilities and behavior, not file-by-file implementation details\n- What matters for continuing the work\n- Avoiding excessive implementation details (variable names, storage keys, constants) unless critical\n- USER REQUESTS (AS-IS) must be verbatim (do not paraphrase)\n- EXPLICIT CONSTRAINTS must be verbatim only (do not invent)\n\nQuestions to consider when extracting:\n- What did I just do or implement?\n- What instructions did I already give which are still relevant (e.g. follow patterns in the codebase)?\n- What files did I tell you are important or that I am working on?\n- Did I provide a plan or spec that should be included?\n- What did I already tell you that is important (libraries, patterns, constraints, preferences)?\n- What important technical details did I discover (APIs, methods, patterns)?\n- What caveats, limitations, or open questions did I find?\n\n---\n\n# PHASE 3: FORMAT OUTPUT\n\nGenerate a handoff summary using this exact format:\n\n```\nHANDOFF CONTEXT\n===============\n\nUSER REQUESTS (AS-IS)\n---------------------\n- [Exact verbatim user requests - NOT paraphrased]\n\nGOAL\n----\n[One sentence describing what should be done next]\n\nWORK COMPLETED\n--------------\n- [First person bullet points of what was done]\n- [Include specific file paths when relevant]\n- [Note key implementation decisions]\n\nCURRENT STATE\n-------------\n- [Current state of the codebase or task]\n- [Build/test status if applicable]\n- [Any environment or configuration state]\n\nPENDING TASKS\n-------------\n- [Tasks that were planned but not completed]\n- [Next logical steps to take]\n- [Any blockers or issues encountered]\n- [Include current todo state from todoread()]\n\nKEY FILES\n---------\n- [path/to/file1] - [brief role description]\n- [path/to/file2] - [brief role description]\n(Maximum 10 files, prioritized by importance)\n- (Include files from git diff/stat and git status)\n\nIMPORTANT DECISIONS\n-------------------\n- [Technical decisions that were made and why]\n- [Trade-offs that were considered]\n- [Patterns or conventions established]\n\nEXPLICIT CONSTRAINTS\n--------------------\n- [Verbatim constraints only - from user or existing AGENTS.md]\n- If none, write: None\n\nCONTEXT FOR CONTINUATION\n------------------------\n- [What the next session needs to know to continue]\n- [Warnings or gotchas to be aware of]\n- [References to documentation if relevant]\n```\n\nRules for the summary:\n- Plain text with bullets\n- No markdown headers with # (use the format above with dashes)\n- No bold, italic, or code fences within content\n- Use workspace-relative paths for files\n- Keep it focused - only include what matters for continuation\n- Pick an appropriate length based on complexity\n- USER REQUESTS (AS-IS) and EXPLICIT CONSTRAINTS must be verbatim only\n\n---\n\n# PHASE 4: PROVIDE INSTRUCTIONS\n\nAfter generating the summary, instruct the user:\n\n```\n---\n\nTO CONTINUE IN A NEW SESSION:\n\n1. Press 'n' in OpenCode TUI to open a new session, or run 'opencode' in a new terminal\n2. Paste the HANDOFF CONTEXT above as your first message\n3. Add your request: \"Continue from the handoff context above. [Your next task]\"\n\nThe new session will have all context needed to continue seamlessly.\n```\n\n---\n\n# IMPORTANT CONSTRAINTS\n\n- DO NOT attempt to programmatically create new sessions (no API available to agents)\n- DO provide a self-contained summary that works without access to this session\n- DO include workspace-relative file paths\n- DO NOT include sensitive information (API keys, credentials, secrets)\n- DO NOT exceed 10 files in the KEY FILES section\n- DO keep the GOAL section to a single sentence or short paragraph\n\n---\n\n# EXECUTE NOW\n\nBegin by gathering programmatic context, then synthesize the handoff summary.\n";

package/dist/features/builtin-commands/templates/init-deep.d.ts

@@ -0,0 +1 @@
+export declare const INIT_DEEP_TEMPLATE = "# /init-deep\n\nGenerate hierarchical AGENTS.md files. Root + complexity-scored subdirectories.\n\n## Usage\n\n```\n/init-deep                      # Update mode: modify existing + create new where warranted\n/init-deep --create-new         # Read existing \u2192 remove all \u2192 regenerate from scratch\n/init-deep --max-depth=2        # Limit directory depth (default: 3)\n```\n\n---\n\n## Workflow (High-Level)\n\n1. **Discovery + Analysis** (concurrent)\n   - Fire background explore agents immediately\n   - Main session: bash structure + LSP codemap + read existing AGENTS.md\n2. **Score & Decide** - Determine AGENTS.md locations from merged findings\n3. **Generate** - Root first, then subdirs in parallel\n4. **Review** - Deduplicate, trim, validate\n\n<critical>\n**TodoWrite ALL phases. Mark in_progress \u2192 completed in real-time.**\n```\nTodoWrite([\n  { id: \"discovery\", content: \"Fire explore agents + LSP codemap + read existing\", status: \"pending\", priority: \"high\" },\n  { id: \"scoring\", content: \"Score directories, determine locations\", status: \"pending\", priority: \"high\" },\n  { id: \"generate\", content: \"Generate AGENTS.md files (root + subdirs)\", status: \"pending\", priority: \"high\" },\n  { id: \"review\", content: \"Deduplicate, validate, trim\", status: \"pending\", priority: \"medium\" }\n])\n```\n</critical>\n\n---\n\n## Phase 1: Discovery + Analysis (Concurrent)\n\n**Mark \"discovery\" as in_progress.**\n\n### Fire Background Explore Agents IMMEDIATELY\n\nDon't wait\u2014these run async while main session works.\n\n```\n// Fire all at once, collect results later\ntask(subagent_type=\"explore\", load_skills=[], description=\"Explore project structure\", run_in_background=true, prompt=\"Project structure: PREDICT standard patterns for detected language \u2192 REPORT deviations only\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Find entry points\", run_in_background=true, prompt=\"Entry points: FIND main files \u2192 REPORT non-standard organization\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Find conventions\", run_in_background=true, prompt=\"Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) \u2192 REPORT project-specific rules\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Find anti-patterns\", run_in_background=true, prompt=\"Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments \u2192 LIST forbidden patterns\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Explore build/CI\", run_in_background=true, prompt=\"Build/CI: FIND .github/workflows, Makefile \u2192 REPORT non-standard patterns\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Find test patterns\", run_in_background=true, prompt=\"Test patterns: FIND test configs, test structure \u2192 REPORT unique conventions\")\n```\n\n<dynamic-agents>\n**DYNAMIC AGENT SPAWNING**: After bash analysis, spawn ADDITIONAL explore agents based on project scale:\n\n| Factor | Threshold | Additional Agents |\n|--------|-----------|-------------------|\n| **Total files** | >100 | +1 per 100 files |\n| **Total lines** | >10k | +1 per 10k lines |\n| **Directory depth** | \u22654 | +2 for deep exploration |\n| **Large files (>500 lines)** | >10 files | +1 for complexity hotspots |\n| **Monorepo** | detected | +1 per package/workspace |\n| **Multiple languages** | >1 | +1 per language |\n\n```bash\n# Measure project scale first\ntotal_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)\ntotal_lines=$(find . -type f \\( -name \"*.ts\" -o -name \"*.py\" -o -name \"*.go\" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')\nlarge_files=$(find . -type f \\( -name \"*.ts\" -o -name \"*.py\" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')\nmax_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)\n```\n\nExample spawning:\n```\n// 500 files, 50k lines, depth 6, 15 large files \u2192 spawn 5+5+2+1 = 13 additional agents\ntask(subagent_type=\"explore\", load_skills=[], description=\"Analyze large files\", run_in_background=true, prompt=\"Large file analysis: FIND files >500 lines, REPORT complexity hotspots\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Explore deep modules\", run_in_background=true, prompt=\"Deep modules at depth 4+: FIND hidden patterns, internal conventions\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Find shared utilities\", run_in_background=true, prompt=\"Cross-cutting concerns: FIND shared utilities across directories\")\n// ... more based on calculation\n```\n</dynamic-agents>\n\n### Main Session: Concurrent Analysis\n\n**While background agents run**, main session does:\n\n#### 1. Bash Structural Analysis\n```bash\n# Directory depth + file counts\nfind . -type d -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c\n\n# Files per directory (top 30)\nfind . -type f -not -path '*/\\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30\n\n# Code concentration by extension\nfind . -type f \\( -name \"*.py\" -o -name \"*.ts\" -o -name \"*.tsx\" -o -name \"*.js\" -o -name \"*.go\" -o -name \"*.rs\" \\) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20\n\n# Existing AGENTS.md / CLAUDE.md\nfind . -type f \\( -name \"AGENTS.md\" -o -name \"CLAUDE.md\" \\) -not -path '*/node_modules/*' 2>/dev/null\n```\n\n#### 2. Read Existing AGENTS.md\n```\nFor each existing file found:\n  Read(filePath=file)\n  Extract: key insights, conventions, anti-patterns\n  Store in EXISTING_AGENTS map\n```\n\nIf `--create-new`: Read all existing first (preserve context) \u2192 then delete all \u2192 regenerate.\n\n#### 3. LSP Codemap (if available)\n```\nLspServers()  # Check availability\n\n# Entry points (parallel)\nLspDocumentSymbols(filePath=\"src/index.ts\")\nLspDocumentSymbols(filePath=\"main.py\")\n\n# Key symbols (parallel)\nLspWorkspaceSymbols(filePath=\".\", query=\"class\")\nLspWorkspaceSymbols(filePath=\".\", query=\"interface\")\nLspWorkspaceSymbols(filePath=\".\", query=\"function\")\n\n# Centrality for top exports\nLspFindReferences(filePath=\"...\", line=X, character=Y)\n```\n\n**LSP Fallback**: If unavailable, rely on explore agents + AST-grep.\n\n### Collect Background Results\n\n```\n// After main session analysis done, collect all task results\nfor each task_id: background_output(task_id=\"...\")\n```\n\n**Merge: bash + LSP + existing + explore findings. Mark \"discovery\" as completed.**\n\n---\n\n## Phase 2: Scoring & Location Decision\n\n**Mark \"scoring\" as in_progress.**\n\n### Scoring Matrix\n\n| Factor | Weight | High Threshold | Source |\n|--------|--------|----------------|--------|\n| File count | 3x | >20 | bash |\n| Subdir count | 2x | >5 | bash |\n| Code ratio | 2x | >70% | bash |\n| Unique patterns | 1x | Has own config | explore |\n| Module boundary | 2x | Has index.ts/__init__.py | bash |\n| Symbol density | 2x | >30 symbols | LSP |\n| Export count | 2x | >10 exports | LSP |\n| Reference centrality | 3x | >20 refs | LSP |\n\n### Decision Rules\n\n| Score | Action |\n|-------|--------|\n| **Root (.)** | ALWAYS create |\n| **>15** | Create AGENTS.md |\n| **8-15** | Create if distinct domain |\n| **<8** | Skip (parent covers) |\n\n### Output\n```\nAGENTS_LOCATIONS = [\n  { path: \".\", type: \"root\" },\n  { path: \"src/hooks\", score: 18, reason: \"high complexity\" },\n  { path: \"src/api\", score: 12, reason: \"distinct domain\" }\n]\n```\n\n**Mark \"scoring\" as completed.**\n\n---\n\n## Phase 3: Generate AGENTS.md\n\n**Mark \"generate\" as in_progress.**\n\n<critical>\n**File Writing Rule**: If AGENTS.md already exists at the target path \u2192 use `Edit` tool. If it does NOT exist \u2192 use `Write` tool.\nNEVER use Write to overwrite an existing file. ALWAYS check existence first via `Read` or discovery results.\n</critical>\n\n### Root AGENTS.md (Full Treatment)\n\n```markdown\n# PROJECT KNOWLEDGE BASE\n\n**Generated:** {TIMESTAMP}\n**Commit:** {SHORT_SHA}\n**Branch:** {BRANCH}\n\n## OVERVIEW\n{1-2 sentences: what + core stack}\n\n## STRUCTURE\n\\`\\`\\`\n{root}/\n\u251C\u2500\u2500 {dir}/    # {non-obvious purpose only}\n\u2514\u2500\u2500 {entry}\n\\`\\`\\`\n\n## WHERE TO LOOK\n| Task | Location | Notes |\n|------|----------|-------|\n\n## CODE MAP\n{From LSP - skip if unavailable or project <10 files}\n\n| Symbol | Type | Location | Refs | Role |\n|--------|------|----------|------|------|\n\n## CONVENTIONS\n{ONLY deviations from standard}\n\n## ANTI-PATTERNS (THIS PROJECT)\n{Explicitly forbidden here}\n\n## UNIQUE STYLES\n{Project-specific}\n\n## COMMANDS\n\\`\\`\\`bash\n{dev/test/build}\n\\`\\`\\`\n\n## NOTES\n{Gotchas}\n```\n\n**Quality gates**: 50-150 lines, no generic advice, no obvious info.\n\n### Subdirectory AGENTS.md (Parallel)\n\nLaunch writing tasks for each location:\n\n```\nfor loc in AGENTS_LOCATIONS (except root):\n  task(category=\"writing\", load_skills=[], run_in_background=false, description=\"Generate AGENTS.md\", prompt=\\`\n    Generate AGENTS.md for: ${loc.path}\n    - Reason: ${loc.reason}\n    - 30-80 lines max\n    - NEVER repeat parent content\n    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS\n  \\`)\n```\n\n**Wait for all. Mark \"generate\" as completed.**\n\n---\n\n## Phase 4: Review & Deduplicate\n\n**Mark \"review\" as in_progress.**\n\nFor each generated file:\n- Remove generic advice\n- Remove parent duplicates\n- Trim to size limits\n- Verify telegraphic style\n\n**Mark \"review\" as completed.**\n\n---\n\n## Final Report\n\n```\n=== init-deep Complete ===\n\nMode: {update | create-new}\n\nFiles:\n  [OK] ./AGENTS.md (root, {N} lines)\n  [OK] ./src/hooks/AGENTS.md ({N} lines)\n\nDirs Analyzed: {N}\nAGENTS.md Created: {N}\nAGENTS.md Updated: {N}\n\nHierarchy:\n  ./AGENTS.md\n  \u2514\u2500\u2500 src/hooks/AGENTS.md\n```\n\n---\n\n## Anti-Patterns\n\n- **Static agent count**: MUST vary agents based on project size/depth\n- **Sequential execution**: MUST parallel (explore + LSP concurrent)\n- **Ignoring existing**: ALWAYS read existing first, even with --create-new\n- **Over-documenting**: Not every dir needs AGENTS.md\n- **Redundancy**: Child never repeats parent\n- **Generic content**: Remove anything that applies to ALL projects\n- **Verbose style**: Telegraphic or die";

package/dist/features/builtin-commands/templates/ralph-loop.d.ts

@@ -0,0 +1,2 @@
+export declare const RALPH_LOOP_TEMPLATE = "You are starting a Ralph Loop - a self-referential development loop that runs until task completion.\n\n## How Ralph Loop Works\n\n1. You will work on the task continuously\n2. When you believe the task is FULLY complete, output: `<promise>{{COMPLETION_PROMISE}}</promise>`\n3. If you don't output the promise, the loop will automatically inject another prompt to continue\n4. Maximum iterations: Configurable (default 100)\n\n## Rules\n\n- Focus on completing the task fully, not partially\n- Don't output the completion promise until the task is truly done\n- Each iteration should make meaningful progress toward the goal\n- If stuck, try different approaches\n- Use todos to track your progress\n\n## Exit Conditions\n\n1. **Completion**: Output your completion promise tag when fully complete\n2. **Max Iterations**: Loop stops automatically at limit\n3. **Cancel**: User runs `/cancel-ralph` command\n\n## Your Task\n\nParse the arguments below and begin working on the task. The format is:\n`\"task description\" [--completion-promise=TEXT] [--max-iterations=N] [--strategy=reset|continue]`\n\nDefault completion promise is \"DONE\" and default max iterations is 100.";
+export declare const CANCEL_RALPH_TEMPLATE = "Cancel the currently active Ralph Loop.\n\nThis will:\n1. Stop the loop from continuing\n2. Clear the loop state file\n3. Allow the session to end normally\n\nCheck if a loop is active and cancel it. Inform the user of the result.";