whitesmith 0.0.1 → 0.0.3

package/README.md

@@ -4,13 +4,15 @@ AI-powered issue-to-PR pipeline. Whitesmith monitors your GitHub issues, breaks
 
 ## How It Works
 
-Whitesmith runs a loop with three phases:
+Whitesmith runs a loop with four phases:
 
-1. **Investigate** — Picks up unlabeled GitHub issues, explores the codebase, and breaks each issue into concrete implementation tasks (stored as markdown files in `tasks/<issue>/`). Opens a PR for human review.
+1. **Investigate** — Picks up unlabeled GitHub issues, explores the codebase, and breaks each issue into concrete implementation tasks (stored as markdown files in `tasks/<issue>/`). Opens a PR on `investigate/<issue-number>` for human review.
 
-2. **Implement** — Once a task PR is merged (tasks accepted), picks up available tasks respecting dependency order, implements the changes, deletes the task file, and opens a PR.
+2. **Auto-approve** *(optional)* — If [auto-work mode](#auto-work-mode) is enabled for an issue, the task-proposal PR is automatically merged (with an optional AI review first).
 
-3. **Reconcile** — When all tasks for an issue are completed and merged, closes the original issue.
+3. **Implement** — Once a task PR is merged (tasks accepted), picks up available tasks respecting dependency order, implements the changes on the `issue/<issue-number>` branch, deletes the task file, and opens a PR when all tasks are complete.
+
+4. **Reconcile** — When all tasks for an issue are completed and merged, closes the original issue.
 
 ### Issue Lifecycle
 
@@ -20,10 +22,50 @@ Issues move through labels automatically:
 (new issue, no labels)
   → whitesmith:investigating    — agent is generating tasks
   → whitesmith:tasks-proposed   — task PR opened for review
-  → whitesmith:tasks-accepted   — task PR merged, implementation begins
+  → whitesmith:tasks-accepted   — task PR merged (or auto-approved), implementation begins
   → whitesmith:completed        — all tasks done, issue closed
 ```
 
+### Labels
+
+| Label | Description |
+|---|---|
+| `whitesmith:investigating` | Agent is generating tasks for this issue |
+| `whitesmith:tasks-proposed` | A PR with generated tasks has been opened for review |
+| `whitesmith:tasks-accepted` | Task PR has been merged — implementation in progress |
+| `whitesmith:completed` | All tasks have been implemented and merged |
+| `whitesmith:auto-work` | Enables [auto-work mode](#auto-work-mode) for this issue |
+
+### Branch Naming Convention
+
+Whitesmith uses specific branch naming conventions:
+
+| Branch | Purpose |
+|---|---|
+| `investigate/<issue-number>` | Task proposal PRs — contains generated task files |
+| `issue/<issue-number>` | Implementation PRs — contains the actual code changes |
+
+### Review System
+
+After creating task-proposal PRs or implementation PRs, whitesmith automatically runs an AI review. Reviews produce a verdict:
+
+- **APPROVE** — The PR looks good
+- **REQUEST_CHANGES** — The review found issues that need attention
+
+The review is posted as a comment on the PR. Disable automatic reviews with the `--no-review` flag on the `run` command.
+
+### Auto-Work Mode
+
+Auto-work mode enables fully autonomous operation — task-proposal PRs are automatically merged without waiting for human review.
+
+Auto-work is enabled for an issue when **any** of these conditions are met:
+
+1. The `--auto-work` CLI flag is passed to `whitesmith run`
+2. The issue has the `whitesmith:auto-work` label
+3. The issue body contains the string `whitesmith:auto-work`
+
+When auto-work is enabled and the review system is active, whitesmith runs an AI review before merging. If the review returns REQUEST_CHANGES, the auto-merge is skipped and a comment is posted asking for manual review.
+
 ## Installation
 
 ```bash
@@ -40,7 +82,11 @@ npm install -g @mariozechner/pi-coding-agent
 
 ### 1. Configure AI Provider
 
-Whitesmith uses `pi` as its agent harness. Configure authentication by creating `~/.pi/agent/auth.json`:
+Whitesmith uses `pi` as its agent harness. You can configure authentication in two ways:
+
+#### Option A: `auth.json` (OAuth / API key)
+
+Create `~/.pi/agent/auth.json`:
 
 ```json
 {
@@ -51,6 +97,30 @@ Whitesmith uses `pi` as its agent harness. Configure authentication by creating
 }
 ```
 
+#### Option B: `models.json` (provider configuration)
+
+Create `~/.pi/agent/models.json` to configure providers with custom base URLs, API types, and models:
+
+```json
+{
+  "providers": {
+    "anthropic": {
+      "apiKey": "ANTHROPIC_API_KEY"
+    },
+    "my-custom-provider": {
+      "baseUrl": "https://api.example.com/v1",
+      "api": "openai-completions",
+      "apiKey": "MY_API_KEY",
+      "models": [{ "id": "my-model" }]
+    }
+  }
+}
+```
+
+For built-in providers (`anthropic`, `openai`), the `apiKey` field references an environment variable name that contains the actual key. For custom providers, you also specify `baseUrl`, `api` type (`anthropic-messages` or `openai-completions`), and available `models`.
+
+This is the default auth mode used by `install-ci` for CI/CD setups.
+
 ### 2. GitHub Authentication
 
 Whitesmith uses the `gh` CLI. Make sure you're authenticated:
@@ -61,12 +131,14 @@ gh auth login
 
 ## Usage
 
-### Run the Loop
+### `whitesmith run` — Run the Main Loop
 
 ```bash
 whitesmith run . --provider anthropic --model claude-opus-4-6
 ```
 
+Runs the full investigate → auto-approve → implement → reconcile loop.
+
 #### Options
 
 | Option | Description | Default |
@@ -79,8 +151,11 @@ whitesmith run . --provider anthropic --model claude-opus-4-6
 | `--log-file <path>` | Log agent output to file | — |
 | `--no-push` | Skip pushing branches and PR creation | `false` |
 | `--no-sleep` | Skip sleep between iterations | `false` |
+| `--dry-run` | Print what would be done without executing it | `false` |
+| `--auto-work` | Enable [auto-work mode](#auto-work-mode) (auto-approve task PRs) | `false` |
+| `--no-review` | Disable the automatic [review step](#review-system) after PRs are created | `false` |
 
-### Check Status
+### `whitesmith status` — Check Status
 
 ```bash
 whitesmith status .
@@ -88,94 +163,217 @@ whitesmith status .
 
 Shows all issues grouped by their whitesmith label and any pending tasks.
 
-### Reconcile
+#### Options
+
+| Option | Description | Default |
+|---|---|---|
+| `--repo <owner/repo>` | GitHub repo | auto-detected |
+
+### `whitesmith reconcile` — Reconcile Issues
 
 ```bash
 whitesmith reconcile .
 ```
 
-Checks for completed issues (all tasks merged) and closes them. No AI needed.
+Checks for completed issues (all tasks merged) and closes them. Also handles the `tasks-proposed` → `tasks-accepted` transition when a task PR has been merged. No AI needed.
 
-## GitHub Actions
+#### Options
+
+| Option | Description | Default |
+|---|---|---|
+| `--repo <owner/repo>` | GitHub repo | auto-detected |
+
+### `whitesmith comment` — Handle Comments
+
+```bash
+whitesmith comment . --number 42 --body "Please add tests" --provider anthropic --model claude-opus-4-6
+```
+
+Handles a comment on an issue or PR. Whitesmith auto-detects whether the target is a PR or an issue and handles each appropriately:
+
+- **PR comments**: Checks out the PR branch, lets the agent make changes, commits and pushes any modifications, and optionally posts a response.
+- **Issue comments**: The agent analyzes the issue and related context (task PRs, implementation PRs, pending tasks) and generates a response. If related PRs exist with open branches, the agent can check them out and make changes.
+
+#### Options
+
+| Option | Description | Default |
+|---|---|---|
+| `--number <n>` | Issue or PR number | *required* |
+| `--body <text>` | Comment body text | — |
+| `--body-file <path>` | Read comment body from a file (alternative to `--body`) | — |
+| `--provider <name>` | AI provider | *required* |
+| `--model <id>` | AI model ID | *required* |
+| `--agent-cmd <cmd>` | Agent harness command | `pi` |
+| `--repo <owner/repo>` | GitHub repo | auto-detected |
+| `--log-file <path>` | Log agent output to file | — |
+| `--post` | Post the response as a GitHub comment (otherwise prints to stdout) | `false` |
+
+Either `--body` or `--body-file` must be provided.
+
+### `whitesmith review` — Review PRs and Tasks
+
+```bash
+whitesmith review . --number 42 --provider anthropic --model claude-opus-4-6
+```
+
+Reviews a PR, task proposal, or completed task implementation. Produces a verdict: **APPROVE** or **REQUEST_CHANGES**.
+
+#### Review Types
+
+| Type | Description |
+|---|---|
+| `pr` | Review a generic PR (examine the diff, check for bugs, quality) |
+| `issue-tasks` | Review a task proposal — check that tasks are detailed and precise enough |
+| `issue-tasks-completed` | Review completed tasks — verify implementation follows the plan, check for bugs |
+
+If `--type` is omitted, the review type is auto-detected based on the target:
 
-Whitesmith can run on a schedule via GitHub Actions. Add the workflow file at `.github/workflows/whitesmith.yml`:
-
-```yaml
-name: whitesmith
-
-on:
-  schedule:
-    - cron: '*/15 * * * *'
-  workflow_dispatch:
-    inputs:
-      max_iterations:
-        description: 'Maximum iterations'
-        default: '3'
-        type: string
-      provider:
-        description: 'AI provider'
-        required: true
-        type: string
-      model:
-        description: 'AI model ID'
-        required: true
-        type: string
-
-concurrency:
-  group: whitesmith-loop
-  cancel-in-progress: false
-
-permissions:
-  contents: write
-  issues: write
-  pull-requests: write
-
-jobs:
-  run:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-
-      - name: Configure git
-        run: |
-          git config user.name "whitesmith[bot]"
-          git config user.email "whitesmith[bot]@users.noreply.github.com"
-
-      - name: Install whitesmith & pi
-        run: |
-          npm install -g whitesmith
-          npm install -g @mariozechner/pi-coding-agent
-
-      - name: Configure pi auth
-        run: |
-          mkdir -p ~/.pi/agent
-          echo '${{ secrets.PI_AUTH_JSON }}' > ~/.pi/agent/auth.json
-          chmod 600 ~/.pi/agent/auth.json
-
-      - name: Run whitesmith
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          whitesmith run . \
-            --agent-cmd "pi" \
-            --provider "${{ inputs.provider || vars.WHITESMITH_PROVIDER }}" \
-            --model "${{ inputs.model || vars.WHITESMITH_MODEL }}" \
-            --max-iterations ${{ inputs.max_iterations || '3' }}
-```
-
-### Required Configuration
-
-| Secret/Variable | Description |
+- PR on `investigate/<N>` branch → `issue-tasks`
+- PR on `issue/<N>` branch → `issue-tasks-completed`
+- Other PR → `pr`
+- Issue with `whitesmith:tasks-accepted` label → `issue-tasks-completed`
+- Issue with `whitesmith:tasks-proposed` label → `issue-tasks`
+
+#### Options
+
+| Option | Description | Default |
+|---|---|---|
+| `--number <n>` | PR or issue number to review | *required* |
+| `--type <type>` | Review type: `pr`, `issue-tasks`, `issue-tasks-completed` | auto-detected |
+| `--provider <name>` | AI provider | *required* |
+| `--model <id>` | AI model ID | *required* |
+| `--agent-cmd <cmd>` | Agent harness command | `pi` |
+| `--repo <owner/repo>` | GitHub repo | auto-detected |
+| `--log-file <path>` | Log agent output to file | — |
+| `--post` | Post the review as a GitHub comment (otherwise prints to stdout) | `false` |
+
+### `whitesmith install-ci` — Set Up GitHub Actions
+
+```bash
+whitesmith install-ci .
+```
+
+Interactive setup wizard that generates GitHub Actions workflows, a shared composite action, and configures GitHub secrets. This is the recommended way to set up whitesmith for CI/CD.
+
+#### What Gets Generated
+
+| File | Description |
 |---|---|
-| `PI_AUTH_JSON` (secret) | Contents of `~/.pi/agent/auth.json` — AI provider credentials |
-| `WHITESMITH_PROVIDER` (variable) | Default AI provider for scheduled runs |
-| `WHITESMITH_MODEL` (variable) | Default AI model for scheduled runs |
+| `.github/actions/setup-whitesmith/action.yml` | Composite action: Node.js setup, git config, install whitesmith + pi, configure auth |
+| `.github/workflows/whitesmith.yml` | Main workflow — manual dispatch for catch-up or debugging (event-driven workflows handle normal operation) |
+| `.github/workflows/whitesmith-issue.yml` | Triggered on new issues — begins investigation immediately |
+| `.github/workflows/whitesmith-comment.yml` | Responds to issue/PR comments (triggered by `/whitesmith` or comments on managed branches) |
+| `.github/workflows/whitesmith-reconcile.yml` | Reconciles on PR merge to `main` — triggers implementation or closes completed issues |
+| `.github/workflows/whitesmith-review.yml` | *(optional)* Reviews PRs on open/synchronize |
+
+#### Auth Modes
+
+- **`models-json`** *(default)* — Each provider's API key is stored as a separate GitHub secret. The setup wizard generates a `models.json` configuration inline in the composite action.
+- **`auth-json`** (`--auth-json` flag) — Uses a single `PI_AUTH_JSON` GitHub secret containing the full `auth.json` file. Also requires a `GH_PAT` secret for OAuth token refresh.
+
+#### Interactive Usage
+
+```bash
+whitesmith install-ci .
+```
+
+The wizard prompts you to:
+1. Add providers (Anthropic, OpenAI, or custom)
+2. Configure models for each provider
+3. Select default provider and model
+4. Enter API keys (set as GitHub secrets automatically)
+
+#### Non-Interactive Usage
+
+Export a configuration file:
+
+```bash
+whitesmith install-ci . --export-config config.json --include-secrets
+```
+
+Re-use the configuration later:
+
+```bash
+whitesmith install-ci . --config config.json
+```
+
+#### Options
+
+| Option | Description | Default |
+|---|---|---|
+| `--auth-json` | Use `auth.json` mode instead of `models.json` | `false` |
+| `--repo <owner/repo>` | GitHub repo | auto-detected |
+| `--fake` | Write workflows to `.fake/` instead of `.github/` (for testing) | `false` |
+| `--config <path>` | Load provider config from a JSON file (skip interactive prompts) | — |
+| `--export-config <path>` | Write the provider config as JSON to a file (instead of generating workflows) | — |
+| `--include-secrets` | With `--export-config`, prompt for API keys and include them in the JSON output | `false` |
+| `--no-secrets` | Skip setting GitHub secrets (useful when reconfiguring workflows only) | `false` |
+| `--dev` | Build whitesmith from source (pnpm) instead of npm install | `false` |
+| `--review-workflow` | Generate the optional PR review workflow | `false` |
+| `--no-review-step` | Disable the review step in the main loop (the review workflow will cover all PRs) | `false` |
+
+## GitHub Actions
+
+### Quick Setup
+
+The easiest way to set up GitHub Actions is with the `install-ci` command:
+
+```bash
+whitesmith install-ci .
+```
+
+This generates all necessary workflows, the shared setup action, and configures your GitHub secrets interactively. See [`whitesmith install-ci`](#whitesmith-install-ci--set-up-github-actions) for details.
+
+### Architecture
+
+The generated CI setup uses an **event-driven architecture** — whitesmith reacts to GitHub events immediately instead of polling on a schedule:
+
+- **Issue created** → investigate immediately
+- **Task PR merged** → implement immediately
+- **Implementation PR merged** → reconcile immediately
+- **Comment on issue/PR** → respond immediately
+- **Manual `workflow_dispatch`** → fallback for catch-up or debugging
+
+The setup consists of:
+
+1. **Composite action** (`.github/actions/setup-whitesmith/action.yml`) — Shared setup logic used by all workflows: installs Node.js, configures git, installs whitesmith + pi, sets up AI provider authentication. Supports npm caching for faster CI runs.
+
+2. **Issue workflow** (`whitesmith-issue.yml`) — Triggered when a new issue is opened. Runs `whitesmith run --issue <N>` to immediately begin investigation.
+
+3. **Main workflow** (`whitesmith.yml`) — Manual `workflow_dispatch` trigger for catch-up or debugging. Accepts an optional `issue` input to target a specific issue, or runs a global scan when omitted. Uses per-issue or global concurrency groups to prevent overlapping runs.
+
+4. **Comment workflow** (`whitesmith-comment.yml`) — Triggered by `issue_comment` events. Runs when:
+   - The comment body contains `/whitesmith` (slash command trigger)
+   - The comment is on a PR whose branch matches `investigate/*` or `task/*` (whitesmith-managed branches)
+
+   The workflow reacts to the comment with 👀, runs the agent, then reacts with 👍 on success or 👎 on failure.
+
+5. **Reconcile workflow** (`whitesmith-reconcile.yml`) — Triggered when a PR is merged to `main`. Handles two cases:
+   - **Task PR merged** (branch `investigate/<N>`) → runs `whitesmith run --issue <N>` to begin implementation immediately.
+   - **Implementation PR merged** (branch `issue/<N>`) or other merges → runs `whitesmith reconcile` to transition issue labels and close completed issues.
+
+6. **Review workflow** (`whitesmith-review.yml`, optional) — Triggered on PR open/synchronize. Runs an AI review and posts the result as a comment. When the review step is enabled in the main loop, this workflow skips whitesmith-managed branches (already reviewed inline). Pass `--review-workflow` to `install-ci` to generate this workflow.
+
+### Required Repository Settings
+
+Enable in your repository settings:
+
+**Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"**
+
+### Secrets
+
+Secrets are set automatically by `install-ci`, or can be added manually:
+
+**models-json mode** (default):
+- One secret per provider API key (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`)
+
+**auth-json mode** (`--auth-json`):
+- `PI_AUTH_JSON` — Contents of `~/.pi/agent/auth.json`
+- `GH_PAT` — GitHub personal access token with repo scope (for OAuth token refresh)
+
+### `/whitesmith` Slash Command
+
+In the comment workflow, any comment containing `/whitesmith` triggers the agent. This works on both issues and PRs. Comments on whitesmith-managed PR branches (`investigate/*` or `task/*`) also trigger automatically without needing the slash command.
 
 ## Task File Format
 

package/dist/auto-work.d.ts

@@ -0,0 +1,11 @@
+import type { DevPulseConfig, Issue } from './types.js';
+/**
+ * Check whether auto-work mode is enabled for a given issue.
+ *
+ * Returns true if any of these conditions are met:
+ * 1. `config.autoWork` is `true` (global config / CLI flag)
+ * 2. The issue has the `whitesmith:auto-work` label
+ * 3. The issue body contains the string `whitesmith:auto-work`
+ */
+export declare function isAutoWorkEnabled(config: DevPulseConfig, issue: Issue): boolean;
+//# sourceMappingURL=auto-work.d.ts.map

package/dist/auto-work.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-work.d.ts","sourceRoot":"","sources":["../src/auto-work.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,cAAc,EAAE,KAAK,EAAC,MAAM,YAAY,CAAC;AAGtD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAc/E"}

package/dist/auto-work.js

@@ -0,0 +1,22 @@
+import { LABELS } from './types.js';
+/**
+ * Check whether auto-work mode is enabled for a given issue.
+ *
+ * Returns true if any of these conditions are met:
+ * 1. `config.autoWork` is `true` (global config / CLI flag)
+ * 2. The issue has the `whitesmith:auto-work` label
+ * 3. The issue body contains the string `whitesmith:auto-work`
+ */
+export function isAutoWorkEnabled(config, issue) {
+    if (config.autoWork) {
+        return true;
+    }
+    if (issue.labels.includes(LABELS.AUTO_WORK)) {
+        return true;
+    }
+    if (issue.body.includes('whitesmith:auto-work')) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=auto-work.js.map

package/dist/auto-work.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-work.js","sourceRoot":"","sources":["../src/auto-work.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,MAAM,EAAC,MAAM,YAAY,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAsB,EAAE,KAAY;IACrE,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7C,OAAO,IAAI,CAAC;IACb,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AA2BlC,wBAAgB,QAAQ,IAAI,OAAO,CA4IlC;AAED,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AA8BlC,wBAAgB,QAAQ,IAAI,OAAO,CA2WlC;AAED,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE"}