software-engineer

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.

The Brain

Installation

npm install -g software-engineer

Prerequisites

• Node.js >= 18.0.0
• Claude CLI 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:

   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

sf "<requirement>"

Examples

# 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
sf --reviews 3 "refactor database layer"

# Dry run to preview commands
sf --dry-run "add dark mode toggle"

# Skip tests and push
sf --skip-tests --skip-push "update README"

# Log output to file
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:

# 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:

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.

Run Individual Stages

You can run specific pipeline stages directly without executing the full pipeline. This is useful for running a quick review or cleanup on code you've already written.

# Run only the code simplification step
sf --simplify

# Run only the code review step
sf --review

# Run only the SOLID & clean code check
sf --clean-code

# Run only the testing step
sf --test

# Run only the commit step
sf --commit

# Run only the implementation step (requires a requirement)
sf --implement "add error handling to the API"

# Combine multiple stages (executed in pipeline order)
sf --simplify --review --clean-code

# Works with other options
sf --review -r 3         # 3 review iterations
sf --review --dry-run    # Preview without executing

Note: All stages except --implement work without a requirement — they operate on the current state of your code. You can combine multiple stage flags and they will run in pipeline order.

Options

| Option | Description | |--------|-------------| | -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 | | --implementation-only | Run only: Implement → Review → SOLID | | --implement | Run only the implementation step | | --simplify | Run only the code simplification step | | --review | Run only the code review step | | --clean-code | Run only the SOLID & clean code step | | --test | Run only the testing step | | --commit | Run only the commit step | | --changelog | Run only the changelog step | | --log <file> | Log output to file | | --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 |

Environment Variables

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_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:

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
  • ✏️ 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

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

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)

5. SOLID & Clean Code

Ensures compliance with:

• SOLID principles (SRP, OCP, LSP, ISP, DIP)
• Clean code practices (naming, small functions, no magic numbers)

6. Testing

• Runs existing tests
• Adds new tests for changed code
• Verifies coverage

7. Commit

Creates a well-formatted commit with:

• Conventional commit format
• Clear subject line
• Detailed body explaining why and what

8. Changelog

Updates CHANGELOG.md following Keep a Changelog format.

License

MIT