Merge pull request #75 from Blazity/dev

kasin-it · web-flow · commit 169fe677ae7e · 2026-05-08T15:44:47.000+02:00
feat: update .env.example
diff --git a/.env.example b/.env.example
@@ -34,11 +34,17 @@ GITHUB_BASE_BRANCH=main
 # GITLAB_BASE_BRANCH=main
 # GITLAB_HOST=https://gitlab.com       # override for self-hosted GitLab
 
-# Messaging (Chat SDK)
+# Messaging (Chat SDK) — optional. When SLACK_TOKEN+CHANNEL_ID are unset, a no-op
+# adapter is used and runs proceed silently.
 CHAT_SDK_SLACK_TOKEN=xoxb-xxxxxxxxxxxx
 CHAT_SDK_CHANNEL_ID=C0123456789
 CHAT_SDK_BOT_NAME=blazebot
 
+# Slack slash commands — required only if you register the /ai-workflow command.
+# When unset, /webhooks/slack rejects all requests.
+# SLACK_SIGNING_SECRET=
+# SLACK_ALLOWED_USER_IDS=U0123,U4567   # comma-separated allowlist; empty = anyone
+
 # Agent — choose runtime (claude | codex). Defaults to claude.
 AGENT_KIND=claude
 
@@ -91,6 +97,9 @@ JOB_TIMEOUT_MS=1800000
 # Polling
 POLL_INTERVAL_MS=300000
 
+# Phase 3 (Review) — opt-in self-review pass after implementation, before push.
+# ENABLE_REVIEW_PHASE=false
+
 # Vercel Sandbox (LOCAL DEV ONLY — on Vercel, OIDC authenticates automatically)
 # VERCEL_TOKEN=
 # VERCEL_TEAM_ID=
diff --git a/README.md b/README.md
@@ -68,298 +68,9 @@ flowchart TD
 | Logging | [Pino](https://getpino.io) | Structured JSON logs |
 | Testing | [Vitest](https://vitest.dev) | Unit and E2E tests |
 
-## Getting Started
-
-### Prerequisites
-
-- **Node.js** 20+
-- **pnpm** 10+
-- **Vercel CLI** — `npm i -g vercel@latest`
-- **Accounts** — you'll need credentials for:
-  - [Jira](https://www.atlassian.com/software/jira) (API token)
-  - [GitHub](https://github.com) (personal access token with repo scope)
-  - [Slack](https://slack.com) (bot token with `chat:write` scope)
-  - [Anthropic](https://console.anthropic.com) (API key)
-  - [Upstash](https://upstash.com) (Redis database)
-
-### 1. Clone and install
-
-```bash
-git clone https://github.com/Blazity/ai-workflow.git
-cd ai-workflow
-pnpm install
-```
-
-### 2. Link to Vercel
-
-ai workflow runs on Vercel and uses OIDC for Sandbox authentication. Link the project first:
-
-```bash
-vercel link
-```
-
-Follow the prompts to connect to your Vercel team and project.
-
-### 3. Configure environment variables
-
-Copy the example file and fill in your credentials:
-
-```bash
-cp .env.example .env
-```
-
-Walk through each section:
-
-**Jira** — Your Atlassian instance and API credentials:
-```bash
-JIRA_BASE_URL=https://your-domain.atlassian.net
-JIRA_EMAIL=your-email@example.com
-JIRA_API_TOKEN=your-jira-api-token    # Generate at https://id.atlassian.com/manage-profile/security/api-tokens
-JIRA_PROJECT_KEY=PROJ                  # Your Jira project key (e.g., AWT)
-JIRA_WEBHOOK_SECRET=                   # Optional: openssl rand -hex 32. Without it, dispatch falls back to 1-min cron polling.
-```
-
-> The Jira webhook is registered separately (see [SETUP.md § 8](./SETUP.md#8-register-the-jira-webhook)). The handler at `/webhooks/jira` verifies an `X-Hub-Signature` HMAC-SHA256 header.
-
-**Jira columns** — The board column names ai workflow watches and moves tickets between:
-```bash
-COLUMN_AI=AI                # Column where tickets are assigned to the agent
-COLUMN_AI_REVIEW=AI Review  # Column where completed tickets go for human review
-COLUMN_BACKLOG=Backlog      # Column where tickets go when clarification is needed
-```
-
-**VCS** — Choose `github` or `gitlab`. Only fill the block matching your provider.
-
-```bash
-VCS_KIND=github
-
-# GitHub (active when VCS_KIND=github)
-GITHUB_TOKEN=ghp_xxxxxxxxxxxx          # Personal access token with repo scope
-GITHUB_OWNER=your-org                  # GitHub org or username
-GITHUB_REPO=your-repo                  # Target repository name
-GITHUB_BASE_BRANCH=main                # Branch PRs will target
-```
-
-```bash
-VCS_KIND=gitlab
-
-# GitLab (active when VCS_KIND=gitlab)
-GITLAB_TOKEN=glpat-xxxxxxxxxxxx        # PAT with api, read_repository, write_repository scopes
-GITLAB_PROJECT_ID=group/repo           # Project ID or full path
-GITLAB_BASE_BRANCH=main                # Branch PRs will target
-GITLAB_HOST=https://gitlab.com         # Override for self-hosted
-```
-
-**Slack** — Bot notifications and slash commands. Bot scopes: `chat:write`, `commands`, `files:read`, `users:read`.
-```bash
-CHAT_SDK_SLACK_TOKEN=xoxb-xxxxxxxxxxxx  # Slack bot token
-CHAT_SDK_CHANNEL_ID=C0123456789         # Channel ID for notifications
-CHAT_SDK_BOT_NAME=blazebot             # Display name for the bot
-SLACK_SIGNING_SECRET=xxxxxxxxxxxxxxxx   # Required — verifies /ai-workflow slash commands
-SLACK_ALLOWED_USER_IDS=U0123,U4567      # Optional: comma-separated allowlist
-```
-
-Operators can drive workflows directly from Slack with `/ai-workflow list | status <KEY> | cancel <KEY>` once `SLACK_SIGNING_SECRET` is set and the slash command is registered (Request URL: `https://<your-domain>/webhooks/slack`). See `.claude/skills/init-slack/references/slash-commands.md` for the full setup walkthrough.
-
-**Agent** — AI model configuration:
-```bash
-ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx  # Anthropic API key
-CLAUDE_MODEL=claude-opus-4-6           # Model to use (default: claude-opus-4-6)
-# COMMIT_AUTHOR=                       # Optional override (set with COMMIT_EMAIL).
-# COMMIT_EMAIL=                        # On GitHub, leave unset to author commits as the App's bot.
-```
-
-**GitHub App bot identity** — when `VCS_KIND=github` and both `COMMIT_AUTHOR` / `COMMIT_EMAIL` are unset, the workflow derives the identity from the configured GitHub App (`<app-slug>[bot]` + the `<id>+<slug>[bot]@users.noreply.github.com` noreply address). GitHub then renders commits with the App's avatar and the `[bot]` badge in the UI.
-
-**Switching agents** — ai workflow supports two CLI runtimes. Set `AGENT_KIND` once per deployment:
-
-```bash
-AGENT_KIND=claude    # default — Anthropic Claude Code
-# or
-AGENT_KIND=codex     # OpenAI Codex CLI
-```
-
-When `AGENT_KIND=codex`:
-
-```bash
-CODEX_API_KEY=sk-codex-xxxxxxxxxxxx   # or CODEX_CHATGPT_OAUTH_TOKEN
-CODEX_MODEL=gpt-5-codex                # default
-```
-
-Pricing is fetched from [LiteLLM's community-maintained JSON](https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json) on each cold start (1h TTL by default). Override `CODEX_PRICING_URL` in air-gapped environments. When pricing is unavailable, Slack reports show tokens-only with `cost unknown`.
-
-**Sandbox** — Concurrency and timeout limits:
-```bash
-MAX_CONCURRENT_AGENTS=3   # Max parallel sandboxes (default: 3)
-JOB_TIMEOUT_MS=1800000    # Agent timeout in ms (default: 30 minutes)
-```
-
-**Run Registry** — Upstash Redis for tracking active runs:
-```bash
-AI_WORKFLOW_KV_REST_API_URL=https://your-redis.upstash.io
-AI_WORKFLOW_KV_REST_API_TOKEN=your-upstash-token
-```
-
-**Security** — Cron endpoint authorization:
-```bash
-CRON_SECRET=your-secret   # Vercel Cron uses this to authenticate requests
-```
-
-### 4. Set up local Postgres (for workflow state in dev)
-
-Vercel Workflows needs a Postgres database locally. Create one and set the connection string:
-
-```bash
-WORKFLOW_POSTGRES_URL=postgresql://localhost:5432/ai_workflow
-```
-
-### 5. Pull Vercel environment (optional)
-
-If your Vercel project already has environment variables configured:
-
-```bash
-vercel env pull .env.local
-```
-
-This provisions OIDC tokens for Sandbox authentication automatically — no need to set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, or `VERCEL_PROJECT_ID` manually.
-
-### 6. Run locally
-
-```bash
-pnpm dev
-```
-
-### 7. Verify it works
-
-Check the health endpoint:
-
-```bash
-curl http://localhost:3000/health
-# → {"status":"ok","timestamp":"2026-03-30T12:00:00.000Z"}
-```
-
-Trigger a poll manually (requires `CRON_SECRET`):
-
-```bash
-curl -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/cron/poll
-```
-
-## Environment Variables Reference
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| **Jira** | | | |
-| `ISSUE_TRACKER_KIND` | No | `jira` | Issue tracker type (only `jira` supported today) |
-| `JIRA_BASE_URL` | Yes | — | Atlassian instance URL |
-| `JIRA_EMAIL` | Yes | — | Jira account email |
-| `JIRA_API_TOKEN` | Yes | — | Jira API token |
-| `JIRA_PROJECT_KEY` | Yes | — | Jira project key |
-| `JIRA_WEBHOOK_SECRET` | No | — | HMAC secret for `/webhooks/jira`. Without it, dispatch is cron-bound. |
-| `COLUMN_AI` | Yes | — | Board column for AI-assigned tickets |
-| `COLUMN_AI_REVIEW` | Yes | — | Board column for completed tickets |
-| `COLUMN_BACKLOG` | Yes | — | Board column for tickets needing clarification |
-| **VCS** | | | |
-| `VCS_KIND` | Yes | — | `github` or `gitlab` |
-| `GITHUB_TOKEN` | Yes† | — | GitHub PAT with `repo` scope (when `VCS_KIND=github`) |
-| `GITHUB_OWNER` | Yes† | — | GitHub org or username (when `VCS_KIND=github`) |
-| `GITHUB_REPO` | Yes† | — | Target repository (when `VCS_KIND=github`) |
-| `GITHUB_BASE_BRANCH` | No | `main` | Base branch for PRs |
-| `GITLAB_TOKEN` | Yes† | — | GitLab PAT with `api`, `read_repository`, `write_repository` (when `VCS_KIND=gitlab`) |
-| `GITLAB_PROJECT_ID` | Yes† | — | Project ID or `group/repo` path (when `VCS_KIND=gitlab`) |
-| `GITLAB_BASE_BRANCH` | No | `main` | Base branch for MRs |
-| `GITLAB_HOST` | No | `https://gitlab.com` | Override for self-hosted GitLab |
-| **Slack** | | | |
-| `CHAT_SDK_SLACK_TOKEN` | Yes | — | Slack bot token |
-| `CHAT_SDK_CHANNEL_ID` | Yes | — | Notification channel ID |
-| `CHAT_SDK_BOT_NAME` | No | `blazebot` | Bot display name |
-| `SLACK_SIGNING_SECRET` | Yes | — | Slack app signing secret; verifies `/ai-workflow` slash commands |
-| `SLACK_ALLOWED_USER_IDS` | No | — | Comma-separated Slack user IDs allowed to run `/ai-workflow`; empty = anyone |
-| **Agent** | | | |
-| `AGENT_KIND` | No | `claude` | Runtime: `claude` or `codex` |
-| `ANTHROPIC_API_KEY` | Yes‡ | — | Anthropic API key (required when `AGENT_KIND=claude`) |
-| `CLAUDE_MODEL` | No | `claude-opus-4-6` | Claude model ID |
-| `CODEX_API_KEY` | Yes‡ | — | OpenAI Codex API key (required when `AGENT_KIND=codex`) |
-| `CODEX_CHATGPT_OAUTH_TOKEN` | No | — | Alternative to `CODEX_API_KEY` |
-| `CODEX_MODEL` | No | `gpt-5-codex` | Codex model ID |
-| `CODEX_PRICING_URL` | No | LiteLLM JSON | Pricing source for Codex cost reporting |
-| `CODEX_PRICING_TTL_MS` | No | `3600000` | Pricing cache TTL (ms) |
-| `COMMIT_AUTHOR` | No | _GitHub: App bot / GitLab: `ai-workflow-blazity`_ | Git author name (override; pair with `COMMIT_EMAIL`) |
-| `COMMIT_EMAIL` | No | _GitHub: App bot / GitLab: `ai-workflow@blazity.com`_ | Git author email (override; pair with `COMMIT_AUTHOR`) |
-| **Sandbox** | | | |
-| `MAX_CONCURRENT_AGENTS` | No | `3` | Max parallel sandboxes |
-| `JOB_TIMEOUT_MS` | No | `1800000` | Agent timeout (ms) |
-| **Attachments** | | | |
-| `ATTACHMENT_MAX_FILE_SIZE_MB` | No | `25` | Per-file size limit |
-| `ATTACHMENT_MAX_TOTAL_SIZE_MB` | No | `100` | Combined attachment size limit |
-| `ATTACHMENT_MAX_COUNT` | No | `20` | Max attachments per ticket |
-| `ATTACHMENT_DOWNLOAD_TIMEOUT_MS` | No | `30000` | Download timeout per attachment |
-| **Polling** | | | |
-| `POLL_INTERVAL_MS` | No | `300000` | Internal poll cadence (ms) — separate from the 1-min Vercel cron |
-| **Vercel** | | | |
-| `VERCEL_TOKEN` | No* | — | Vercel API token (local dev only) |
-| `VERCEL_TEAM_ID` | No* | — | Vercel team ID (local dev only) |
-| `VERCEL_PROJECT_ID` | No* | — | Vercel project ID (local dev only) |
-| `WORKFLOW_POSTGRES_URL` | No* | — | Local Postgres for Vercel Workflow durable state (dev only) |
-| **Arthur (optional)** | | | |
-| `GENAI_ENGINE_API_KEY` | No | — | Arthur AI Engine API key |
-| `GENAI_ENGINE_TRACE_ENDPOINT` | No | — | Arthur trace endpoint URL |
-| `GENAI_ENGINE_PROMPT_TASK_ID` | No | — | Hosted prompt task ID (set after `pnpm setup:arthur-prompts`) |
-| **Redis** | | | |
-| `AI_WORKFLOW_KV_REST_API_URL` | Yes | — | Upstash Redis REST URL (auto-injected by Marketplace integration) |
-| `AI_WORKFLOW_KV_REST_API_TOKEN` | Yes | — | Upstash Redis REST token (auto-injected) |
-| **Security** | | | |
-| `CRON_SECRET` | No | — | Cron endpoint auth token (Vercel sets this automatically when defined) |
-
-† Required only for the matching `VCS_KIND`. `env.ts` cross-validates at startup.
-‡ Required only for the matching `AGENT_KIND` (the OAuth token alternative also satisfies this).
-\* On Vercel, OIDC authenticates the sandbox automatically. These are only needed for local development if `vercel env pull` doesn't cover your setup.
-
-## Deploying to Vercel
-
-### 1. Push to GitHub
-
-ai workflow deploys automatically when connected to Vercel via Git integration.
-
-### 2. Import project
-
-In the [Vercel Dashboard](https://vercel.com/new), import your repository. Vercel auto-detects Nitropack and configures the build.
-
-### 3. Set environment variables
-
-Add all required environment variables in your Vercel project settings under **Settings → Environment Variables**. You can also use the CLI:
-
-```bash
-vercel env add JIRA_BASE_URL
-vercel env add JIRA_API_TOKEN
-# ... repeat for each variable
-```
-
-### 4. Cron job
-
-The cron schedule is configured in `vercel.json` and activates automatically on deploy:
-
-```json
-{
-  "crons": [
-    {
-      "path": "/cron/poll",
-      "schedule": "* * * * *"
-    }
-  ]
-}
-```
-
-This hits `/cron/poll` every minute. Vercel injects the `CRON_SECRET` header automatically.
-
-### 5. CI/CD
-
-Two GitHub Actions workflows are included:
+## Setup
 
-- **CI** (`ci.yml`) — Runs on pull requests targeting `main`/`dev` and on `merge_group` events. Runs typecheck and unit tests; gates the merge queue on `e2e-orchestration → e2e-capacity → e2e-agent`.
-- **E2E** (`e2e.yml`) — Manual `workflow_dispatch` with tier selection (`orchestration`, `capacity`, `agent`, `all`) and an `agent` choice (`claude` | `codex`):
-  - **orchestration** — dispatch / cron / webhook flows (60 min timeout)
-  - **capacity** — concurrency, claim/release, reconciler (30 min timeout, runs after orchestration)
-  - **agent** — full ticket → PR run against real Jira + GitHub (120 min timeout, runs after capacity)
+For installation, environment variables, and deployment instructions, see [SETUP.md](./SETUP.md).
 
 ## Workflow Deep-dive
 
@@ -389,7 +100,7 @@ There is a single durable workflow — `agentWorkflow` in [`src/workflows/agent.
 
 If either phase returns `clarification_needed`, the workflow posts numbered questions as a Jira comment, moves the ticket to Backlog, and emits a `needs_clarification` Slack event. If a phase fails or times out, the ticket is moved to Backlog with a `failed` event.
 
-> A third "Review" phase exists as commented-out scaffolding in `agent.ts`. It's intentionally disabled today.
+> A third "Review" phase is implemented in `agent.ts` but gated behind `ENABLE_REVIEW_PHASE` (default `false`). When enabled, it runs after Phase 2 — the agent self-reviews its diff and fixes issues before push (15 min poll cap, `REVIEW_SCHEMA` for structured output).
 
 ### Sandbox Lifecycle
 
diff --git a/SETUP.md b/SETUP.md
