@pleaseai/work 0.1.6 → 0.1.8

package/README.md

@@ -1,5 +1,7 @@
 # Work Please
 
+English | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
+
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=pleaseai_work-please&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=pleaseai_work-please) [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=pleaseai_work-please&metric=bugs)](https://sonarcloud.io/summary/new_code?id=pleaseai_work-please) [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=pleaseai_work-please&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=pleaseai_work-please) [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=pleaseai_work-please&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=pleaseai_work-please)
 [![codecov](https://codecov.io/gh/pleaseai/work-please/graph/badge.svg?token=do858Z1lsI)](https://codecov.io/gh/pleaseai/work-please)
 
@@ -36,13 +38,13 @@ instead of supervising coding agents.
 
 Work Please is a long-running TypeScript service that:
 
-1. Polls an issue tracker (Asana or GitHub Projects v2) for tasks in configured active states.
+1. Polls an issue tracker (GitHub Projects v2 or Asana) for tasks in configured active states.
 2. Creates an isolated workspace directory for each eligible issue.
 3. Launches a Claude Code agent session inside that workspace with a rendered prompt.
 4. Monitors the session, handles retries, and reconciles issue state on each poll cycle.
 
 It is a TypeScript implementation of the [Symphony specification](vendor/symphony/SPEC.md),
-adapted for Asana / GitHub Projects v2 and Claude Code instead of Linear and Codex.
+adapted for GitHub Projects v2 / Asana and Claude Code instead of Linear and Codex.
 
 For full technical details, see [SPEC.md](SPEC.md).
 
@@ -50,18 +52,18 @@ For full technical details, see [SPEC.md](SPEC.md).
 
 | | Symphony (reference) | Work Please |
 |---|---|---|
-| Issue Tracker | Linear | Asana & GitHub Projects v2 |
+| Issue Tracker | Linear | GitHub Projects v2 & Asana (under development) |
 | Coding Agent | Codex (app-server mode) | Claude Code CLI |
 | Language | Elixir/OTP | TypeScript + Bun |
-| Tracker Auth | `LINEAR_API_KEY` | `ASANA_ACCESS_TOKEN`, `GITHUB_TOKEN`, or GitHub App credentials |
-| Project Config | `project_slug` | `project_gid` (Asana) or `owner` + `project_number` (GitHub Projects v2) |
-| Issue States | Linear workflow states | Asana sections / GitHub Projects v2 Status field |
+| Tracker Auth | `LINEAR_API_KEY` | `GITHUB_TOKEN`, GitHub App credentials, or `ASANA_ACCESS_TOKEN` |
+| Project Config | `project_slug` | `owner` + `project_number` (GitHub Projects v2) or `project_gid` (Asana) |
+| Issue States | Linear workflow states | GitHub Projects v2 Status field / Asana sections |
 | Agent Protocol | JSON-RPC over stdio | `@anthropic-ai/claude-agent-sdk` |
 | Permission Model | Codex approval/sandbox policies | Claude Code `--permission-mode` |
 
 ## Features
 
-- **Multi-tracker support** — Dispatch work from Asana tasks or GitHub Projects v2 items on a
+- **Multi-tracker support** — Dispatch work from GitHub Projects v2 items or Asana tasks (under development) on a
   fixed cadence.
 - **GitHub App authentication** — Authenticate the GitHub tracker with a GitHub App installation
   token (`app_id` + `private_key` + `installation_id`) instead of a PAT, for fine-grained
@@ -90,8 +92,8 @@ Config Layer ──> Orchestrator ──> Workspace Manager ──> Agent Runner
                      |                                         |
                      v                                         v
            Issue Tracker Client                       Isolated workspace/
-          (Asana REST API or                          per-issue directory
-          GitHub GraphQL API,
+          (GitHub GraphQL API or                      per-issue directory
+          Asana REST API,
           polling + reconciliation)
                      |
                      v
@@ -103,7 +105,7 @@ Components:
 - **Workflow Loader** — Parses `WORKFLOW.md` YAML front matter and prompt template body.
 - **Config Layer** — Typed getters with env-var indirection and built-in defaults.
 - **Issue Tracker Client** — Fetches candidate issues, reconciles running-issue states. Supports
-  Asana (REST API) and GitHub Projects v2 (GraphQL API) adapters.
+  GitHub Projects v2 (GraphQL API) and Asana (REST API) adapters.
 - **Orchestrator** — Owns in-memory state; drives the poll/dispatch/retry loop.
 - **Workspace Manager** — Creates, reuses, and cleans per-issue workspaces; runs hooks.
 - **Agent Runner** — Launches Claude Code, streams events back to the orchestrator.
@@ -117,14 +119,14 @@ See [SPEC.md](SPEC.md) for the full specification.
 
 - **Bun** (see [bun.sh](https://bun.sh) for installation)
 - **Claude Code CLI** (see the [official installation guide](https://docs.anthropic.com/en/docs/claude-code))
-- **Asana access token** (`ASANA_ACCESS_TOKEN`) **or** **GitHub token** (`GITHUB_TOKEN`) with
-  access to the target project, **or** **GitHub App credentials** (`GITHUB_APP_ID`,
-  `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_INSTALLATION_ID`) — see [GitHub App Authentication](#github-app-authentication)
+- **GitHub token** (`GITHUB_TOKEN`) with access to the target project, **or** **GitHub App credentials**
+  (`GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_INSTALLATION_ID`) — see [GitHub App Authentication](#github-app-authentication),
+  **or** **Asana access token** (`ASANA_ACCESS_TOKEN`) (under development)
 
 ### Install
 
 ```bash
-git clone https://github.com/chatbot-pf/work-please.git
+git clone https://github.com/pleaseai/work-please.git
 cd work-please
 bun install
 bun run build
@@ -133,20 +135,36 @@ bun run build
 ### Configure
 
 Create a `WORKFLOW.md` in your target repository. Two examples are shown below.
+See also the [example WORKFLOW.md](https://github.com/pleaseai/workflow/blob/main/WORKFLOW.md) for a real-world reference.
+
+#### GitHub Projects v2 (PAT)
 
-#### Asana
+See also the [example GitHub Project](https://github.com/orgs/pleaseai/projects/2) for a real-world reference.
 
 ```markdown
 ---
 tracker:
-  kind: asana
-  api_key: $ASANA_ACCESS_TOKEN
-  project_gid: "1234567890123456"
-  active_sections:
+  kind: github_projects
+  api_key: $GITHUB_TOKEN
+  owner: your-org
+  project_number: 42
+  active_statuses:
+    - Todo
     - In Progress
-  terminal_sections:
-    - Done
+    - Merging
+    - Rework
+  terminal_statuses:
+    - Closed
     - Cancelled
+    - Canceled
+    - Duplicate
+    - Done
+  watched_statuses:
+    - Human Review
+  auto_transitions:
+    human_review_to_rework: true
+    human_review_to_merging: true
+    include_bot_reviews: true
 
 polling:
   interval_ms: 30000
@@ -169,9 +187,9 @@ claude:
   turn_timeout_ms: 3600000
 ---
 
-You are working on an Asana task for the project.
+You are working on a GitHub issue for the repository `your-org/your-repo`.
 
-Task: {{ issue.title }}
+Issue {{ issue.identifier }}: {{ issue.title }}
 
 {{ issue.description }}
 
@@ -187,26 +205,42 @@ This is attempt #{{ attempt }}. Review any prior work in the workspace before co
 {% endif %}
 
 Your task:
-1. Understand the task requirements.
+1. Understand the issue requirements.
 2. Implement the requested changes.
 3. Write or update tests as needed.
-4. Open a pull request and move this task to the review section.
+4. Open a pull request and move this issue to `Human Review`.
 ```
 
-#### GitHub Projects v2 (PAT)
+#### GitHub Projects v2 (GitHub App)
+
+Use GitHub App credentials instead of a PAT for fine-grained permissions and higher API rate limits:
 
 ```markdown
 ---
 tracker:
   kind: github_projects
-  api_key: $GITHUB_TOKEN
+  app_id: $GITHUB_APP_ID
+  private_key: $GITHUB_APP_PRIVATE_KEY
+  installation_id: $GITHUB_APP_INSTALLATION_ID
   owner: your-org
   project_number: 42
   active_statuses:
+    - Todo
     - In Progress
+    - Merging
+    - Rework
   terminal_statuses:
-    - Done
+    - Closed
     - Cancelled
+    - Canceled
+    - Duplicate
+    - Done
+  watched_statuses:
+    - Human Review
+  auto_transitions:
+    human_review_to_rework: true
+    human_review_to_merging: true
+    include_bot_reviews: true
 
 polling:
   interval_ms: 30000
@@ -250,25 +284,22 @@ Your task:
 1. Understand the issue requirements.
 2. Implement the requested changes.
 3. Write or update tests as needed.
-4. Open a pull request and move this issue to the review status.
+4. Open a pull request and move this issue to `Human Review`.
 ```
 
-#### GitHub Projects v2 (GitHub App)
+#### Asana (under development)
 
-Use GitHub App credentials instead of a PAT for fine-grained permissions and higher API rate limits:
+> **Note**: Asana support is under development. The configuration below is a preview and may change.
 
 ```markdown
 ---
 tracker:
-  kind: github_projects
-  app_id: $GITHUB_APP_ID
-  private_key: $GITHUB_APP_PRIVATE_KEY
-  installation_id: $GITHUB_APP_INSTALLATION_ID
-  owner: your-org
-  project_number: 42
-  active_statuses:
+  kind: asana
+  api_key: $ASANA_ACCESS_TOKEN
+  project_gid: "1234567890123456"
+  active_sections:
     - In Progress
-  terminal_statuses:
+  terminal_sections:
     - Done
     - Cancelled
 
@@ -293,24 +324,41 @@ claude:
   turn_timeout_ms: 3600000
 ---
 
-You are working on a GitHub issue for the repository `your-org/your-repo`.
+You are working on an Asana task for the project.
 
-Issue {{ issue.identifier }}: {{ issue.title }}
+Task: {{ issue.title }}
 
 {{ issue.description }}
+
+{% if issue.blocked_by.size > 0 %}
+Blocked by:
+{% for blocker in issue.blocked_by %}
+- {{ blocker.identifier }} ({{ blocker.state }})
+{% endfor %}
+{% endif %}
+
+{% if attempt %}
+This is attempt #{{ attempt }}. Review any prior work in the workspace before continuing.
+{% endif %}
+
+Your task:
+1. Understand the task requirements.
+2. Implement the requested changes.
+3. Write or update tests as needed.
+4. Open a pull request and move this task to the review section (e.g. `Human Review`).
 ```
 
 ### Run
 
 ```bash
-# Set your tracker token
-export ASANA_ACCESS_TOKEN=your_token_here
-# or (GitHub PAT)
+# Set your tracker token (GitHub PAT)
 export GITHUB_TOKEN=ghp_your_token_here
 # or (GitHub App)
 export GITHUB_APP_ID=12345
 export GITHUB_APP_PRIVATE_KEY="$(cat path/to/private-key.pem)"
 export GITHUB_APP_INSTALLATION_ID=67890
+# or (Asana — under development)
+export ASANA_ACCESS_TOKEN=your_token_here
 
 # Run Work Please against a WORKFLOW.md in the current directory
 bunx work-please
@@ -332,34 +380,46 @@ front matter configuration block with a Markdown prompt template body.
 ```yaml
 ---
 tracker:
-  kind: asana                         # Required: "asana" or "github_projects"
+  kind: github_projects               # Required: "github_projects" or "asana"
 
-  # --- Asana fields (when kind == "asana") ---
-  api_key: $ASANA_ACCESS_TOKEN        # Required: token or $ENV_VAR
-  endpoint: https://app.asana.com/api/1.0  # Optional: override Asana API base URL
-  project_gid: "1234567890123456"     # Required: Asana project GID
-  active_sections:                    # Optional: default ["To Do", "In Progress"]
+  # --- GitHub Projects v2 fields (when kind == "github_projects") ---
+  api_key: $GITHUB_TOKEN              # Required: token or $ENV_VAR
+  endpoint: https://api.github.com   # Optional: override GitHub API base URL
+  owner: your-org                     # Required: GitHub organization or user login
+  project_number: 42                  # Required: GitHub Projects v2 project number
+  project_id: PVT_kwDOxxxxx          # Optional: project node ID (bypasses owner+project_number lookup)
+  active_statuses:                    # Optional: default ["Todo", "In Progress", "Merging", "Rework"]
+    - Todo
     - In Progress
-  terminal_sections:                  # Optional: default ["Done", "Cancelled"]
-    - Done
+    - Merging
+    - Rework
+  terminal_statuses:                  # Optional: default ["Closed", "Cancelled", "Canceled", "Duplicate", "Done"]
+    - Closed
     - Cancelled
-
-  # --- GitHub Projects v2 fields (when kind == "github_projects") ---
-  # api_key: $GITHUB_TOKEN            # Required: token or $ENV_VAR
-  # endpoint: https://api.github.com  # Optional: override GitHub API base URL
-  # owner: your-org                   # Required: GitHub organization or user login
-  # project_number: 42                # Required: GitHub Projects v2 project number
-  # project_id: PVT_kwDOxxxxx         # Optional: project node ID (bypasses owner+project_number lookup)
-  # active_statuses:                  # Optional: default ["Todo", "In Progress"]
-  #   - In Progress
-  # terminal_statuses:                # Optional: default ["Done", "Cancelled"]
-  #   - Done
-  #   - Cancelled
+    - Canceled
+    - Duplicate
+    - Done
+  watched_statuses:                   # Optional: states polled but not dispatched. Default ["Human Review"]
+    - Human Review
+  auto_transitions:                   # Optional: auto-transition rules for watched states
+    human_review_to_rework: true      # Move to Rework on CHANGES_REQUESTED or unresolved threads. Default true
+    human_review_to_merging: true     # Move to Merging on APPROVED + no unresolved threads. Default true
+    include_bot_reviews: true         # Whether bot comment threads count as unresolved. Default true
   # GitHub App authentication (alternative to api_key — all three required together):
   # app_id: $GITHUB_APP_ID            # Optional: GitHub App ID (integer or $ENV_VAR)
   # private_key: $GITHUB_APP_PRIVATE_KEY  # Optional: GitHub App private key PEM or $ENV_VAR
   # installation_id: $GITHUB_APP_INSTALLATION_ID  # Optional: installation ID (integer or $ENV_VAR)
 
+  # --- Asana fields (when kind == "asana") --- UNDER DEVELOPMENT
+  # api_key: $ASANA_ACCESS_TOKEN      # Required: token or $ENV_VAR
+  # endpoint: https://app.asana.com/api/1.0  # Optional: override Asana API base URL
+  # project_gid: "1234567890123456"   # Required: Asana project GID
+  # active_sections:                  # Optional: default ["To Do", "In Progress"]
+  #   - In Progress
+  # terminal_sections:                # Optional: default ["Done", "Cancelled"]
+  #   - Done
+  #   - Cancelled
+
   # --- Shared filter fields (both trackers) ---
   # filter:
   #   assignee: user1, user2          # Optional: CSV or YAML array; case-insensitive OR match
@@ -386,12 +446,15 @@ hooks:
 
 agent:
   max_concurrent_agents: 10           # Optional: global concurrency limit, default 10
+  max_turns: 20                       # Optional: max turns per agent run, default 20
   max_retry_backoff_ms: 300000        # Optional: max retry delay in ms, default 300000
   max_concurrent_agents_by_state:     # Optional: per-state concurrency limits
     in progress: 5
 
 claude:
   command: claude                     # Optional: Claude Code CLI command, default "claude"
+  model: claude-sonnet-4-5-20250514   # Optional: override Claude model. Default: CLI default
+  effort: high                        # Optional: reasoning depth — 'low', 'medium', 'high', or 'max'. Default 'high'.
   permission_mode: acceptEdits        # Optional: one of 'default', 'acceptEdits', 'bypassPermissions'. Defaults to 'bypassPermissions'.
   allowed_tools:                      # Optional: restrict available tools
     - Read
@@ -405,13 +468,26 @@ claude:
   turn_timeout_ms: 3600000            # Optional: per-turn timeout in ms, default 3600000
   read_timeout_ms: 5000               # Optional: initial subprocess read timeout in ms, default 5000
   stall_timeout_ms: 300000            # Optional: stall detection timeout, default 300000
+  system_prompt: "custom prompt"      # Optional: custom system prompt string. Default: built-in claude_code preset
   settings:
     attribution:
       commit: "🙏 Generated with [Work Please](https://github.com/pleaseai/work-please)"  # Optional: appended to git commit messages. Defaults to Work Please link.
       pr: "🙏 Generated with [Work Please](https://github.com/pleaseai/work-please)"      # Optional: appended to PR descriptions. Defaults to Work Please link.
 
+# worker:                              # Optional: SSH worker support (experimental)
+#   ssh_hosts:                         # List of SSH host aliases for remote execution
+#     - worker-1
+#     - worker-2
+#   max_concurrent_agents_per_host: 5  # Max agents per SSH host
+
+# observability:                       # Optional: TUI dashboard settings
+#   dashboard_enabled: true            # Enable TUI dashboard, default true
+#   refresh_ms: 1000                   # Dashboard data refresh interval, default 1000
+#   render_interval_ms: 16             # TUI render interval, default 16
+
 server:
   port: 3000                          # Optional: enable HTTP dashboard on this port
+  host: "127.0.0.1"                   # Optional: bind address, default "127.0.0.1"
 ---
 
 Your prompt template goes here. Available variables:
@@ -425,10 +501,21 @@ Your prompt template goes here. Available variables:
 - {{ issue.assignees }}     — Array of assignee logins (GitHub) or emails (Asana)
 - {{ issue.labels }}       — Array of label strings (normalized to lowercase)
 - {{ issue.blocked_by }}   — Array of blocker refs (each has id, identifier, state)
+- {{ issue.branch_name }}  — PR head branch name (for PullRequest items) or null
 - {{ issue.pull_requests }} — Array of linked PRs (each has number, title, url, state, branch_name)
+- {{ issue.review_decision }} — PR review decision: "approved", "changes_requested", "commented", "review_required", or null
+- {{ issue.has_unresolved_threads }} — Whether the PR has unresolved review threads
+- {{ issue.has_unresolved_human_threads }} — Whether the PR has unresolved non-bot review threads
 - {{ issue.priority }}     — Numeric priority or null
 - {{ issue.created_at }}   — ISO-8601 creation timestamp
 - {{ issue.updated_at }}   — ISO-8601 last-updated timestamp
+- {{ issue.project }}      — GitHub Projects v2 context (null for Asana):
+  - {{ issue.project.owner }}          — Project owner login
+  - {{ issue.project.number }}         — Project number
+  - {{ issue.project.project_id }}     — Project GraphQL node ID (resolved at runtime)
+  - {{ issue.project.item_id }}        — Project item GraphQL node ID
+  - {{ issue.project.field_id }}       — Status field GraphQL node ID (resolved at runtime)
+  - {{ issue.project.status_options }} — Array of { name, id } for status field options
 - {{ attempt }}            — Retry attempt number (null on first run)
 ```
 
@@ -578,7 +665,7 @@ Start with `default` or `acceptEdits` unless you are running in a fully isolated
 
 ## License
 
-Apache License 2.0. See [LICENSE](vendor/symphony/LICENSE) for details.
+Functional Source License 1.1, MIT Future License (FSL-1.1-MIT). See [LICENSE](LICENSE) for details.
 
 Work Please is a TypeScript implementation based on the
 [Symphony specification](vendor/symphony/SPEC.md) by OpenAI (Apache 2.0).