software-engineer 0.1.21 → 0.1.23

package/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+By default, Claude is automatically granted permission to **Edit, Read, and Bash** tools, allowing seamless autonomous operation without constant permission prompts.
+
 ## Installation
 
 ```bash
@@ -13,6 +15,27 @@ 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
+- **Seamless operation** - Claude automatically has permission to edit files, read code, and run commands without prompts
+
 ## Usage
 
 ```bash
@@ -22,7 +45,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
@@ -38,6 +64,46 @@ sf --skip-tests --skip-push "update README"
 sf --log pipeline.log "implement caching layer"
 ```
 
+## Permission Management
+
+By default, `software-engineer` automatically grants Claude permission to use **Edit, Read, and Bash** tools without prompting. This streamlines the workflow while maintaining control over file operations.
+
+### Default Behavior
+
+When you run the tool, it automatically passes `--allowedTools "Edit,Read,Bash"` to Claude:
+- **Edit**: Modify existing files
+- **Read**: Read file contents
+- **Bash**: Execute shell commands (git, npm, build tools, etc.)
+
+This means Claude can work autonomously on your codebase without constant permission prompts, making the pipeline smooth and efficient.
+
+### Customizing Allowed Tools
+
+You can customize which tools are auto-approved:
+
+```bash
+# Allow additional tools
+sf --allowedTools "Edit,Read,Write,Bash,Grep" "add new feature"
+
+# Via environment variable
+SF_ALLOWED_TOOLS="Edit,Read,Write,Bash" sf "implement caching"
+
+# Restrict to read-only operations
+sf --allowedTools "Read,Grep,Glob" "analyze the codebase"
+```
+
+### Skipping All Permissions (Use with Caution)
+
+For fully autonomous operation in trusted environments (like CI/CD), you can skip all permission checks:
+
+```bash
+sf --dangerously-skip-permissions "implement feature"
+```
+
+**Warning**: This bypasses ALL permission prompts. Only use in isolated, secure environments.
+
+**Note**: When `--dangerously-skip-permissions` is used, the `allowedTools` setting is ignored.
+
 ## Options
 
 | Option | Description |
@@ -49,7 +115,8 @@ sf --log pipeline.log "implement caching layer"
 | `--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 |
+| `--allowedTools <tools>` | Comma-separated list of allowed tools (default: "Edit,Read,Bash") |
+| `--dangerously-skip-permissions` | Skip Claude permission prompts (overrides allowedTools) |
 | `-h, --help` | Display help |
 | `-V, --version` | Display version |
 
@@ -66,7 +133,8 @@ All options can be set via environment variables:
 | `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 |
+| `SF_ALLOWED_TOOLS` | Comma-separated list of allowed tools (default: "Edit,Read,Bash") |
+| `SF_DANGEROUSLY_SKIP_PERMISSIONS` | `true`/`false` to skip Claude permissions (overrides allowedTools) |
 
 Example:
 ```bash
@@ -75,6 +143,7 @@ SF_REVIEW_ITERATIONS=3 sf "add feature X"
 
 ## Features
 
+- **Automatic Permission Management**: Claude is pre-authorized to Edit, Read, and execute Bash commands by default - no constant permission prompts
 - **Real-time Progress Visualization**: See exactly what Claude is doing with colorized, emoji-enhanced output
   - 📖 File reads in cyan
   - ✍️ File writes in green

package/dist/claude.js

@@ -75,6 +75,9 @@ export async function runClaude(options, config) {
     if (config.dangerouslySkipPermissions) {
         args.push('--dangerously-skip-permissions');
     }
+    else if (config.allowedTools) {
+        args.push('--allowedTools', config.allowedTools);
+    }
     // Always pass -p for output and add streaming JSON output format
     args.push('-p', '--output-format=stream-json', '--verbose');
     if (options.continueConversation) {

package/dist/config.d.ts

@@ -6,8 +6,10 @@ export interface Config {
     skipPush: boolean;
     skipBranchManagement: boolean;
     dangerouslySkipPermissions: boolean;
+    allowedTools?: string;
     requirement: string;
     adaptiveExecution: boolean;
+    implementationOnly: boolean;
 }
 export declare function loadConfigFromEnv(): Partial<Config>;
 export declare function mergeConfig(envConfig: Partial<Config>, cliConfig: Partial<Config>): Config;

package/dist/config.js

@@ -19,10 +19,17 @@ 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),
+        allowedTools: process.env.SF_ALLOWED_TOOLS || undefined,
         adaptiveExecution: parseBoolEnv(process.env.SF_ADAPTIVE_EXECUTION, false),
+        implementationOnly: parseBoolEnv(process.env.SF_IMPLEMENTATION_ONLY, false),
     };
 }
 export function mergeConfig(envConfig, cliConfig) {
+    const dangerouslySkipPermissions = cliConfig.dangerouslySkipPermissions ?? envConfig.dangerouslySkipPermissions ?? false;
+    // Set default allowedTools to "Edit,Read,Bash" unless dangerouslySkipPermissions is true
+    const allowedTools = dangerouslySkipPermissions
+        ? undefined
+        : (cliConfig.allowedTools ?? envConfig.allowedTools ?? 'Edit,Read,Bash');
     return {
         reviewIterations: cliConfig.reviewIterations ?? envConfig.reviewIterations ?? DEFAULT_REVIEW_ITERATIONS,
         dryRun: cliConfig.dryRun ?? envConfig.dryRun ?? false,
@@ -30,8 +37,10 @@ export function mergeConfig(envConfig, cliConfig) {
         skipTests: cliConfig.skipTests ?? envConfig.skipTests ?? false,
         skipPush: cliConfig.skipPush ?? envConfig.skipPush ?? false,
         skipBranchManagement: cliConfig.skipBranchManagement ?? envConfig.skipBranchManagement ?? false,
-        dangerouslySkipPermissions: cliConfig.dangerouslySkipPermissions ?? envConfig.dangerouslySkipPermissions ?? false,
+        dangerouslySkipPermissions,
+        allowedTools,
         requirement: cliConfig.requirement ?? '',
         adaptiveExecution: cliConfig.adaptiveExecution ?? envConfig.adaptiveExecution ?? false,
+        implementationOnly: cliConfig.implementationOnly ?? envConfig.implementationOnly ?? false,
     };
 }

package/dist/index.js

@@ -47,8 +47,10 @@ program
     .option('--skip-tests', 'Skip the testing step')
     .option('--skip-push', 'Commit but do not push')
     .option('--skip-branch-management', 'Skip smart branch management')
+    .option('--implementation-only', 'Run only: Implement → Review → SOLID (skips branch, tests, commit)')
     .option('--log <file>', 'Log output to file')
     .option('--dangerously-skip-permissions', 'Pass flag to claude to skip permission prompts')
+    .option('--allowedTools <tools>', 'Comma-separated list of allowed tools (default: "Edit,Read,Bash")')
     .action(async (requirement, options) => {
     // Check for updates (non-blocking, fails silently)
     await checkForUpdates(pkg.name, pkg.version).catch(() => { });
@@ -67,9 +69,23 @@ program
         skipBranchManagement: options.skipBranchManagement ?? undefined,
         logFile: options.log ?? undefined,
         dangerouslySkipPermissions: options.dangerouslySkipPermissions ?? undefined,
+        allowedTools: options.allowedTools ?? undefined,
         adaptiveExecution: options.adaptive ?? undefined,
+        implementationOnly: options.implementationOnly ?? undefined,
     };
     const config = mergeConfig(envConfig, cliConfig);
+    // Handle implementation-only mode
+    if (config.implementationOnly) {
+        // Implementation-only mode automatically skips branch management and tests
+        config.skipBranchManagement = true;
+        config.skipTests = true;
+        // Warn if adaptive execution was explicitly requested but will be overridden
+        const adaptiveWasRequested = options.adaptive || process.env.SF_ADAPTIVE_EXECUTION === 'true';
+        if (config.adaptiveExecution && adaptiveWasRequested) {
+            console.log(chalk.yellow('⚠ Implementation-only mode overrides --adaptive flag'));
+        }
+        config.adaptiveExecution = false;
+    }
     if (!config.requirement) {
         console.error(chalk.red('Error:') + ' No requirement provided');
         program.help();

package/dist/logger.d.ts

@@ -6,6 +6,8 @@ export declare function logHeader(config: {
     reviewIterations: number;
     dryRun: boolean;
     dangerouslySkipPermissions: boolean;
+    allowedTools?: string;
+    implementationOnly: boolean;
 }): void;
 export declare function logSuccess(message: string): void;
 export declare function logError(message: string): void;

package/dist/logger.js

@@ -52,12 +52,19 @@ export function logHeader(config) {
     const authorLine = ' '.repeat(authorPadding) + author + ' '.repeat(BOX_WIDTH - authorPadding - author.length);
     console.log(chalk.green('║') + chalk.dim(authorLine) + chalk.green('║'));
     console.log(chalk.green(`╠${line}╣`));
-    const configLine = ` Reviews: ${config.reviewIterations} | Dry-run: ${config.dryRun}`;
+    let configLine = ` Reviews: ${config.reviewIterations} | Dry-run: ${config.dryRun}`;
+    if (config.implementationOnly) {
+        configLine += ' | Mode: implementation-only';
+    }
     console.log(chalk.green('║') + configLine.padEnd(BOX_WIDTH) + chalk.green('║'));
     if (config.dangerouslySkipPermissions) {
         const permLine = ' ' + chalk.yellow('⚠ Skip permissions: enabled');
         console.log(chalk.green('║') + permLine + ' '.repeat(BOX_WIDTH - stripAnsi(permLine).length) + chalk.green('║'));
     }
+    else if (config.allowedTools) {
+        const toolsLine = ' ' + chalk.cyan(`🔓 Allowed tools: ${config.allowedTools}`);
+        console.log(chalk.green('║') + toolsLine + ' '.repeat(BOX_WIDTH - stripAnsi(toolsLine).length) + chalk.green('║'));
+    }
     console.log(chalk.green(`╚${line}╝`));
     console.log();
 }

package/dist/pipeline.js

@@ -1,7 +1,39 @@
 import chalk from 'chalk';
 import { log, logHeader, setLogFile, logInfo } from './logger.js';
 import { stepBranchManagement, stepImplement, stepSimplify, stepReview, stepSolidCleanCode, stepTest, stepCommit, stepChangelog, } from './steps/index.js';
+const EXIT_CODE_FAILURE = 1;
+const EXIT_CODE_INTERRUPT = 130;
 let signalHandlersRegistered = false;
+function exitWithError(message) {
+    console.log(chalk.red(`\n${message}`));
+    process.exit(EXIT_CODE_FAILURE);
+}
+function getSkipReason(implementationOnly, primaryReason, fallbackReason) {
+    return implementationOnly ? 'implementation-only mode' : primaryReason;
+}
+function determineSkipTestsReason(config, rec) {
+    if (config.implementationOnly)
+        return 'implementation-only mode';
+    if (rec?.skipTests)
+        return 'adaptive execution';
+    if (config.skipTests)
+        return '--skip-tests';
+    return null;
+}
+function displayImplementationOnlyBanner() {
+    console.log(chalk.cyan('▶ Running in IMPLEMENTATION-ONLY mode'));
+    console.log(chalk.cyan('▶ Steps: Implement → Review → SOLID'));
+    console.log(chalk.dim('▶ Skipping: Branch Management, Simplify, Tests, Commit, Changelog\n'));
+}
+function displayCompletionMessage(implementationOnly) {
+    if (implementationOnly) {
+        console.log(chalk.green('\n✓ Implementation-only pipeline completed successfully'));
+        console.log(chalk.yellow('⚠ Changes are not committed - review and commit manually when ready\n'));
+    }
+    else {
+        console.log(chalk.green('\n✓ Pipeline completed successfully\n'));
+    }
+}
 export async function runPipeline(config) {
     // Setup logging
     if (config.logFile) {
@@ -11,44 +43,54 @@ export async function runPipeline(config) {
     if (!signalHandlersRegistered) {
         process.on('SIGINT', () => {
             console.log(chalk.red('\n\nPipeline interrupted'));
-            process.exit(130);
+            process.exit(EXIT_CODE_INTERRUPT);
         });
         process.on('SIGTERM', () => {
             console.log(chalk.red('\n\nPipeline terminated'));
-            process.exit(130);
+            process.exit(EXIT_CODE_INTERRUPT);
         });
         signalHandlersRegistered = true;
     }
     // Display header
     logHeader(config);
+    if (config.implementationOnly) {
+        displayImplementationOnlyBanner();
+    }
     log(`Starting pipeline for: ${config.requirement}`);
-    // Step 1: Smart Branch Management (also performs adaptive analysis if enabled)
-    const branchResult = await stepBranchManagement(config);
-    if (!branchResult.success) {
-        console.log(chalk.red('\nBranch management step failed. Exiting.'));
-        process.exit(1);
-    }
-    // Extract adaptive analysis for step decisions
-    const adaptive = branchResult.adaptiveAnalysis;
-    const rec = adaptive?.stepRecommendation;
+    // Step 1: Smart Branch Management
+    let adaptive = null;
+    let rec = null;
+    const shouldSkipBranchManagement = config.implementationOnly || config.skipBranchManagement;
+    if (shouldSkipBranchManagement) {
+        const reason = getSkipReason(config.implementationOnly, '--skip-branch-management', '--skip-branch-management');
+        logInfo(`Branch management step skipped (${reason})`);
+    }
+    else {
+        const branchResult = await stepBranchManagement(config);
+        if (!branchResult.success) {
+            exitWithError('Branch management step failed. Exiting.');
+        }
+        adaptive = branchResult.adaptiveAnalysis;
+        rec = adaptive?.stepRecommendation;
+    }
     // Step 2: Implement
     const implSuccess = await stepImplement(config);
     if (!implSuccess) {
-        console.log(chalk.red('\nImplementation step failed. Exiting.'));
-        process.exit(1);
+        exitWithError('Implementation step failed. Exiting.');
     }
-    // Step 4: Simplify (can be skipped by adaptive execution)
-    if (rec?.skipSimplify) {
-        logInfo('Simplify step skipped (adaptive execution)');
+    // Step 3: Simplify
+    const shouldSkipSimplify = config.implementationOnly || rec?.skipSimplify;
+    if (shouldSkipSimplify) {
+        const reason = getSkipReason(config.implementationOnly, 'adaptive execution', 'adaptive execution');
+        logInfo(`Simplify step skipped (${reason})`);
     }
     else {
         const simplifySuccess = await stepSimplify(config);
         if (!simplifySuccess) {
-            console.log(chalk.red('\nSimplification step failed. Exiting.'));
-            process.exit(1);
+            exitWithError('Simplification step failed. Exiting.');
         }
     }
-    // Step 5: Review loop (can be skipped or adjusted by adaptive execution)
+    // Step 5: Review loop
     if (rec?.skipReview) {
         logInfo('Review step skipped (adaptive execution)');
     }
@@ -57,61 +99,56 @@ export async function runPipeline(config) {
         for (let i = 1; i <= reviewIterations; i++) {
             const reviewResult = await stepReview(i, config, rec?.reviewDepth);
             if (!reviewResult.success) {
-                console.log(chalk.red('\nReview step failed. Exiting.'));
-                process.exit(1);
+                exitWithError('Review step failed. Exiting.');
             }
-            // Skip remaining reviews if no issues were found
             if (reviewResult.noIssuesFound) {
                 console.log(chalk.green('\n✓ Code review passed - no issues found, skipping remaining reviews'));
                 break;
             }
         }
     }
-    // Step 6: SOLID & Clean Code (can be skipped by adaptive execution)
+    // Step 6: SOLID & Clean Code
     if (rec?.skipSolid) {
         logInfo('SOLID review step skipped (adaptive execution)');
     }
     else {
         const solidSuccess = await stepSolidCleanCode(config);
         if (!solidSuccess) {
-            console.log(chalk.red('\nSOLID review step failed. Exiting.'));
-            process.exit(1);
+            exitWithError('SOLID review step failed. Exiting.');
         }
     }
-    // Step 7: Test (can be skipped by adaptive execution or CLI flag)
-    let skipTestsReason = null;
-    if (rec?.skipTests) {
-        skipTestsReason = 'adaptive execution';
-    }
-    else if (config.skipTests) {
-        skipTestsReason = '--skip-tests';
-    }
+    // Step 7: Test
+    const skipTestsReason = determineSkipTestsReason(config, rec);
     if (skipTestsReason) {
         logInfo(`Test step skipped (${skipTestsReason})`);
     }
     else {
         const testSuccess = await stepTest(config);
         if (!testSuccess) {
-            console.log(chalk.red('\nTest step failed. Exiting.'));
-            process.exit(1);
+            exitWithError('Test step failed. Exiting.');
         }
     }
     // Step 8: Commit
-    const commitSuccess = await stepCommit(config);
-    if (!commitSuccess) {
-        console.log(chalk.red('\nCommit step failed. Exiting.'));
-        process.exit(1);
+    if (config.implementationOnly) {
+        logInfo('Commit step skipped (implementation-only mode)');
+    }
+    else {
+        const commitSuccess = await stepCommit(config);
+        if (!commitSuccess) {
+            exitWithError('Commit step failed. Exiting.');
+        }
     }
-    // Step 9: Changelog (can be skipped by adaptive execution)
-    if (rec?.skipChangelog) {
-        logInfo('Changelog step skipped (adaptive execution)');
+    // Step 9: Changelog
+    const shouldSkipChangelog = config.implementationOnly || rec?.skipChangelog;
+    if (shouldSkipChangelog) {
+        const reason = getSkipReason(config.implementationOnly, 'adaptive execution', 'adaptive execution');
+        logInfo(`Changelog step skipped (${reason})`);
     }
     else {
         const changelogSuccess = await stepChangelog(config);
         if (!changelogSuccess) {
-            console.log(chalk.red('\nChangelog step failed. Exiting.'));
-            process.exit(1);
+            exitWithError('Changelog step failed. Exiting.');
         }
     }
-    console.log(chalk.green('\n✓ Pipeline completed successfully\n'));
+    displayCompletionMessage(config.implementationOnly);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "software-engineer",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "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",