@engineereddev/fractal-planner 0.1.1

package/dist/src/cli/classify-intent.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=classify-intent.d.ts.map

package/dist/src/cli/compute-signals.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env bun
+export interface TaskSignals {
+    fileScope: number;
+    coupling: number;
+    gitRisk: number;
+    testCoverage: number;
+    composite: number;
+}
+export declare function computeFileScope(files: string[]): number;
+export declare function computeCoupling(files: string[]): number;
+export declare function computeGitRisk(files: string[]): number;
+export declare function computeTestCoverage(files: string[], testsRequired: boolean): number;
+export declare function computeComposite(signals: Omit<TaskSignals, 'composite'>): number;
+//# sourceMappingURL=compute-signals.d.ts.map

package/dist/src/cli/generate-plan.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=generate-plan.d.ts.map

package/dist/src/cli/load-config.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=load-config.d.ts.map

package/dist/src/cli/validate-tasks.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=validate-tasks.d.ts.map

package/dist/src/config.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Configuration Module
+ *
+ * Layered JSON config system with user-level and project-level files,
+ * merged with sensible defaults.
+ *
+ * Priority (highest wins): runtime overrides > project config > user config > defaults
+ */
+import { z } from 'zod';
+export declare const LinearConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    teamId: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    statusMap: z.ZodOptional<z.ZodObject<{
+        pending: z.ZodOptional<z.ZodString>;
+        'in-progress': z.ZodOptional<z.ZodString>;
+        completed: z.ZodOptional<z.ZodString>;
+        failed: z.ZodOptional<z.ZodString>;
+        review: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const CommentCheckerConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    binaryPath: z.ZodOptional<z.ZodString>;
+    customPrompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const NudgeConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    maxRetries: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const IterationScalingConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    base: z.ZodDefault<z.ZodNumber>;
+    factor: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+declare const FractalPlannerConfigBaseSchema: z.ZodObject<{
+    maxComplexity: z.ZodDefault<z.ZodNumber>;
+    maxIterations: z.ZodDefault<z.ZodNumber>;
+    maxParallelTasks: z.ZodDefault<z.ZodNumber>;
+    researchOnly: z.ZodDefault<z.ZodBoolean>;
+    planOnly: z.ZodDefault<z.ZodBoolean>;
+    skipPlanReview: z.ZodDefault<z.ZodBoolean>;
+    skipApproachReview: z.ZodDefault<z.ZodBoolean>;
+    preAnalysis: z.ZodDefault<z.ZodBoolean>;
+    enableAgentTeams: z.ZodDefault<z.ZodBoolean>;
+    noCommit: z.ZodDefault<z.ZodBoolean>;
+    plansDir: z.ZodDefault<z.ZodString>;
+    permissionMode: z.ZodDefault<z.ZodEnum<{
+        default: "default";
+        acceptEdits: "acceptEdits";
+        bypassPermissions: "bypassPermissions";
+        plan: "plan";
+        delegate: "delegate";
+        dontAsk: "dontAsk";
+    }>>;
+    linear: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        teamId: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodString>;
+        statusMap: z.ZodOptional<z.ZodObject<{
+            pending: z.ZodOptional<z.ZodString>;
+            'in-progress': z.ZodOptional<z.ZodString>;
+            completed: z.ZodOptional<z.ZodString>;
+            failed: z.ZodOptional<z.ZodString>;
+            review: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    commentChecker: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        binaryPath: z.ZodOptional<z.ZodString>;
+        customPrompt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    nudge: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    cliRunner: z.ZodDefault<z.ZodEnum<{
+        bun: "bun";
+        node: "node";
+        auto: "auto";
+    }>>;
+    iterationScaling: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        base: z.ZodDefault<z.ZodNumber>;
+        factor: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    executionOrder: z.ZodDefault<z.ZodEnum<{
+        "risk-first": "risk-first";
+        "easy-first": "easy-first";
+        "document-order": "document-order";
+    }>>;
+}, z.core.$strip>;
+export declare const FractalPlannerConfigSchema: z.ZodObject<{
+    maxComplexity: z.ZodDefault<z.ZodNumber>;
+    maxIterations: z.ZodDefault<z.ZodNumber>;
+    maxParallelTasks: z.ZodDefault<z.ZodNumber>;
+    researchOnly: z.ZodDefault<z.ZodBoolean>;
+    planOnly: z.ZodDefault<z.ZodBoolean>;
+    skipPlanReview: z.ZodDefault<z.ZodBoolean>;
+    skipApproachReview: z.ZodDefault<z.ZodBoolean>;
+    preAnalysis: z.ZodDefault<z.ZodBoolean>;
+    enableAgentTeams: z.ZodDefault<z.ZodBoolean>;
+    noCommit: z.ZodDefault<z.ZodBoolean>;
+    plansDir: z.ZodDefault<z.ZodString>;
+    permissionMode: z.ZodDefault<z.ZodEnum<{
+        default: "default";
+        acceptEdits: "acceptEdits";
+        bypassPermissions: "bypassPermissions";
+        plan: "plan";
+        delegate: "delegate";
+        dontAsk: "dontAsk";
+    }>>;
+    linear: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        teamId: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodString>;
+        statusMap: z.ZodOptional<z.ZodObject<{
+            pending: z.ZodOptional<z.ZodString>;
+            'in-progress': z.ZodOptional<z.ZodString>;
+            completed: z.ZodOptional<z.ZodString>;
+            failed: z.ZodOptional<z.ZodString>;
+            review: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    commentChecker: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        binaryPath: z.ZodOptional<z.ZodString>;
+        customPrompt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    nudge: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    cliRunner: z.ZodDefault<z.ZodEnum<{
+        bun: "bun";
+        node: "node";
+        auto: "auto";
+    }>>;
+    iterationScaling: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        base: z.ZodDefault<z.ZodNumber>;
+        factor: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    executionOrder: z.ZodDefault<z.ZodEnum<{
+        "risk-first": "risk-first";
+        "easy-first": "easy-first";
+        "document-order": "document-order";
+    }>>;
+}, z.core.$strip>;
+export type FractalPlannerConfig = z.infer<typeof FractalPlannerConfigSchema>;
+export type FractalPlannerConfigFile = z.input<typeof FractalPlannerConfigBaseSchema>;
+export declare const DEFAULT_CONFIG: FractalPlannerConfig;
+/**
+ * Resolve the user-level config path.
+ * Respects $XDG_CONFIG_HOME, falls back to ~/.config.
+ */
+export declare function getUserConfigPath(): string;
+/**
+ * Resolve the project-level config path (relative to cwd).
+ */
+export declare function getProjectConfigPath(): string;
+/**
+ * Load config from user + project files, merge with defaults, and cache.
+ * Optionally accepts runtime overrides (highest priority).
+ *
+ * Throws if any config file contains invalid JSON or values.
+ */
+export declare function loadConfig(overrides?: FractalPlannerConfigFile): Promise<FractalPlannerConfig>;
+/**
+ * Sync getter for cached config.
+ * Throws if loadConfig() has not been called.
+ */
+export declare function getConfig(): FractalPlannerConfig;
+/**
+ * Clear the cached config (for testing or reloading).
+ */
+export declare function resetConfig(): void;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Fractal Planner
+ *
+ * Main exports for the framework
+ */
+export * from './types/index.js';
+export * from './config.js';
+export * from './phases/interview.js';
+export * from './phases/research.js';
+export * from './phases/decomposition.js';
+export * from './phases/planning.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/phases/clearance.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Clearance Check Module
+ *
+ * Evaluates if interview has gathered enough context to proceed.
+ * Adapted from oh-my-opencode clearance checklist.
+ */
+import type { ClearanceCheck, InterviewDraft } from '../types/index.js';
+/**
+ * Evaluate if interview has gathered enough context to proceed
+ */
+export declare function evaluateClearance(draft: InterviewDraft): Promise<ClearanceCheck>;
+//# sourceMappingURL=clearance.d.ts.map

package/dist/src/phases/decomposition.d.ts

@@ -0,0 +1,41 @@
+import type { Task } from '../types/index.js';
+export type ViolationType = 'over-complexity' | 'missing-acceptance' | 'missing-files' | 'missing-tests-required' | 'missing-hints' | 'missing-guardrails' | 'subtask-count' | 'scattered-files';
+export interface TaskViolation {
+    type: ViolationType;
+    id: string;
+    description: string;
+    parentId: string | null;
+    depth: number;
+    detail: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    maxComplexity: number;
+    totalLeafTasks: number;
+    violations: TaskViolation[];
+    warnings: TaskViolation[];
+    stats: {
+        maxDepth: number;
+        leafComplexityDistribution: Record<number, number>;
+        dimensionAverages?: Record<string, number>;
+    };
+}
+/**
+ * Validate that the task tree conforms to all decomposer rules:
+ * - Leaf complexity <= maxComplexity
+ * - Leaves have acceptance criteria
+ * - Leaves have filesToModify metadata
+ * - Leaves have testsRequired metadata
+ * - Leaves have guardrails metadata
+ * - Non-leaf, non-root nodes have 2-5 subtasks
+ */
+export declare function validateTaskTree(root: Task, maxComplexity: number): ValidationResult;
+/**
+ * Calculate total number of leaf tasks in the tree
+ */
+export declare function countLeafTasks(task: Task): number;
+/**
+ * Calculate maximum depth of the task tree
+ */
+export declare function calculateMaxDepth(task: Task, currentDepth?: number): number;
+//# sourceMappingURL=decomposition.d.ts.map

package/dist/src/phases/interview.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interview Phase - Iterative clarification loop
+ *
+ * Uses Claude Agent SDK to spawn an agent with access to AskUserQuestion tool.
+ * Adapted from oh-my-opencode Prometheus agent.
+ */
+import type { InterviewFindings, FractalPlannerConfig } from '../types/index.js';
+/**
+ * Interview Phase - Iterative clarification loop
+ * Runs until clearance check passes
+ */
+export declare function runInterviewPhase(userGoal: string, planId?: string, config?: Partial<FractalPlannerConfig>): Promise<{
+    findings: InterviewFindings;
+    draftPath: string;
+    planId: string;
+}>;
+//# sourceMappingURL=interview.d.ts.map

package/dist/src/phases/planning.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Planning Phase
+ *
+ * Creates a detailed implementation plan with strict acceptance criteria
+ * and execution ordering based on dependencies.
+ */
+import type { Task, PlanningResult } from '../types/index.js';
+/**
+ * Generate a comprehensive implementation plan
+ */
+export declare function createImplementationPlan(rootTask: Task): Promise<PlanningResult>;
+/**
+ * Get execution order respecting dependencies
+ * Returns tasks in topological order with optional tiebreak strategy
+ */
+export declare function getExecutionOrder(rootTask: Task, tiebreak?: 'risk-first' | 'easy-first' | 'document-order'): Task[];
+/**
+ * Print a visual tree representation of the plan
+ */
+export declare function printPlanTree(task: Task, prefix?: string, isLast?: boolean): void;
+//# sourceMappingURL=planning.d.ts.map

package/dist/src/phases/research.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Research Phase
+ *
+ * Conducts iterative research to understand the codebase,
+ * identify gaps, and gather requirements.
+ */
+import type { ResearchFindings, InterviewFindings, FractalPlannerConfig } from '../types/index.js';
+export declare function runResearchPhase(userGoal: string, interviewFindings?: InterviewFindings, config?: Partial<FractalPlannerConfig>): Promise<ResearchFindings>;
+//# sourceMappingURL=research.d.ts.map

package/dist/src/types/index.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Core types for Fractal Planner
+ */
+export interface Task {
+    id: string;
+    description: string;
+    acceptanceCriteria: string[];
+    estimatedComplexity: number;
+    dependencies: string[];
+    subtasks?: Task[];
+    status?: TaskStatus;
+    complexityDimensions?: {
+        scope: number;
+        risk: number;
+        novelty: number;
+        integration: number;
+        testing: number;
+    };
+    metadata?: {
+        filesToModify?: string[];
+        testsRequired?: boolean;
+        hints?: string[];
+        references?: string[];
+        guardrails?: string[];
+        testCommands?: string[];
+        complexitySignals?: {
+            fileScope: number;
+            coupling: number;
+            gitRisk: number;
+            testCoverage: number;
+            composite: number;
+        };
+    };
+}
+export type TaskStatus = 'pending' | 'in-progress' | 'completed' | 'failed';
+export interface ResearchFindings {
+    codebasePatterns: string[];
+    existingImplementations: string[];
+    potentialChallenges: string[];
+    openQuestions: string[];
+    assumptions: string[];
+}
+export interface PlanningResult {
+    rootTask: Task;
+    totalTasks: number;
+    maxDepth: number;
+    estimatedDuration?: string;
+}
+export interface ExecutionResult {
+    taskId: string;
+    success: boolean;
+    iterations: number;
+    verificationReport: VerificationReport;
+}
+export interface VerificationReport {
+    verified: boolean;
+    passedCriteria: number[];
+    failedCriteria: number[];
+    feedback: string;
+    suggestions?: string[];
+}
+export type { FractalPlannerConfig, FractalPlannerConfigFile } from '../config.js';
+export interface AgentMessage {
+    role: 'builder' | 'verifier' | 'orchestrator';
+    content: string;
+    timestamp: number;
+}
+export type IntentType = 'trivial' | 'refactoring' | 'build-from-scratch' | 'mid-sized' | 'architecture';
+export interface QuestionStrategy {
+    researchFirst: boolean;
+    focusAreas: string[];
+    initialQuestions: string[];
+    researchPrompts: string[];
+}
+export interface ClearanceCheck {
+    passed: boolean;
+    checklist: {
+        coreObjectiveDefined: boolean;
+        scopeBoundariesEstablished: boolean;
+        noAmbiguities: boolean;
+        technicalApproachDecided: boolean;
+        noBlockingQuestions: boolean;
+        testStrategyIdentified: boolean;
+    };
+    gaps: ClearanceGap[];
+}
+export interface ClearanceGap {
+    type: 'critical' | 'minor' | 'ambiguous';
+    item: keyof ClearanceCheck['checklist'];
+    description: string;
+    suggestedQuestion?: string;
+}
+export interface InterviewFindings {
+    intent: IntentType;
+    userGoal: string;
+    confirmedRequirements: string[];
+    scopeInclusions: string[];
+    scopeExclusions: string[];
+    technicalDecisions: Record<string, string>;
+    constraints: string[];
+    assumptions: string[];
+    openQuestions: string[];
+    codebaseContext?: {
+        relevantFiles: string[];
+        existingPatterns: string[];
+        testStrategy?: string;
+    };
+}
+export interface InterviewDraft {
+    name: string;
+    planId?: string;
+    created: string;
+    lastUpdated: string;
+    findings: InterviewFindings;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/src/utils/draft.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Draft Management Utility
+ *
+ * Manages persistent interview state across turns.
+ * The draft file serves as working memory during the interview loop.
+ */
+import type { InterviewDraft, InterviewFindings, IntentType } from '../types/index.js';
+export declare function generateSlugPlanId(description: string): string;
+export declare function createDraft(name: string, userGoal: string, intent: IntentType, planId?: string, plansDir?: string): Promise<{
+    draftPath: string;
+    planId: string;
+}>;
+/**
+ * Update draft with new findings
+ */
+export declare function updateDraft(draftPath: string, updates: Partial<InterviewFindings>): Promise<void>;
+/**
+ * Read draft file
+ */
+export declare function readDraft(draftPath: string): Promise<InterviewDraft>;
+//# sourceMappingURL=draft.d.ts.map

package/dist/src/utils/question-strategies.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Intent-Specific Question Strategies
+ *
+ * Adapted from oh-my-opencode interview-mode.ts
+ */
+import type { IntentType } from '../types/index.js';
+/**
+ * Question strategy for interview phase
+ */
+export interface QuestionStrategy {
+    researchFirst: boolean;
+    focusAreas: string[];
+    initialQuestions: string[];
+    researchPrompts: string[];
+}
+/**
+ * Intent-specific interview strategies
+ */
+export declare function getQuestionStrategy(intent: IntentType): QuestionStrategy;
+/**
+ * Classify user intent based on goal description
+ */
+export declare function classifyIntent(userGoal: string): IntentType;
+//# sourceMappingURL=question-strategies.d.ts.map

package/dist/src/utils/task-parser.d.ts

@@ -0,0 +1,3 @@
+import type { Task } from '../types/index.js';
+export declare function parseTasksMarkdown(markdown: string): Task;
+//# sourceMappingURL=task-parser.d.ts.map

package/hooks/hooks.json

@@ -0,0 +1,27 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/run-comment-checker.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "TeammateIdle": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/nudge-teammate.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}