claude-intern 1.0.0 → 1.1.0

package/.env.sample

@@ -41,8 +41,5 @@ CLAUDE_CLI_PATH=claude
 
 # Note: Bitbucket workspace is automatically detected from your git remote URL
 
-# Optional: JIRA Status Transition After PR Creation
-# Set the status to transition the JIRA task to after successfully creating a PR
-# Common values: "In Review", "Code Review", "Under Review", "Ready for Review"
-# Leave empty or comment out to skip status transition
-# JIRA_PR_STATUS=In Review
+# Note: JIRA PR status transitions are now configured per-project in .claude-intern/settings.json
+# See settings.json for configuring different PR statuses for different JIRA projects

package/README.md

@@ -2,7 +2,23 @@
 
 Your AI intern for automatically implementing JIRA tasks using Claude. Supports both single task processing and batch processing of multiple tasks through JQL queries or explicit task lists. Pulls task details and feeds them to Claude for implementation with full automation of the development workflow.
 
-## Setup
+## Installation
+
+### Global Installation (Recommended)
+
+Install globally via npm to use from any directory:
+
+```bash
+# Install globally
+npm install -g claude-intern
+
+# Or use directly without installing
+npx claude-intern PROJ-123
+```
+
+### Local Development Setup
+
+For development or contributing to the project:
 
 1. Install Bun (if not already installed):
 
@@ -10,19 +26,71 @@ Your AI intern for automatically implementing JIRA tasks using Claude. Supports
 curl -fsSL https://bun.sh/install | bash
 ```
 
-2. Install dependencies:
+2. Clone and install dependencies:
 
 ```bash
+git clone https://github.com/danii1/claude-intern.git
+cd claude-intern
 bun install
 ```
 
-3. Copy `.env.sample` to `.env` and configure your JIRA credentials:
+3. (Optional) Install development version globally:
+
+```bash
+bun run install-global
+```
+
+## Configuration
+
+### Quick Setup with Init Command
+
+The easiest way to set up claude-intern for your project is using the `init` command:
+
+```bash
+# Initialize project-specific configuration
+claude-intern init
+```
+
+This creates a `.claude-intern` folder in your current project with:
+- `.env` - Your project-specific configuration file with JIRA credentials
+- `.env.sample` - Template with all configuration options
+- `settings.json` - Per-project settings (PR status transitions, etc.)
+
+**Automatic .gitignore Protection:** The `init` command automatically adds `.claude-intern/.env` to your `.gitignore` file (or creates one if it doesn't exist) to prevent accidentally committing credentials to version control.
+
+After running `init`:
+1. Edit `.claude-intern/.env` with your JIRA credentials
+2. (Optional) Edit `.claude-intern/settings.json` to configure per-project PR status transitions
+
+### Environment File Setup
+
+The tool searches for `.env` files in the following order:
+
+1. **Custom path** (if specified with `--env-file`)
+2. **Project-specific** (`.claude-intern/.env` - recommended)
+3. **Current working directory** (`.env`)
+4. **User home directory** (`~/.env`)
+5. **Tool installation directory**
+
+Configuration options:
 
 ```bash
+# Option 1: Project-specific (recommended)
+claude-intern init  # Creates .claude-intern/.env
+
+# Option 2: Current directory
 cp .env.sample .env
+
+# Option 3: Global configuration
+cp .env.sample ~/.env
+
+# Option 4: Custom location
+claude-intern PROJ-123 --env-file /path/to/custom.env
 ```
 
-4. Update `.env` with your JIRA details:
+### Required Configuration
+
+Update your `.env` file with your JIRA details:
 
    - `JIRA_BASE_URL`: Your JIRA instance URL (e.g., https://yourcompany.atlassian.net)
    - `JIRA_EMAIL`: Your JIRA email address
@@ -31,122 +99,145 @@ cp .env.sample .env
    Optional PR integration:
    - `GITHUB_TOKEN`: GitHub personal access token for creating pull requests
    - `BITBUCKET_TOKEN`: Bitbucket app password for creating pull requests
-   - `JIRA_PR_STATUS`: Auto-transition JIRA status after PR creation (e.g., "In Review")
 
    The `.env.sample` file includes helpful comments and optional configuration options.
 
-5. (Optional) Install globally to use from any directory:
+   **Note:** JIRA PR status transitions are now configured per-project in `settings.json` (see below).
 
-```bash
-bun run install-global
+### Per-Project Settings (settings.json)
+
+The `.claude-intern/settings.json` file allows you to configure project-specific behavior:
+
+```json
+{
+  "projects": {
+    "PROJ": {
+      "prStatus": "In Review"
+    },
+    "ABC": {
+      "prStatus": "Code Review"
+    }
+  }
+}
 ```
 
+**Configuration options:**
+- `prStatus`: JIRA status to transition to after PR creation for a specific project
+  - Each project key can have its own status workflow
+  - If not configured, no status transition will occur
+
+**Example:** If you work with multiple JIRA projects that have different workflows (e.g., "PROJ" uses "In Review" but "ABC" uses "Code Review"), configure each project's status in `settings.json`.
+
 ## Usage
 
 ### Single Task Processing
 
 ```bash
-# Run with a JIRA task key (automatically runs Claude)
-bun start TASK-123
+# Global installation usage (recommended)
+claude-intern TASK-123
 
-# Development mode (same as start with Bun)
-bun run dev TASK-123
+# Or use with npx (no installation needed)
+npx claude-intern TASK-123
 
 # Skip Claude and just fetch/format the task
-bun start TASK-123 -- --no-claude
+claude-intern TASK-123 --no-claude
 
 # Skip git branch creation
-bun start TASK-123 -- --no-git
+claude-intern TASK-123 --no-git
 
 # Use custom .env file
-bun start TASK-123 -- --env-file /path/to/custom.env
+claude-intern TASK-123 --env-file /path/to/custom.env
 
 # Specify custom output file
-bun start TASK-123 -- -o my-task.md
+claude-intern TASK-123 -o my-task.md
 
 # Verbose output for debugging
-bun start TASK-123 -- -v
+claude-intern TASK-123 -v
 
 # Custom Claude CLI path
-bun start TASK-123 -- --claude-path /path/to/claude
+claude-intern TASK-123 --claude-path /path/to/claude
 
 # Increase max turns for complex tasks
-bun start TASK-123 -- --max-turns 50
+claude-intern TASK-123 --max-turns 50
 
 # Skip automatic commit after Claude completes
-bun start TASK-123 -- --no-auto-commit
+claude-intern TASK-123 --no-auto-commit
 
 # Create pull request after implementation
-bun start TASK-123 -- --create-pr
+claude-intern TASK-123 --create-pr
 
 # Create pull request targeting specific branch
-bun start TASK-123 -- --create-pr --pr-target-branch develop
+claude-intern TASK-123 --create-pr --pr-target-branch develop
+
+# Testing options - skip ALL JIRA comments (feasibility + implementation)
+claude-intern TASK-123 --skip-jira-comments
+
+# Local testing without PR (commits stay local, no push to remote)
+# Simply omit --create-pr to skip pushing to remote
+claude-intern TASK-123 --skip-jira-comments
+```
+
+#### Local Development Usage
+
+```bash
+# Run with Bun during development
+bun start TASK-123
+
+# Development mode (same as start)
+bun run dev TASK-123
+
+# All options work with bun as well (note the -- separator)
+bun start TASK-123 -- --no-claude --verbose
 ```
 
 ### Batch Processing (Multiple Tasks)
 
 ```bash
 # Process multiple specific tasks
-bun start PROJ-123 PROJ-124 PROJ-125
+claude-intern PROJ-123 PROJ-124 PROJ-125
 
 # Process tasks matching JQL query
-bun start -- --jql "project = PROJ AND status = 'To Do'"
+claude-intern --jql "project = PROJ AND status = 'To Do'"
 
 # Complex JQL with custom fields and conditions
-bun start -- --jql "project = \"My Project\" AND cf[10016] <= 3 AND labels IN (FrontEnd, MobileApp)"
+claude-intern --jql "project = \"My Project\" AND cf[10016] <= 3 AND labels IN (FrontEnd, MobileApp)"
 
 # Batch process with PR creation
-bun start -- --jql "assignee = currentUser() AND status = 'To Do'" --create-pr
+claude-intern --jql "assignee = currentUser() AND status = 'To Do'" --create-pr
 
 # High-complexity batch processing with extended turns
-bun start -- --jql "labels = 'refactoring' AND type = Story" --max-turns 500 --create-pr
+claude-intern --jql "labels = 'refactoring' AND type = Story" --max-turns 500 --create-pr
 
 # Batch process with skipped clarity checks for faster processing
-bun start PROJ-101 PROJ-102 PROJ-103 -- --skip-clarity-check --create-pr
+claude-intern PROJ-101 PROJ-102 PROJ-103 --skip-clarity-check --create-pr
 ```
 
-### Examples
+#### Local Development Batch Processing
 
 ```bash
-# Fetch JIRA task and run Claude automatically
-bun start PROJ-456
-
-# Just fetch and format (useful for reviewing before Claude runs)
-bun start PROJ-456 -- --no-claude
-
-# Then manually run Claude with the formatted output
-claude -p --dangerously-skip-permissions --max-turns 10 < task-details.md
+# Process multiple tasks with Bun
+bun start PROJ-123 PROJ-124 PROJ-125
 
-# Development mode (same as start with Bun)
-bun run dev PROJ-456
+# JQL queries (note -- separator for options)
+bun start -- --jql "project = PROJ AND status = 'To Do'"
+bun start -- --jql "assignee = currentUser()" --create-pr
 ```
 
-### Global Usage (from any directory)
-
-After installing globally, you can run the tool from any directory (especially useful when working in your project's git repository):
+### Quick Examples
 
 ```bash
-# Single task processing
-claude-intern PROJ-123
-
-# Multiple task processing
-claude-intern PROJ-123 PROJ-124 PROJ-125
+# Fetch JIRA task and run Claude automatically
+claude-intern PROJ-456
 
-# JQL query processing
-claude-intern --jql "project = PROJ AND status = 'To Do'"
-claude-intern --jql "assignee = currentUser() AND labels = 'frontend' AND type = Bug"
+# Just fetch and format (useful for reviewing before Claude runs)
+claude-intern PROJ-456 --no-claude
 
-# All the same options work with batch processing
-claude-intern PROJ-123 PROJ-124 --no-claude --verbose
-claude-intern --jql "status = 'To Do'" --create-pr --pr-target-branch develop
-claude-intern --jql "priority = High" --max-turns 300 --skip-clarity-check
+# Then manually run Claude with the formatted output
+claude -p --dangerously-skip-permissions --max-turns 10 < task-details.md
 
 # Advanced batch scenarios
 claude-intern --jql "\"Epic Link\" = PROJ-100" --create-pr
 claude-intern --jql "sprint in openSprints() AND assignee = currentUser()" --max-turns 500
-
-# Uninstall when no longer needed
-bun run uninstall-global  # (run from claude-intern directory)
 ```
 
 ## What it does
@@ -161,13 +252,27 @@ bun run uninstall-global  # (run from claude-intern directory)
 
 3. Creates a feature branch named `feature/task-id` (e.g., `feature/proj-123`)
 
-4. Runs `claude -p` with enhanced permissions and extended conversation limits for automatic implementation
+4. Runs optional feasibility assessment to validate task clarity (skippable with `--skip-clarity-check`)
+   - Posts assessment results to JIRA (skippable with `--skip-jira-comments`)
+   - Saves assessment results for debugging:
+     - `{output-dir}/{task-key}/feasibility-assessment.md` (formatted results with JSON)
+     - `{output-dir}/{task-key}/feasibility-assessment-failed.txt` (raw output on parse failure)
 
-5. Automatically commits all changes with a descriptive commit message after Claude completes successfully
+5. Runs `claude -p` with enhanced permissions and extended conversation limits for automatic implementation
 
-6. Pushes the feature branch to remote repository (when creating PRs)
+6. Saves Claude's implementation summary to local files for analysis:
+   - `{output-dir}/{task-key}/implementation-summary.md` (successful)
+   - `{output-dir}/{task-key}/implementation-summary-incomplete.md` (incomplete/failed)
 
-7. Optionally creates pull requests on GitHub or Bitbucket with detailed implementation summaries
+7. Automatically commits all changes with a descriptive commit message after Claude completes successfully
+
+8. Pushes the feature branch to remote repository (when creating PRs)
+
+9. Optionally creates pull requests on GitHub or Bitbucket with detailed implementation summaries
+
+10. Posts implementation results back to JIRA as comments (skippable with `--skip-jira-comments`)
+    - Includes feasibility assessment results
+    - Includes implementation summary
 
 ## Requirements
 
@@ -178,10 +283,12 @@ bun run uninstall-global  # (run from claude-intern directory)
 
 ## Quick Start
 
-1. Install globally: `bun run install-global`
-2. Copy `.env.sample` to your project directory as `.env`
-3. Configure your JIRA credentials in `.env`
-4. Run from your project directory: `claude-intern PROJ-123`
+1. Install globally: `npm install -g claude-intern`
+2. Initialize your project: `claude-intern init`
+3. Configure your JIRA credentials in `.claude-intern/.env`
+4. Run from any directory: `claude-intern PROJ-123`
+
+**Alternative:** For global configuration across all projects, place `.env` in your home directory (`~/.env`)
 
 See [USAGE.md](./USAGE.md) for detailed usage scenarios and troubleshooting.  
 See [GLOBAL_USAGE.md](./GLOBAL_USAGE.md) for quick reference on global installation.