task-while 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhang Yu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+# task-while
+
+`task-while` is a git-first task orchestrator built around a task source protocol. The published package name and CLI binary are both `task-while`.
+
+It reads workflow settings from `while.yaml`, opens the configured task source, executes one task at a time, reviews the result, integrates approved work, and creates one git commit per completed task. The built-in task sources are `spec-kit`, which consumes `spec.md`, `plan.md`, and `tasks.md` under `specs/<feature>/`, and `openspec`, which consumes an OpenSpec change under `openspec/changes/<change>/`.
+
+It also provides a standalone `batch` command for YAML-driven file processing that is independent from the feature/task orchestration workflow.
+
+## Requirements
+
+- Node.js 18 or newer
+- For `run`: a git repository with an initial commit
+- For `run`: a workspace with the directory layout required by the selected task source
+- For `run`: the files required by the selected task source
+- For `run`: a clean worktree before `run`
+
+Current built-in source requirements:
+
+- `task.source: spec-kit`
+- `specs/<feature>/spec.md`
+- `specs/<feature>/plan.md`
+- `specs/<feature>/tasks.md`
+- `task.source: openspec`
+- `openspec/changes/<change>/proposal.md`
+- `openspec/changes/<change>/design.md`
+- `openspec/changes/<change>/tasks.md`
+- At least one file under `openspec/changes/<change>/specs/**/*.md`
+
+## Install
+
+```bash
+pnpm add -D task-while
+```
+
+Run it with:
+
+```bash
+pnpm exec task-while run
+```
+
+## Configuration
+
+`while.yaml` configures the `run` workflow only. When it is absent, the CLI runs `task.source: spec-kit`, `task.maxIterations: 5`, and `workflow.mode: direct` with `codex` for both roles. Each workflow role accepts provider-specific `model` and `effort`.
+
+```yaml
+task:
+  source: spec-kit
+  maxIterations: 5
+
+workflow:
+  mode: direct
+  roles:
+    implementer:
+      model: gpt-5-codex
+      effort: high
+    reviewer:
+      model: gpt-5-codex
+      effort: high
+```
+
+Current status:
+
+- `workflow.roles.<role>.provider` accepts `codex` or `claude`; when omitted it defaults to `codex`, including roles that only set `model` and/or `effort`
+- `codex` `effort` accepts `minimal`, `low`, `medium`, `high`, or `xhigh`
+- `claude` `effort` accepts `low`, `medium`, `high`, or `max`
+- `workflow.mode: direct` requires `implementer` and `reviewer` to use identical `model` and `effort` when they share the same provider
+- `workflow.mode: direct` uses a local reviewer
+- `workflow.mode: pull-request` pushes a task branch, polls GitHub PR review from `chatgpt-codex-connector[bot]`, then squash-merges on approval
+- in `workflow.mode: pull-request`, reviewer `provider` still selects the remote reviewer, but any local reviewer `model` and `effort` values are ignored
+- `workflow.mode: pull-request` currently supports only `codex` as the remote reviewer provider
+- `task.maxIterations` applies globally to every task in the selected source session
+
+Example pull-request mode:
+
+```yaml
+workflow:
+  mode: pull-request
+  roles:
+    implementer:
+      provider: claude
+      model: claude-sonnet-4-6
+      effort: max
+    reviewer:
+      provider: codex
+```
+
+## Workspace Resolution
+
+`task-while run` resolves the current working directory as the workspace root.
+
+- `task.source: spec-kit` requires `cwd/specs`
+- `task.source: openspec` requires `cwd/openspec/changes`
+- if the required source root is missing, the CLI fails with a clear user-facing error
+
+Feature resolution order:
+
+1. `--feature`
+2. current git branch prefix for `spec-kit`
+3. the only entry under the selected source root
+
+For `task.source: openspec`, `--feature` identifies the OpenSpec change id.
+
+## Commands
+
+### `task-while run`
+
+Runs the current feature workflow from the existing `.while` state or initializes a new one. Run it from the workspace root so the current directory contains the source-specific root, such as `specs/` for `spec-kit` or `openspec/changes/` for `openspec`.
+
+```bash
+cd /path/to/workspace
+pnpm exec task-while run --feature 001-demo
+```
+
+Useful flags:
+
+- `--feature <featureId>`: select the feature explicitly
+- For `task.source: openspec`, `--feature <featureId>` selects the OpenSpec change id
+- `--until-task <taskSelector>`: stop after the target task reaches `done`
+- `--verbose`: stream agent events to `stderr`
+
+### `task-while batch`
+
+Runs a standalone YAML-driven batch job. This command does not read `while.yaml`, does not require `specs/`, and does not use the task-source workflow.
+
+```bash
+cd /path/to/workspace
+pnpm exec task-while batch --config ./batch.yaml
+```
+
+Batch config example:
+
+```yaml
+provider: claude
+model: claude-sonnet-4-6
+effort: max
+glob:
+  - 'src/**/*.{ts,tsx}'
+prompt: |
+  Read the target file and return structured output for it.
+schema:
+  type: object
+  properties:
+    summary:
+      type: string
+    tags:
+      type: array
+      items:
+        type: string
+  required:
+    - summary
+```
+
+Batch behavior:
+
+- `glob` is optional and defaults to `**/*`
+- `glob` is resolved relative to the directory that contains `batch.yaml`
+- `provider`, `prompt`, and `schema` are required
+- `model` and `effort` are optional and are forwarded to the selected provider client
+- batch `provider` accepts `codex` or `claude`
+- batch `codex` `effort` accepts `minimal`, `low`, `medium`, `high`, or `xhigh`
+- batch `claude` `effort` accepts `low`, `medium`, `high`, or `max`
+- each run scans files under the `batch.yaml` directory and filters them by `glob`
+- execution state is written beside the YAML file in `state.json`
+- structured results are written beside the YAML file in `results.json`
+- result keys are relative to the directory that contains `batch.yaml`
+- `--verbose` prints per-file failure reasons to `stderr`
+- rerunning the command resumes unfinished work and skips files that already have accepted results
+- when the current `pending` queue is exhausted and `failed` is non-empty, the command persists a recycle transition that moves `failed` back into `pending` for the next round
+- the command exits only when both `pending` and `failed` are empty
+- there is no retry limit for file-level failures; failed files continue to be retried round by round
+- when `glob` matches no files, the command exits successfully without initializing a provider
+
+## Task Lifecycle
+
+Each task follows this lifecycle:
+
+1. The implement role receives a task-source-built prompt for the current task.
+2. The reviewer evaluates the task-source-built review prompt plus changed-file context and overall risk.
+3. If review is approved, `task-while` asks the task source to apply its completion marker, creates the final integration commit, and records integrate artifacts under `.while`.
+
+Completion requires all of the following:
+
+- review verdict `pass`
+- no findings
+- every acceptance check passing
+
+Review context uses `actualChangedFiles` derived from git diff against `HEAD`. In `pull-request` mode, changed-file context comes from the live PR snapshot instead of the local worktree diff.
+
+In `pull-request` mode:
+
+- review creates or reuses `task/<slug>` and an open PR against `main`
+- if an open PR exists but the local task branch is missing, review restores the branch from `origin/task/<slug>`
+- review creates a checkpoint commit with `checkpoint: Task <taskId>: <title> (attempt <n>)`
+- review polls every minute with no default timeout
+- review evaluates approval from a fully paginated live GraphQL PR snapshot
+- approval is driven by the freshest `chatgpt-codex-connector[bot]` signal after the checkpoint commit
+- active feedback includes unresolved, non-outdated review threads plus reviewer-authored review summaries and discussion comments after the current checkpoint
+- process restart re-enters `review` or `integrate` and continues the same PR flow
+- if the PR was already squash-merged before state was persisted, integrate treats it as already completed and finalizes local cleanup on resume
+- integrate checks the task source completion marker, creates the final task commit when needed, squash-merges, returns to `main`, and deletes the local task branch
+
+Completion is git-first:
+
+- one completed task = one git commit
+- `.while` is runtime state and is not committed
+- completed task state stores `commitSha`
+
+## Built-in `spec-kit` Expectations
+
+The built-in `spec-kit` task source parses raw Spec Kit task lines in file order. It does not require enhanced per-task metadata blocks.
+
+Example:
+
+```md
+## Phase 1: Core
+
+- [ ] T001 Implement greeting
+- [ ] T002 [P] Implement farewell
+- [ ] T010 [P] [US1] Add scenario coverage
+```
+
+Current built-in `spec-kit` behavior:
+
+- task ordering follows the order in `tasks.md`
+- explicit task dependencies are not extracted from raw task lines
+- implement/review prompts include the current task line, the current phase, `spec.md`, `plan.md`, and the full `tasks.md`
+- completion is still written back through `tasks.md` checkboxes
+
+## Built-in `openspec` Expectations
+
+The built-in `openspec` task source consumes an existing OpenSpec change directory and aligns implement/review prompts with `openspec instructions apply --json`.
+
+Example configuration:
+
+```yaml
+task:
+  source: openspec
+  maxIterations: 5
+```
+
+Example run:
+
+```bash
+pnpm exec task-while run --feature example-change
+```
+
+Current built-in `openspec` behavior:
+
+- `--feature` maps to `openspec/changes/<change>`
+- stable task handles come from explicit numbering in `tasks.md`, such as `1.1` and `2.3`
+- implement/review prompts include the current task, task group, `proposal.md`, `design.md`, expanded `specs/**/*.md`, full `tasks.md`, and the OpenSpec apply instruction/state/progress
+- completion is still written by `task-while` after review/integrate success; it does not adopt `/opsx:apply`'s immediate checkbox update behavior
+- `task-while` consumes OpenSpec artifacts and CLI JSON, but it does not run `/opsx:propose`
+
+Task retry budget is configured globally in `while.yaml`:
+
+```yaml
+task:
+  maxIterations: 2
+```
+
+## What `task-while` Does Not Do
+
+`task-while` does not replace Spec Kit's project-level workflow. It does not run Spec Kit commands, checklists, hooks, or preset-installed skills.
+
+Its contract with the selected task source is simple:
+
+- the task source parses source artifacts and provides prompts plus completion operations
+- `task-while` orchestrates implement, review, integrate, and persistence around that protocol
+
+The standalone `batch` command is separate from this contract. It does not use task sources, task graphs, review/integrate stages, or git-first completion.
+
+## Runtime Layout
+
+`run` keeps runtime state under:
+
+```text
+<source-entry>/<id>/.while/
+```
+
+Important files:
+
+- `state.json`
+- `graph.json`
+- `report.json`
+- `events.jsonl`
+- `tasks/<taskHandle>/g<generation>/a<attempt>/implement.json`
+- `tasks/<taskHandle>/g<generation>/a<attempt>/review.json`
+- `tasks/<taskHandle>/g<generation>/a<attempt>/integrate.json`
+
+`.while` is runtime state, not the long-term source of truth. Pull-request review recovery reloads persisted `implement` artifacts by `taskHandle`, `generation`, and `attempt`.
+
+`batch` keeps runtime files beside the YAML config:
+
+```text
+<config-dir>/
+├── batch.yaml
+├── state.json
+└── results.json
+```
+
+`state.json` contains:
+
+- `pending`
+- `inProgress`
+- `failed`
+
+`failed` is the current round's failure buffer. When `pending` becomes empty, those paths are persisted back into `pending` and retried in the next round. Historical state entries whose files no longer exist are dropped when a new run starts.
+
+`results.json` maps accepted structured output by file path relative to the `batch.yaml` directory. If the config lives under a subdirectory and uses patterns such as `../input/*.txt`, the keys keep that relative form.
+
+## Publishing
+
+Before publishing:
+
+```bash
+pnpm lint
+pnpm typecheck
+AI_AGENT=1 pnpm test
+AI_AGENT=1 pnpm tsx fixtures/smoke/codex-e2e.ts
+npm pack --dry-run
+```

package/bin/task-while.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const entry = path.join(__dirname, '..', 'src', 'index.ts')
+const tsxLoader = require.resolve('tsx')
+const result = spawnSync(
+  process.execPath,
+  ['--import', tsxLoader, entry, ...process.argv.slice(2)],
+  {
+    stdio: 'inherit',
+  },
+)
+
+if (typeof result.status === 'number') {
+  process.exit(result.status)
+}
+process.exit(1)

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "task-while",
+  "version": "0.0.1",
+  "packageManager": "pnpm@10.32.1",
+  "description": "Git-first task orchestrator for task-source workspaces",
+  "author": "Zhang Yu",
+  "license": "MIT",
+  "homepage": "https://github.com/zhangyu1818/task-while#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhangyu1818/task-while.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zhangyu1818/task-while/issues"
+  },
+  "keywords": [
+    "spec-kit",
+    "spec-driven",
+    "task-orchestrator",
+    "cli",
+    "git"
+  ],
+  "bin": {
+    "task-while": "bin/task-while.mjs"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "smoke:codex": "tsx fixtures/smoke/codex-provider.ts",
+    "smoke:e2e:codex": "tsx fixtures/smoke/codex-e2e.ts",
+    "smoke:github-pr-snapshot": "tsx fixtures/smoke/github-pr-snapshot.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.92",
+    "@openai/codex-sdk": "^0.116.0",
+    "ajv": "^8.18.0",
+    "arg": "^5.0.2",
+    "execa": "^8.0.1",
+    "fs-extra": "^11.3.4",
+    "glob": "13.0.6",
+    "tsx": "^4.21.0",
+    "yaml": "^2.8.3",
+    "zod": "3.25.76",
+    "zod-to-json-schema": "^3.25.1"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "4.1.0",
+    "@zhangyu1818/eslint-config": "^5.0.0",
+    "eslint": "^10.1.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.0"
+  }
+}

package/src/agents/claude.ts

@@ -0,0 +1,175 @@
+import { buildImplementerPrompt } from '../prompts/implementer'
+import { buildReviewerPrompt } from '../prompts/reviewer'
+import {
+  implementOutputSchema,
+  reviewOutputSchema,
+  validateImplementOutput,
+  validateReviewOutput,
+} from '../schema/index'
+
+import type { Options as ClaudeQueryOptions } from '@anthropic-ai/claude-agent-sdk'
+
+import type { ClaudeProviderOptions } from './provider-options'
+import type {
+  ImplementAgentInput,
+  ImplementerProvider,
+  ReviewAgentInput,
+  ReviewerProvider,
+} from './types'
+
+export interface ClaudeTextEvent {
+  delta: string
+  type: 'text'
+}
+
+export interface ClaudeAssistantEvent {
+  type: 'assistant'
+}
+
+export interface ClaudeResultEvent {
+  type: 'result'
+}
+
+export interface ClaudeErrorEvent {
+  message: string
+  type: 'error'
+}
+
+export type ClaudeAgentEvent =
+  | ClaudeAssistantEvent
+  | ClaudeErrorEvent
+  | ClaudeResultEvent
+  | ClaudeTextEvent
+
+export type ClaudeAgentEventHandler = (event: ClaudeAgentEvent) => void
+
+interface QueryResultMessage {
+  errors?: string[]
+  structured_output?: unknown
+  subtype: string
+  type: 'result'
+}
+
+interface QueryStreamEventMessage {
+  event: {
+    delta?: { text?: string; type?: string }
+    type: string
+  }
+  type: 'stream_event'
+}
+
+interface QueryAssistantMessage {
+  type: 'assistant'
+}
+
+type QueryMessage =
+  | QueryAssistantMessage
+  | QueryResultMessage
+  | QueryStreamEventMessage
+
+export interface ClaudeAgentClientOptions extends ClaudeProviderOptions {
+  onEvent?: ClaudeAgentEventHandler
+  workspaceRoot: string
+}
+
+export interface ClaudeStructuredInput {
+  outputSchema: Record<string, unknown>
+  prompt: string
+}
+
+export class ClaudeAgentClient
+  implements ImplementerProvider, ReviewerProvider
+{
+  public readonly name = 'claude'
+
+  public constructor(private readonly options: ClaudeAgentClientOptions) {}
+
+  private async collectStructuredOutput(
+    messages: AsyncIterable<QueryMessage>,
+  ): Promise<unknown> {
+    let structuredOutput: unknown = null
+
+    for await (const message of messages) {
+      if (message.type === 'stream_event' && this.options.onEvent) {
+        const event = message.event
+        if (
+          event.type === 'content_block_delta' &&
+          event.delta?.type === 'text_delta' &&
+          event.delta.text
+        ) {
+          this.options.onEvent({ delta: event.delta.text, type: 'text' })
+        }
+      }
+
+      if (message.type === 'assistant' && this.options.onEvent) {
+        this.options.onEvent({ type: 'assistant' })
+      }
+
+      if (message.type === 'result') {
+        if (message.subtype !== 'success') {
+          const detail = message.errors?.join('; ') ?? message.subtype
+          throw new Error(`Claude agent query failed: ${detail}`)
+        }
+        structuredOutput = message.structured_output ?? null
+        if (this.options.onEvent) {
+          this.options.onEvent({ type: 'result' })
+        }
+      }
+    }
+
+    if (structuredOutput === null || structuredOutput === undefined) {
+      throw new Error('Claude agent returned no structured output')
+    }
+
+    return structuredOutput
+  }
+
+  public async implement(input: ImplementAgentInput) {
+    const prompt = await buildImplementerPrompt(input)
+    const output = await this.invokeStructured<unknown>({
+      outputSchema: implementOutputSchema,
+      prompt,
+    })
+    return validateImplementOutput(output)
+  }
+
+  public async invokeStructured<T>(input: ClaudeStructuredInput): Promise<T> {
+    const { query } = await import('@anthropic-ai/claude-agent-sdk')
+    const queryOptions = {
+      allowDangerouslySkipPermissions: true,
+      cwd: this.options.workspaceRoot,
+      includePartialMessages: !!this.options.onEvent,
+      permissionMode: 'bypassPermissions',
+      outputFormat: {
+        schema: input.outputSchema,
+        type: 'json_schema',
+      },
+      ...(this.options.model ? { model: this.options.model } : {}),
+      ...(this.options.effort ? { effort: this.options.effort } : {}),
+    } satisfies ClaudeQueryOptions
+
+    const messages = query({
+      options: queryOptions,
+      prompt: input.prompt,
+    })
+
+    return this.collectStructuredOutput(
+      messages as AsyncIterable<QueryMessage>,
+    ) as Promise<T>
+  }
+
+  public async review(input: ReviewAgentInput) {
+    const prompt = await buildReviewerPrompt(input)
+    const output = await this.invokeStructured<unknown>({
+      outputSchema: reviewOutputSchema,
+      prompt,
+    })
+    return validateReviewOutput(output)
+  }
+}
+
+export function createClaudeProvider(
+  options: ClaudeAgentClientOptions,
+): ImplementerProvider & ReviewerProvider {
+  return new ClaudeAgentClient(options)
+}