software-engineer 0.1.20 → 0.1.22

package/README.md

@@ -1,6 +1,6 @@
 # software-engineer
 
-A CLI tool that automates the software development workflow using Claude AI. It runs a 7-step pipeline to implement features, simplify code, review, ensure quality, test, commit, and update changelogs.
+A CLI tool that automates the software development workflow using Claude AI. It runs an 8-step pipeline to implement features, simplify code, review, ensure quality, test, commit, and update changelogs with real-time progress visualization.
 
 ## Installation
 
@@ -13,6 +13,26 @@ npm install -g software-engineer
 - Node.js >= 18.0.0
 - [Claude CLI](https://github.com/anthropics/claude-code) installed and configured
 
+## Recommended Workflow
+
+For best results, follow this workflow:
+
+1. **Plan with Claude**: Start a Claude session and use plan mode to design what needs to be done
+   - Discuss requirements with Claude
+   - Iterate and refine the plan until it's complete
+   - Claude will generate a plan file (usually a `.md` file)
+
+2. **Execute with software-engineer**: Once your plan is finalized, close Claude and run:
+   ```bash
+   sf "implement the plan mentioned in /path/to/plan.md"
+   ```
+
+3. **Wait for completion**: The tool will automatically execute the entire pipeline and implement your plan
+
+This approach gives you the best of both worlds:
+- **Interactive planning** with Claude to ensure the approach is correct
+- **Automated execution** with comprehensive quality checks
+
 ## Usage
 
 ```bash
@@ -22,7 +42,10 @@ sf "<requirement>"
 ### Examples
 
 ```bash
-# Basic usage
+# Recommended: Use with a plan file from Claude
+sf "implement the plan mentioned in ./docs/feature-plan.md"
+
+# Basic usage with direct requirement
 sf "add user authentication with JWT"
 
 # Custom review iterations
@@ -44,8 +67,10 @@ sf --log pipeline.log "implement caching layer"
 |--------|-------------|
 | `-d, --dry-run` | Print commands without executing |
 | `-r, --reviews <n>` | Number of review iterations (default: 2) |
+| `-a, --adaptive` | Enable adaptive step execution (AI decides which steps to skip) |
 | `--skip-tests` | Skip the testing step |
 | `--skip-push` | Commit but don't push to remote |
+| `--skip-branch-management` | Skip smart branch management |
 | `--log <file>` | Log output to file |
 | `--dangerously-skip-permissions` | Skip Claude permission prompts |
 | `-h, --help` | Display help |
@@ -58,10 +83,12 @@ All options can be set via environment variables:
 | Variable | Description |
 |----------|-------------|
 | `SF_REVIEW_ITERATIONS` | Number of review iterations |
+| `SF_ADAPTIVE_EXECUTION` | `true`/`false` for adaptive execution |
 | `SF_DRY_RUN` | `true`/`false` for dry run |
 | `SF_LOG_FILE` | Path to log file |
 | `SF_SKIP_TESTS` | `true`/`false` to skip tests |
 | `SF_SKIP_PUSH` | `true`/`false` to skip push |
+| `SF_SKIP_BRANCH_MANAGEMENT` | `true`/`false` to skip branch management |
 | `SF_DANGEROUSLY_SKIP_PERMISSIONS` | `true`/`false` to skip Claude permissions |
 
 Example:
@@ -69,41 +96,63 @@ Example:
 SF_REVIEW_ITERATIONS=3 sf "add feature X"
 ```
 
-## Pipeline Steps
+## Features
 
-### 1. Implement
-Takes your requirement and asks Claude to implement it following project conventions.
+- **Real-time Progress Visualization**: See exactly what Claude is doing with colorized, emoji-enhanced output
+  - 📖 File reads in cyan
+  - ✍️ File writes in green
+  - ✏️ File edits in yellow
+  - ⚡ Command execution in magenta
+  - 🔍 Code searches in blue
+- **Smart Branch Management**: Automatically creates feature branches based on requirement type
+- **Adaptive Execution**: AI-powered step optimization that skips unnecessary stages
+- **Comprehensive Code Quality**: Multi-stage review process ensuring best practices
+
+## Pipeline Steps
 
-### 2. Code Simplification
-Refines the implementation for clarity, consistency, and maintainability while preserving functionality:
+### 1. Smart Branch Management
+Analyzes your requirement and automatically creates appropriate feature branches:
+- Detects change type (feature/fix/refactor/docs/chore)
+- Creates semantically named branches
+- Warns about potential conflicts
+
+### 2. Implement
+Claude understands your codebase and implements the requirement:
+- Analyzes project structure and patterns
+- Follows project conventions
+- Handles edge cases appropriately
+- Minimal, focused changes
+
+### 3. Code Simplification
+Refines the implementation for clarity, consistency, and maintainability:
 - Follows project standards (ES modules, explicit types)
 - Enhances clarity by avoiding nested ternaries
 - Removes redundant abstractions
 
-### 3. Code Review (configurable iterations)
+### 4. Code Review (configurable iterations)
 Reviews the implementation for:
 - Bugs (logic errors, null refs, race conditions)
 - Security issues (injection, auth problems)
 - Performance (N+1 queries, memory leaks)
 - Maintainability (clarity, naming, complexity)
 
-### 4. SOLID & Clean Code
+### 5. SOLID & Clean Code
 Ensures compliance with:
 - SOLID principles (SRP, OCP, LSP, ISP, DIP)
 - Clean code practices (naming, small functions, no magic numbers)
 
-### 5. Testing
+### 6. Testing
 - Runs existing tests
 - Adds new tests for changed code
 - Verifies coverage
 
-### 6. Commit
+### 7. Commit
 Creates a well-formatted commit with:
 - Conventional commit format
 - Clear subject line
 - Detailed body explaining why and what
 
-### 7. Changelog
+### 8. Changelog
 Updates CHANGELOG.md following Keep a Changelog format.
 
 ## License

package/dist/claude.js

@@ -1,8 +1,73 @@
 import spawn from 'cross-spawn';
+import chalk from 'chalk';
 import { logInfo, logSuccess, logError, logDryRun } from './logger.js';
 // Exit codes
 const EXIT_SUCCESS = 0;
 const EXIT_INTERRUPTED = 130;
+function formatToolCall(name, input) {
+    const toolColors = {
+        Read: 'cyan',
+        Write: 'green',
+        Edit: 'yellow',
+        Bash: 'magenta',
+        Grep: 'blue',
+        Glob: 'blue',
+    };
+    const color = toolColors[name] || 'white';
+    const colorFn = chalk[color];
+    if (name === 'Read' && input && typeof input === 'object' && 'file_path' in input) {
+        return colorFn(`📖 Reading: ${input.file_path}`);
+    }
+    if (name === 'Write' && input && typeof input === 'object' && 'file_path' in input) {
+        return colorFn(`✍️  Writing: ${input.file_path}`);
+    }
+    if (name === 'Edit' && input && typeof input === 'object' && 'file_path' in input) {
+        return colorFn(`✏️  Editing: ${input.file_path}`);
+    }
+    if (name === 'Bash' && input && typeof input === 'object' && 'description' in input) {
+        return colorFn(`⚡ Running: ${input.description}`);
+    }
+    if (name === 'Grep' && input && typeof input === 'object' && 'pattern' in input) {
+        return colorFn(`🔍 Searching: ${input.pattern}`);
+    }
+    if (name === 'Glob' && input && typeof input === 'object' && 'pattern' in input) {
+        return colorFn(`📁 Finding: ${input.pattern}`);
+    }
+    return colorFn(`🔧 ${name}`);
+}
+let lastPrintedMessage = '';
+function processStreamEvent(line) {
+    try {
+        const event = JSON.parse(line);
+        if (event.type === 'system' && event.subtype === 'init') {
+            console.log(chalk.dim('━'.repeat(60)));
+            console.log(chalk.bold.cyan('🤖 Claude is ready'));
+            console.log(chalk.dim('━'.repeat(60)));
+            lastPrintedMessage = ''; // Reset on new session
+            return;
+        }
+        if (event.type === 'assistant' && event.message?.content) {
+            for (const content of event.message.content) {
+                if (content.type === 'text' && content.text) {
+                    // Print assistant text responses (always print, don't deduplicate text)
+                    console.log(chalk.white(content.text));
+                    lastPrintedMessage = ''; // Reset after text message
+                }
+                else if (content.type === 'tool_use' && content.name) {
+                    // Print formatted tool calls (deduplicate consecutive identical messages)
+                    const message = formatToolCall(content.name, content.input);
+                    if (message !== lastPrintedMessage) {
+                        console.log(message);
+                        lastPrintedMessage = message;
+                    }
+                }
+            }
+        }
+    }
+    catch (error) {
+        // Silently ignore JSON parse errors for non-JSON lines
+    }
+}
 export async function runClaude(options, config) {
     // Build the full prompt with exit instruction (like Python version)
     const fullPrompt = `${options.prompt}. Once the work is completed, exit.`;
@@ -10,9 +75,8 @@ export async function runClaude(options, config) {
     if (config.dangerouslySkipPermissions) {
         args.push('--dangerously-skip-permissions');
     }
-    if (config.printOutput) {
-        args.push('-p');
-    }
+    // Always pass -p for output and add streaming JSON output format
+    args.push('-p', '--output-format=stream-json', '--verbose');
     if (options.continueConversation) {
         args.push('-c');
     }
@@ -24,16 +88,38 @@ export async function runClaude(options, config) {
     }
     logInfo('Calling Claude...');
     return new Promise((resolve) => {
-        // Spawn Claude using cross-spawn for cross-platform compatibility
-        // cross-spawn handles Windows .cmd/.bat files automatically without shell:true
-        // Use 'inherit' for stdio to allow Claude's interactive UI to work properly
+        let outputBuffer = '';
+        // Spawn Claude with piped stdio to capture stream-json output
         const child = spawn('claude', args, {
             cwd: process.cwd(),
             env: process.env,
-            stdio: 'inherit',
+            stdio: ['inherit', 'pipe', 'inherit'], // pipe stdout, inherit stdin and stderr
+        });
+        // Process stdout line by line
+        child.stdout?.on('data', (data) => {
+            const lines = data.toString().split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                if (i === lines.length - 1) {
+                    // Last line might be incomplete, buffer it
+                    outputBuffer += lines[i];
+                }
+                else {
+                    // Complete line, process it
+                    const line = outputBuffer + lines[i];
+                    outputBuffer = '';
+                    if (line.trim()) {
+                        processStreamEvent(line);
+                    }
+                }
+            }
         });
         // Handle process exit
         child.on('close', (exitCode) => {
+            // Process any remaining buffered output
+            if (outputBuffer.trim()) {
+                processStreamEvent(outputBuffer);
+            }
+            console.log(chalk.dim('━'.repeat(60)));
             if (exitCode === EXIT_INTERRUPTED || exitCode === 2) {
                 logError('Claude interrupted');
                 process.exit(EXIT_INTERRUPTED);

package/dist/config.d.ts

@@ -6,7 +6,6 @@ export interface Config {
     skipPush: boolean;
     skipBranchManagement: boolean;
     dangerouslySkipPermissions: boolean;
-    printOutput: boolean;
     requirement: string;
     adaptiveExecution: boolean;
 }

package/dist/config.js

@@ -19,7 +19,6 @@ export function loadConfigFromEnv() {
         skipPush: parseBoolEnv(process.env.SF_SKIP_PUSH, false),
         skipBranchManagement: parseBoolEnv(process.env.SF_SKIP_BRANCH_MANAGEMENT, false),
         dangerouslySkipPermissions: parseBoolEnv(process.env.SF_DANGEROUSLY_SKIP_PERMISSIONS, false),
-        printOutput: parseBoolEnv(process.env.SF_PRINT_OUTPUT, false),
         adaptiveExecution: parseBoolEnv(process.env.SF_ADAPTIVE_EXECUTION, false),
     };
 }
@@ -32,7 +31,6 @@ export function mergeConfig(envConfig, cliConfig) {
         skipPush: cliConfig.skipPush ?? envConfig.skipPush ?? false,
         skipBranchManagement: cliConfig.skipBranchManagement ?? envConfig.skipBranchManagement ?? false,
         dangerouslySkipPermissions: cliConfig.dangerouslySkipPermissions ?? envConfig.dangerouslySkipPermissions ?? false,
-        printOutput: cliConfig.printOutput ?? envConfig.printOutput ?? false,
         requirement: cliConfig.requirement ?? '',
         adaptiveExecution: cliConfig.adaptiveExecution ?? envConfig.adaptiveExecution ?? false,
     };

package/dist/index.js

@@ -4,9 +4,34 @@ import chalk from 'chalk';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import { createInterface } from 'readline';
 import { loadConfigFromEnv, mergeConfig } from './config.js';
 import { runPipeline } from './pipeline.js';
 import { checkForUpdates } from './utils/updateNotifier.js';
+async function promptForRequirement() {
+    console.log(chalk.cyan('Enter your requirement (press Ctrl+D or type END on a new line when done):'));
+    console.log(chalk.gray('─'.repeat(60)));
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: process.stdin.isTTY ?? false,
+    });
+    const lines = [];
+    return new Promise((resolve) => {
+        rl.on('line', (line) => {
+            if (line.trim().toUpperCase() === 'END') {
+                rl.close();
+            }
+            else {
+                lines.push(line);
+            }
+        });
+        rl.on('close', () => {
+            console.log(chalk.gray('─'.repeat(60)));
+            resolve(lines.join('\n').trim());
+        });
+    });
+}
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -15,7 +40,7 @@ program
     .name('sf')
     .description('Software Factory Pipeline - Automate development workflow with Claude AI')
     .version(pkg.version)
-    .argument('<requirement>', 'The requirement or task to implement')
+    .argument('[requirement]', 'The requirement or task to implement')
     .option('-d, --dry-run', 'Print commands without executing')
     .option('-r, --reviews <n>', 'Number of review iterations', '2')
     .option('-a, --adaptive', 'Enable adaptive step execution (AI decides which steps to skip)')
@@ -24,13 +49,17 @@ program
     .option('--skip-branch-management', 'Skip smart branch management')
     .option('--log <file>', 'Log output to file')
     .option('--dangerously-skip-permissions', 'Pass flag to claude to skip permission prompts')
-    .option('-p, --print', 'Print Claude output (pass -p to claude CLI)')
     .action(async (requirement, options) => {
     // Check for updates (non-blocking, fails silently)
     await checkForUpdates(pkg.name, pkg.version).catch(() => { });
+    // Prompt for requirement if not provided
+    let finalRequirement = requirement;
+    if (!finalRequirement) {
+        finalRequirement = await promptForRequirement();
+    }
     const envConfig = loadConfigFromEnv();
     const cliConfig = {
-        requirement,
+        requirement: finalRequirement,
         dryRun: options.dryRun ?? undefined,
         reviewIterations: options.reviews ? parseInt(options.reviews, 10) : undefined,
         skipTests: options.skipTests ?? undefined,
@@ -38,7 +67,6 @@ program
         skipBranchManagement: options.skipBranchManagement ?? undefined,
         logFile: options.log ?? undefined,
         dangerouslySkipPermissions: options.dangerouslySkipPermissions ?? undefined,
-        printOutput: options.print ?? undefined,
         adaptiveExecution: options.adaptive ?? undefined,
     };
     const config = mergeConfig(envConfig, cliConfig);

package/dist/pipeline.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { log, logHeader, setLogFile, logInfo } from './logger.js';
-import { stepBranchManagement, stepUnderstandCodebase, stepImplement, stepSimplify, stepReview, stepSolidCleanCode, stepTest, stepCommit, stepChangelog, } from './steps/index.js';
+import { stepBranchManagement, stepImplement, stepSimplify, stepReview, stepSolidCleanCode, stepTest, stepCommit, stepChangelog, } from './steps/index.js';
 let signalHandlersRegistered = false;
 export async function runPipeline(config) {
     // Setup logging
@@ -31,13 +31,7 @@ export async function runPipeline(config) {
     // Extract adaptive analysis for step decisions
     const adaptive = branchResult.adaptiveAnalysis;
     const rec = adaptive?.stepRecommendation;
-    // Step 2: Understand Codebase
-    const understandSuccess = await stepUnderstandCodebase(config);
-    if (!understandSuccess) {
-        console.log(chalk.red('\nUnderstand codebase step failed. Exiting.'));
-        process.exit(1);
-    }
-    // Step 3: Implement
+    // Step 2: Implement
     const implSuccess = await stepImplement(config);
     if (!implSuccess) {
         console.log(chalk.red('\nImplementation step failed. Exiting.'));

package/dist/steps/branchManagement.js

@@ -46,7 +46,7 @@ function branchMatchesRequirement(currentBranch, analysis) {
     return overlap || (prefixMatches && suggestedKeywords.length === 0);
 }
 export async function stepBranchManagement(config) {
-    logStep('1/9', 'SMART BRANCH MANAGEMENT');
+    logStep('1/8', 'SMART BRANCH MANAGEMENT');
     const adaptiveAnalysis = config.adaptiveExecution ? await performAdaptiveAnalysis(config) : null;
     if (config.skipBranchManagement) {
         logInfo('Branch management skipped (--skip-branch-management)');

package/dist/steps/changelog.js

@@ -1,7 +1,7 @@
 import { logStep } from '../logger.js';
 import { runClaude } from '../claude.js';
 export async function stepChangelog(config) {
-    logStep('9/9', 'UPDATE CHANGELOG');
+    logStep('8/8', 'UPDATE CHANGELOG');
     const prompt = `Update CHANGELOG.md:
 
 ## Format (Keep a Changelog):

package/dist/steps/commit.js

@@ -1,7 +1,7 @@
 import { logStep } from '../logger.js';
 import { runClaude } from '../claude.js';
 export async function stepCommit(config) {
-    logStep('8/9', 'COMMIT CHANGES');
+    logStep('7/8', 'COMMIT CHANGES');
     const pushInstruction = config.skipPush ? '' : 'Then push to remote.';
     const prompt = `Commit the changes:
 

package/dist/steps/implement.js

@@ -1,14 +1,15 @@
 import { logStep } from '../logger.js';
 import { runClaude } from '../claude.js';
 export async function stepImplement(config) {
-    logStep('3/9', 'IMPLEMENT REQUIREMENT');
+    logStep('2/8', 'IMPLEMENT REQUIREMENT');
     const prompt = `${config.requirement}
 
 ## Implementation Guidelines:
+- First, understand the codebase structure and identify relevant files for this requirement
 - Write clean, idiomatic code following project conventions
 - Handle edge cases and errors appropriately
 - Add necessary comments for complex logic
 - Keep changes focused and minimal. Once the work is completed, exit.`;
-    const result = await runClaude({ prompt, continueConversation: true }, config);
+    const result = await runClaude({ prompt }, config);
     return result.success;
 }

package/dist/steps/index.d.ts

@@ -1,5 +1,4 @@
 export { stepBranchManagement, type BranchResult } from './branchManagement.js';
-export { stepUnderstandCodebase } from './understand.js';
 export { stepImplement } from './implement.js';
 export { stepSimplify } from './simplify.js';
 export { stepReview, type ReviewResult, type ReviewDepth } from './review.js';

package/dist/steps/index.js

@@ -1,5 +1,4 @@
 export { stepBranchManagement } from './branchManagement.js';
-export { stepUnderstandCodebase } from './understand.js';
 export { stepImplement } from './implement.js';
 export { stepSimplify } from './simplify.js';
 export { stepReview } from './review.js';

package/dist/steps/review.js

@@ -60,7 +60,7 @@ function getPromptForDepth(depth) {
 }
 export async function stepReview(iteration, config, depth = 'standard') {
     const depthLabel = depth !== 'standard' ? ` [${depth}]` : '';
-    logStep('5/9', `CODE REVIEW (Round ${iteration}/${config.reviewIterations})${depthLabel}`);
+    logStep('4/8', `CODE REVIEW (Round ${iteration}/${config.reviewIterations})${depthLabel}`);
     const prompt = getPromptForDepth(depth);
     const result = await runClaude({ prompt, continueConversation: true }, config);
     const noIssuesFound = result.success && detectNoIssues(result.output);

package/dist/steps/simplify.js

@@ -1,7 +1,7 @@
 import { logStep } from '../logger.js';
 import { runClaude } from '../claude.js';
 export async function stepSimplify(config) {
-    logStep('4/9', 'CODE SIMPLIFICATION');
+    logStep('3/8', 'CODE SIMPLIFICATION');
     const prompt = `Refine the recently modified code for clarity, consistency, and maintainability while preserving all functionality.
 
 ## Core Principles:

package/dist/steps/solid.js

@@ -1,7 +1,7 @@
 import { logStep } from '../logger.js';
 import { runClaude } from '../claude.js';
 export async function stepSolidCleanCode(config) {
-    logStep('6/9', 'SOLID PRINCIPLES & CLEAN CODE');
+    logStep('5/8', 'SOLID PRINCIPLES & CLEAN CODE');
     const prompt = `Review the code for SOLID principles and Clean Code compliance:
 
 ## SOLID Principles:

package/dist/steps/test.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { logStep } from '../logger.js';
 import { runClaude } from '../claude.js';
 export async function stepTest(config) {
-    logStep('7/9', 'TESTING');
+    logStep('6/8', 'TESTING');
     if (config.skipTests) {
         console.log(chalk.yellow('[SKIPPED]') + ' Testing step skipped via configuration');
         return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "software-engineer",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "CLI that automates the full dev workflow with Claude AI - implement, review, test, and commit code with a single command",
   "type": "module",
   "main": "dist/index.js",