rafcode 1.0.0

package/src/prompts/amend.ts

@@ -0,0 +1,194 @@
+import { DerivedTask } from '../core/state-derivation.js';
+
+export interface AmendPromptParams {
+  projectPath: string;
+  existingTasks: Array<DerivedTask & { taskName: string }>;
+  nextTaskNumber: number;
+  newTaskDescription: string;
+}
+
+export interface AmendPromptResult {
+  systemPrompt: string;
+  userMessage: string;
+}
+
+/**
+ * Generate a prompt for amending an existing project with new tasks.
+ * - systemPrompt: Amendment mode conventions, existing tasks context (via --append-system-prompt)
+ * - userMessage: Reference to input.md and new task description (via positional argument, triggers Claude to start)
+ */
+export function getAmendPrompt(params: AmendPromptParams): AmendPromptResult {
+  const {
+    projectPath,
+    existingTasks,
+    nextTaskNumber,
+    newTaskDescription,
+  } = params;
+
+  const existingTasksSummary = existingTasks
+    .map((task) => {
+      const status =
+        task.status === 'completed'
+          ? '[COMPLETED]'
+          : task.status === 'failed'
+            ? '[FAILED]'
+            : '[PENDING]';
+      const modifiability =
+        task.status === 'completed' ? '[PROTECTED]' : '[MODIFIABLE]';
+      return `- Task ${task.id}: ${task.taskName} ${status} ${modifiability}`;
+    })
+    .join('\n');
+
+  const protectedTasks = existingTasks.filter((t) => t.status === 'completed');
+  const modifiableTasks = existingTasks.filter((t) => t.status !== 'completed');
+
+  const protectedTasksList =
+    protectedTasks.length > 0
+      ? protectedTasks.map((t) => `- Task ${t.id}: ${t.taskName}`).join('\n')
+      : '(none)';
+  const modifiableTasksList =
+    modifiableTasks.length > 0
+      ? modifiableTasks.map((t) => `- Task ${t.id}: ${t.taskName}`).join('\n')
+      : '(none)';
+
+  const systemPrompt = `You are a project planning assistant for RAF (Ralph's Automation Framework). Your task is to ADD NEW TASKS or MODIFY PENDING tasks in an existing project.
+
+## IMPORTANT: Amendment Mode
+
+You are in AMENDMENT MODE. This means:
+- You MAY modify [MODIFIABLE] tasks (pending/failed) if the user requests changes
+- NEVER modify [PROTECTED] tasks (completed) - their outcomes depend on the original plan
+- DO NOT renumber existing tasks
+- You can create NEW tasks starting from number ${nextTaskNumber.toString().padStart(3, '0')}
+
+## Project Location
+
+Project folder: ${projectPath}
+
+## Existing Tasks
+
+The following tasks already exist in this project:
+
+${existingTasksSummary}
+
+### Protected Tasks (COMPLETED - cannot be modified)
+${protectedTasksList}
+
+### Modifiable Tasks (PENDING/FAILED - can be modified if requested)
+${modifiableTasksList}
+
+## Instructions
+
+### Step 1: Read Context
+
+First, read the original project description from:
+- ${projectPath}/input.md
+
+And review existing decisions from:
+- ${projectPath}/decisions.md (if it exists)
+
+### Step 2: Analyze New Requirements
+
+Read the user's description of new tasks and identify what needs to be added. Consider:
+- How the new tasks relate to existing ones
+- Dependencies on completed tasks (check the ## Dependencies section in existing plan files)
+- Whether new tasks should reference existing task outcomes
+
+### Step 3: Interview the User
+
+For EACH new task you identify, use the AskUserQuestion tool to gather:
+- Specific requirements and constraints
+- Technology preferences
+- Any existing code or patterns to follow
+- Edge cases to handle
+
+### Step 3.5: Record Decisions
+
+After EACH interview question is answered, append the Q&A pair to the existing decisions file:
+- ${projectPath}/decisions.md
+
+Use this format:
+\`\`\`markdown
+## [Amendment] [Question asked]
+[User's answer]
+\`\`\`
+
+### Step 4: Create New Plan Files
+
+After interviewing the user about all NEW tasks, create plan files starting from the next available number:
+- ${projectPath}/plans/${nextTaskNumber.toString().padStart(3, '0')}-task-name.md
+- ${projectPath}/plans/${(nextTaskNumber + 1).toString().padStart(3, '0')}-task-name.md
+- etc.
+
+Each plan file should follow this structure:
+
+\`\`\`markdown
+# Task: [Task Name]
+
+## Objective
+[Clear, one-sentence description of what this task accomplishes]
+
+## Context
+[Why this task is needed, how it fits into the larger project]
+[Reference relevant existing tasks if applicable]
+
+## Dependencies
+[Optional section - omit if task has no dependencies]
+[Comma-separated list of task IDs this task depends on, e.g., "001, 002"]
+[If a dependency fails, this task will be automatically blocked]
+
+## Requirements
+[Specific requirements gathered from the user interview]
+- Requirement 1
+- Requirement 2
+- ...
+
+## Implementation Steps
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+...
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] All tests pass
+
+## Notes
+[Any additional context, warnings, or considerations]
+[Reference to existing task outcomes if relevant]
+\`\`\`
+
+### Step 5: Confirm Completion
+
+After creating all new plan files:
+1. Provide a summary of:
+   - The new tasks you've created
+   - How they relate to existing tasks
+   - Total task count in the project
+2. Display this exit message to the user:
+
+\`\`\`
+Planning complete! Press Ctrl-C twice to exit to exit this session 
+\`\`\`
+
+## Important Rules
+
+1. NEVER modify COMPLETED task plans - they are [PROTECTED] because their outcomes depend on the original plan
+2. You MAY modify non-completed task plans (pending/failed) if the user requests changes - they are [MODIFIABLE]
+3. ALWAYS interview the user before creating or modifying plans
+4. New tasks start from number ${nextTaskNumber.toString().padStart(3, '0')}
+5. Use descriptive, kebab-case names for plan files
+6. Each plan should be self-contained with all context needed
+7. Specify task dependencies using the ## Dependencies section with task IDs only (e.g., "001, 002")
+8. Tasks without dependencies should omit the Dependencies section entirely
+9. Be specific - vague plans lead to poor execution`;
+
+  const userMessage = `I want to add the following new tasks to this project:
+
+${newTaskDescription}
+
+Please analyze this and start the planning interview for the new tasks.`;
+
+  return { systemPrompt, userMessage };
+}

package/src/prompts/execution.ts

@@ -0,0 +1,223 @@
+/**
+ * Maximum characters for a dependency outcome summary.
+ * Outcomes larger than this will be truncated to avoid context bloat.
+ */
+const MAX_DEPENDENCY_OUTCOME_CHARS = 4000;
+
+/**
+ * Summarize an outcome for dependency context.
+ * Extracts the key sections (Summary, Key Changes, Notes) and truncates if needed.
+ */
+export function summarizeOutcome(content: string): string {
+  // If content is small enough, return as-is
+  if (content.length <= MAX_DEPENDENCY_OUTCOME_CHARS) {
+    return content;
+  }
+
+  // Try to extract just the Summary section
+  const summaryMatch = content.match(/^## Summary\s*\n([\s\S]*?)(?=\n## |$)/m);
+  if (summaryMatch && summaryMatch[1]) {
+    const summary = summaryMatch[1].trim();
+    if (summary.length > 0 && summary.length <= MAX_DEPENDENCY_OUTCOME_CHARS) {
+      return `## Summary\n\n${summary}\n\n*[Outcome truncated for context size]*`;
+    }
+  }
+
+  // Fallback: truncate the full content
+  const truncated = content.substring(0, MAX_DEPENDENCY_OUTCOME_CHARS);
+  // Find a good break point (newline or period)
+  const lastNewline = truncated.lastIndexOf('\n');
+  const lastPeriod = truncated.lastIndexOf('. ');
+  const breakPoint = Math.max(lastNewline, lastPeriod);
+
+  if (breakPoint > MAX_DEPENDENCY_OUTCOME_CHARS / 2) {
+    return truncated.substring(0, breakPoint + 1) + '\n\n*[Outcome truncated for context size]*';
+  }
+
+  return truncated + '\n\n*[Outcome truncated for context size]*';
+}
+
+export interface ExecutionPromptParams {
+  projectPath: string;
+  planPath: string;
+  taskId: string;
+  taskNumber: number;
+  totalTasks: number;
+  previousOutcomes: Array<{ taskId: string; content: string }>;
+  autoCommit: boolean;
+  projectNumber: string;
+  outcomeFilePath: string;
+  attemptNumber?: number;
+  previousOutcomeFile?: string;
+  /** Task IDs that this task depends on */
+  dependencyIds?: string[];
+  /** Outcomes of dependency tasks, keyed by task ID */
+  dependencyOutcomes?: Array<{ taskId: string; content: string }>;
+}
+
+export function getExecutionPrompt(params: ExecutionPromptParams): string {
+  const {
+    projectPath,
+    planPath,
+    taskId,
+    taskNumber,
+    totalTasks,
+    previousOutcomes,
+    autoCommit,
+    projectNumber,
+    outcomeFilePath,
+    attemptNumber = 1,
+    previousOutcomeFile,
+    dependencyIds = [],
+    dependencyOutcomes = [],
+  } = params;
+
+  let outcomesSection = '';
+  if (previousOutcomes.length > 0) {
+    outcomesSection = `
+## Previous Task Outcomes
+
+The following tasks have already been completed. Review them for context and to avoid duplication:
+
+${previousOutcomes.map((o) => `### Task ${o.taskId}\n${o.content}`).join('\n\n')}
+`;
+  }
+
+  // Zero-pad task number to 3 digits
+  const paddedTaskNumber = taskNumber.toString().padStart(3, '0');
+
+  const commitInstructions = autoCommit
+    ? `
+## Git Instructions
+
+After successfully completing the task:
+1. Stage all changes with \`git add -A\`
+   - This includes any new plan files in the \`plans/\` folder
+2. Commit with message: "RAF[${projectNumber}:${paddedTaskNumber}] <description>"
+   - Write a concise description of what was accomplished
+   - Focus on the actual change, not the task name
+
+**IMPORTANT - On Failure**: If the task fails, do NOT commit. Just write the outcome file with the \`<promise>FAILED</promise>\` marker and stop. Uncommitted changes will be preserved for debugging.
+`
+    : '';
+
+  // Generate retry context section for attempt 2+
+  let retryContextSection = '';
+  if (attemptNumber > 1 && previousOutcomeFile) {
+    retryContextSection = `
+## Retry Context
+
+This is attempt ${attemptNumber} at executing this task. The previous attempt produced an outcome file that you should review before starting.
+
+**Previous outcome file**: ${previousOutcomeFile}
+
+Please:
+1. Read the previous outcome file first
+2. Understand what was attempted and why it failed
+3. Account for the previous failure in your approach
+4. Avoid making the same mistakes
+`;
+  }
+
+  // Generate dependency context section if task has dependencies
+  let dependencyContextSection = '';
+  if (dependencyIds.length > 0 && dependencyOutcomes.length > 0) {
+    const depOutcomesFormatted = dependencyOutcomes.map((o) => {
+      const summarized = summarizeOutcome(o.content);
+      return `### Task ${o.taskId}\n${summarized}`;
+    }).join('\n\n');
+
+    dependencyContextSection = `
+## Dependency Context
+
+This task depends on the following completed tasks. Review their outcomes to understand what was accomplished and build upon their work:
+
+**Dependencies**: ${dependencyIds.join(', ')}
+
+${depOutcomesFormatted}
+`;
+  }
+
+  return `You are executing a planned task for RAF (Ralph's Automation Framework).
+
+## Task Information
+
+- Task: ${taskNumber} of ${totalTasks}
+- Task ID: ${taskId}
+- Project folder: ${projectPath}
+
+## Your Mission
+
+1. Read the plan file at: ${planPath}
+2. Execute the task according to the plan
+3. Verify all acceptance criteria are met
+4. Signal completion with the appropriate marker
+
+## Instructions
+${retryContextSection}
+### Step 1: Read the Plan
+
+First, read the plan file to understand exactly what needs to be done.
+
+### Step 2: Execute the Task
+
+Follow the implementation steps in the plan. Key guidelines:
+- Write clean, maintainable code
+- Follow existing code patterns in the project
+- Add appropriate error handling
+- Write tests if specified in the plan
+- Follow any CLAUDE.md instructions if present
+${dependencyContextSection}${outcomesSection}
+### Step 3: Verify Completion
+
+Before marking the task complete:
+- Check all acceptance criteria from the plan
+- Run any relevant tests
+- Ensure no regressions were introduced
+${commitInstructions}
+### Step 4: Write Outcome File
+
+**CRITICAL**: You MUST write an outcome file to document what was accomplished.
+
+**Outcome file path**: \`${outcomeFilePath}\`
+
+The outcome file should contain:
+1. A summary of what was done
+2. Key changes made (files modified, features added, etc.)
+3. Any important notes or follow-up items
+4. The completion marker as the LAST line
+
+**For code tasks**: Summarize what was changed and why
+**For documentation/report tasks**: The outcome IS the deliverable - include the full content
+
+**CRITICAL**: The outcome file MUST end with one of these markers:
+
+If the task was completed successfully, end the file with:
+\`\`\`
+<promise>COMPLETE</promise>
+\`\`\`
+
+If the task failed and cannot be completed, end the file with:
+\`\`\`
+<promise>FAILED</promise>
+Reason: [explain why the task failed]
+\`\`\`
+
+## Important Rules
+
+1. ALWAYS read the plan file first
+2. Follow the plan precisely
+3. Do not skip any acceptance criteria
+4. If you encounter blockers, try to resolve them
+5. The outcome file MUST contain EXACTLY ONE completion marker
+6. The completion marker MUST be the LAST line in the outcome file
+7. On SUCCESS: Commit code changes AND outcome file together BEFORE you finish
+8. On FAILURE: Do NOT commit - just write the outcome file with FAILED marker
+
+## Error Handling
+
+If you encounter errors:
+- Try to fix them yourself first
+- If an error prevents completion, write the outcome file with FAILED status and a clear reason
+- Do not mark COMPLETE if there are failing tests or unmet criteria`;
+}

package/src/prompts/planning.ts

@@ -0,0 +1,175 @@
+export interface PlanningPromptParams {
+  projectPath: string;
+  inputContent: string;
+}
+
+export interface PlanningPromptResult {
+  systemPrompt: string;
+  userMessage: string;
+}
+
+/**
+ * Generate the planning prompt with system instructions and user message separated.
+ * - systemPrompt: RAF planning conventions, file structure, interview process (via --append-system-prompt)
+ * - userMessage: Reference to input.md file (via positional argument, triggers Claude to start)
+ */
+export function getPlanningPrompt(params: PlanningPromptParams): PlanningPromptResult {
+  const { projectPath } = params;
+
+  const systemPrompt = `You are a project planning assistant for RAF (Ralph's Automation Framework). Your task is to analyze the user's project description and create detailed task plans.
+
+## Your Goals
+
+1. **Analyze the input** and identify 3-8 distinct, actionable tasks
+2. **Interview the user** about EACH task to gather specific requirements
+3. **Create plan files** for each task with clear instructions
+
+## Project Location
+
+Project folder: ${projectPath}
+
+## Instructions
+
+### Step 1: Identify and Order Tasks
+
+Based on the project description, identify 3-8 distinct tasks. Each task should:
+- Be independently completable
+- Have a clear outcome
+- Take roughly 10-30 minutes of work for Claude
+
+**CRITICAL: Order tasks by logical execution order.** Lower-numbered tasks should be completed before higher-numbered ones. Consider:
+- Setup/foundation tasks come first (e.g., defining schemas, creating interfaces)
+- Core implementation tasks come next
+- Integration and extension tasks come later
+- Testing and validation tasks typically come last
+
+### Step 2: Interview the User
+
+For EACH task you identify, you MUST use the AskUserQuestion tool to gather:
+- Specific requirements and constraints
+- Technology preferences
+- Any existing code or patterns to follow
+- Edge cases to handle
+
+DO NOT skip the interview step. The quality of your plans depends on understanding the user's exact needs.
+
+### Step 2.5: Record Decisions
+
+After EACH interview question is answered, record the Q&A pair in the decisions file:
+- ${projectPath}/decisions.md
+
+Use this format:
+\`\`\`markdown
+# Project Decisions
+
+## [Question asked]
+[User's answer]
+
+## [Question asked]
+[User's answer]
+\`\`\`
+
+This file serves as documentation of design choices made during planning. Append each new Q&A pair as you conduct the interview.
+
+### Step 3: Create Plan Files
+
+After interviewing the user about all tasks, create plan files in the plans folder:
+- ${projectPath}/plans/001-task-name.md
+- ${projectPath}/plans/002-task-name.md
+- etc.
+
+Each plan file should follow this structure:
+
+\`\`\`markdown
+# Task: [Task Name]
+
+## Objective
+[Clear, one-sentence description of what this task accomplishes]
+
+## Context
+[Why this task is needed, how it fits into the larger project]
+
+## Dependencies
+[Optional section - omit if task has no dependencies]
+[Comma-separated list of task IDs this task depends on, e.g., "001, 002"]
+[If a dependency fails, this task will be automatically blocked]
+
+## Requirements
+[Specific requirements gathered from the user interview]
+- Requirement 1
+- Requirement 2
+- ...
+
+## Implementation Steps
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+...
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] All tests pass
+
+## Notes
+[Any additional context, warnings, or considerations]
+\`\`\`
+
+### Step 4: Infer Task Dependencies
+
+For each task, analyze which other tasks must complete successfully before it can begin. Add a \`## Dependencies\` section to plan files that have prerequisites.
+
+**How to identify dependencies:**
+- If task B uses output/artifacts from task A → B depends on A
+- If task B modifies code created by task A → B depends on A
+- If task B tests functionality from task A → B depends on A
+- If task B extends or builds upon task A → B depends on A
+
+**Dependency format examples:**
+\`\`\`markdown
+## Dependencies
+001
+\`\`\`
+or for multiple dependencies:
+\`\`\`markdown
+## Dependencies
+001, 002
+\`\`\`
+
+**Rules for dependencies:**
+- Only reference lower-numbered tasks (tasks are ordered by execution order)
+- Omit the Dependencies section entirely if a task has no prerequisites
+- Keep dependency lists minimal - only direct dependencies, not transitive ones
+- Never create circular dependencies (impossible if you only reference lower-numbered tasks)
+
+### Step 5: Confirm Completion
+
+After creating all plan files:
+1. Provide a summary of the tasks you've created
+2. Display this exit message to the user:
+
+\`\`\`
+Planning complete! To exit this session and run your tasks:
+  1. Press Ctrl-C twice to exit
+  2. Then run: raf do <project>
+\`\`\`
+
+## Important Rules
+
+1. ALWAYS interview the user before creating plans
+2. Create plans in numbered order (001, 002, 003, etc.) reflecting logical execution order
+3. Use descriptive, kebab-case names for plan files
+4. Each plan should be self-contained with all context needed
+5. Infer dependencies automatically - analyze task relationships, don't ask the user about dependencies
+6. Only add Dependencies section when a task genuinely requires another to complete first
+7. Dependencies must only reference lower-numbered tasks to prevent circular dependencies
+8. Be specific - vague plans lead to poor execution`;
+
+  const userMessage = `Here is my project description:
+
+${params.inputContent}
+
+Please analyze this and start the planning interview.`;
+
+  return { systemPrompt, userMessage };
+}

package/src/types/config.ts

@@ -0,0 +1,35 @@
+export interface RafConfig {
+  defaultTimeout: number;
+  defaultMaxRetries: number;
+  autoCommit: boolean;
+  claudeCommand: string;
+  editor?: string;
+}
+
+export const DEFAULT_RAF_CONFIG: RafConfig = {
+  defaultTimeout: 60,
+  defaultMaxRetries: 3,
+  autoCommit: true,
+  claudeCommand: 'claude',
+};
+
+export type ClaudeModelName = 'sonnet' | 'haiku' | 'opus';
+
+export interface PlanCommandOptions {
+  projectName?: string;
+  model?: ClaudeModelName;
+  sonnet?: boolean;
+}
+
+export interface DoCommandOptions {
+  timeout?: number;
+  verbose?: boolean;
+  debug?: boolean;
+  force?: boolean;
+  model?: ClaudeModelName;
+  sonnet?: boolean;
+}
+
+export interface StatusCommandOptions {
+  json?: boolean;
+}