feat(project): add pr iteration task type

Author: krokoko

AGENTS.md

@@ -24,7 +24,7 @@ To get started and understand the developer flow, follow the [Developer guide](.
 - **`scripts/`** (root) — Optional cross-package helpers; **`scripts/ci-build.sh`** runs the full monorepo build (same as CI).
 - **`cdk/`** — CDK app package (`@abca/cdk`): `cdk/src/`, `cdk/test/`, `cdk/cdk.json`, `cdk/tsconfig.json`, `cdk/tsconfig.dev.json`, and `cdk/.eslintrc.json`.
 - **`cli/`** — `@backgroundagent/cli` — CLI tool for interacting with the deployed REST API (see below).
-- **`agent/`** — Python code that runs inside the agent compute environment (entrypoint, server, system prompt, Dockerfile, requirements).
+- **`agent/`** — Python code that runs inside the agent compute environment (entrypoint, server, system prompt, Dockerfile, requirements). The system prompt is refactored into `agent/prompts/` with a shared base template and per-task-type workflow variants (`new_task`, `pr_iteration`).
 - **`docs/`** — Authoritative Markdown in `guides/` (developer, user, roadmap, prompt) and `design/`; assets in `diagrams/`, `imgs/`. The Starlight docs site lives here (`astro.config.mjs`, `package.json`); `src/content/docs/` is refreshed via `docs/scripts/sync-starlight.mjs`.
 - **`CONTRIBUTING.md`** — Contribution guidelines at the repository root.
 - **`package.json`** (root), **`yarn.lock`** — Yarn workspace root (minimal manifest); dependencies live in **`cdk/`**, **`cli/`**, and **`docs/`** package manifests.
@@ -40,7 +40,7 @@ The `@backgroundagent/cli` package provides the `bgagent` executable for submitt
 - `src/api-client.ts` — HTTP client wrapping `fetch` with auth header injection
 - `src/auth.ts` — Cognito login, token caching (`~/.bgagent/credentials.json`), auto-refresh
 - `src/config.ts` — Read/write `~/.bgagent/config.json`
-- `src/types.ts` — API request/response types (mirrored from `cdk/src/handlers/shared/types.ts`)
+- `src/types.ts` — API request/response types (mirrored from `cdk/src/handlers/shared/types.ts`), including `TaskType` (`new_task` | `pr_iteration`)
 - `src/format.ts` — Output formatting (table, detail view, JSON)
 - `src/debug.ts` — Verbose/debug logging (`--verbose` flag)
 - `src/errors.ts` — `CliError` and `ApiError` classes

agent/Dockerfile

@@ -51,6 +51,7 @@ RUN uv sync --frozen --no-dev --directory /app
 # Copy agent code (ARG busts cache so file edits are always picked up)
 ARG CACHE_BUST=0
 COPY entrypoint.py system_prompt.py server.py task_state.py observability.py memory.py /app/
+COPY prompts/ /app/prompts/
 COPY prepare-commit-msg.sh /app/
 COPY test_sdk_smoke.py test_subprocess_threading.py /app/
 

agent/entrypoint.py

@@ -31,6 +31,7 @@
 import memory as agent_memory
 import task_state
 from observability import task_span
+from prompts import get_system_prompt
 from system_prompt import SYSTEM_PROMPT
 
 # ---------------------------------------------------------------------------
@@ -77,6 +78,9 @@ def build_config(
     dry_run: bool = False,
     task_id: str = "",
     system_prompt_overrides: str = "",
+    task_type: str = "new_task",
+    branch_name: str = "",
+    pr_number: str = "",
 ) -> dict:
     """Build and validate configuration from explicit parameters.
 
@@ -94,6 +98,9 @@ def build_config(
         "max_turns": max_turns,
         "max_budget_usd": max_budget_usd,
         "system_prompt_overrides": system_prompt_overrides,
+        "task_type": task_type,
+        "branch_name": branch_name,
+        "pr_number": pr_number,
     }
 
     errors = []
@@ -103,7 +110,10 @@ def build_config(
         errors.append("github_token is required")
     if not config["aws_region"]:
         errors.append("aws_region is required for Bedrock")
-    if not config["issue_number"] and not config["task_description"]:
+    if config["task_type"] == "pr_iteration":
+        if not config["pr_number"]:
+            errors.append("pr_number is required for pr_iteration task type")
+    elif not config["issue_number"] and not config["task_description"]:
         errors.append("Either issue_number or task_description is required")
 
     if errors:
@@ -303,15 +313,19 @@ def setup_repo(config: dict) -> dict:
     repo_dir = f"{AGENT_WORKSPACE}/{config['task_id']}"
     setup: dict[str, str | list[str] | bool] = {"repo_dir": repo_dir, "notes": []}
 
-    # Derive branch slug from issue title or task description
-    title = ""
-    if config.get("issue"):
-        title = config["issue"]["title"]
-    if not title:
-        title = config["task_description"]
-    slug = slugify(title)
-    branch = f"bgagent/{config['task_id']}/{slug}"
-    setup["branch"] = branch
+    if config.get("task_type") == "pr_iteration" and config.get("branch_name"):
+        branch = config["branch_name"]
+        setup["branch"] = branch
+    else:
+        # Derive branch slug from issue title or task description
+        title = ""
+        if config.get("issue"):
+            title = config["issue"]["title"]
+        if not title:
+            title = config["task_description"]
+        slug = slugify(title)
+        branch = f"bgagent/{config['task_id']}/{slug}"
+        setup["branch"] = branch
 
     # Mark the repo directory as safe for git.  On persistent session storage
     # the mount may be owned by a different UID than the container user,
@@ -343,9 +357,22 @@ def setup_repo(config: dict) -> dict:
         cwd=repo_dir,
     )
 
-    # Create branch
-    log("SETUP", f"Creating branch: {branch}")
-    run_cmd(["git", "checkout", "-b", branch], label="create-branch", cwd=repo_dir)
+    # Branch setup
+    if config.get("task_type") == "pr_iteration" and config.get("branch_name"):
+        log("SETUP", f"Checking out existing PR branch: {branch}")
+        run_cmd(
+            ["git", "fetch", "origin", branch],
+            label="fetch-pr-branch",
+            cwd=repo_dir,
+        )
+        run_cmd(
+            ["git", "checkout", "-b", branch, f"origin/{branch}"],
+            label="checkout-pr-branch",
+            cwd=repo_dir,
+        )
+    else:
+        log("SETUP", f"Creating branch: {branch}")
+        run_cmd(["git", "checkout", "-b", branch], label="create-branch", cwd=repo_dir)
 
     # Trust mise config files in the cloned repo (required before mise install)
     run_cmd(
@@ -402,7 +429,11 @@ def setup_repo(config: dict) -> dict:
         setup["lint_before"] = True
 
     # Detect default branch
-    setup["default_branch"] = detect_default_branch(config["repo_url"], repo_dir)
+    # For PR iteration: use base_branch from orchestrator if available
+    if config.get("task_type") == "pr_iteration" and config.get("base_branch"):
+        setup["default_branch"] = config["base_branch"]
+    else:
+        setup["default_branch"] = detect_default_branch(config["repo_url"], repo_dir)
 
     # Install prepare-commit-msg hook for code attribution
     _install_commit_hook(repo_dir)
@@ -628,6 +659,37 @@ def ensure_pr(
     branch = setup["branch"]
     default_branch = setup.get("default_branch", "main")
 
+    # PR iteration: skip PR creation — just push and return existing PR URL
+    if config.get("task_type") == "pr_iteration":
+        if not ensure_pushed(repo_dir, branch):
+            log("WARN", "Failed to push commits before resolving PR URL")
+        log("POST", "PR iteration — returning existing PR URL")
+        result = subprocess.run(
+            [
+                "gh",
+                "pr",
+                "view",
+                branch,
+                "--repo",
+                config["repo_url"],
+                "--json",
+                "url",
+                "-q",
+                ".url",
+            ],
+            cwd=repo_dir,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            pr_url = result.stdout.strip()
+            log("POST", f"Existing PR: {pr_url}")
+            return pr_url
+        stderr_msg = result.stderr.strip() if result.stderr else "(no stderr)"
+        log("WARN", f"Could not resolve existing PR URL (rc={result.returncode}): {stderr_msg}")
+        return None
+
     # Check if the agent already created a PR for this branch
     log("POST", "Checking for existing PR...")
     result = subprocess.run(
@@ -1482,7 +1544,13 @@ def _build_system_prompt(
     overrides: str,
 ) -> str:
     """Assemble the system prompt with task-specific values and memory context."""
-    system_prompt = SYSTEM_PROMPT.replace("{repo_url}", config["repo_url"])
+    task_type = config.get("task_type", "new_task")
+    try:
+        system_prompt = get_system_prompt(task_type)
+    except ValueError:
+        log("ERROR", f"Unknown task_type {task_type!r} — falling back to default system prompt")
+        system_prompt = SYSTEM_PROMPT
+    system_prompt = system_prompt.replace("{repo_url}", config["repo_url"])
     system_prompt = system_prompt.replace("{task_id}", config["task_id"])
     system_prompt = system_prompt.replace("{workspace}", AGENT_WORKSPACE)
     system_prompt = system_prompt.replace("{branch_name}", setup["branch"])
@@ -1513,6 +1581,14 @@ def _build_system_prompt(
             memory_context_text = "\n".join(mc_parts)
     system_prompt = system_prompt.replace("{memory_context}", memory_context_text)
 
+    # Substitute PR-specific placeholders
+    pr_number_val = config.get("pr_number", "")
+    if pr_number_val:
+        system_prompt = system_prompt.replace("{pr_number}", str(pr_number_val))
+    elif "{pr_number}" in system_prompt:
+        log("WARN", "System prompt contains {pr_number} placeholder but no pr_number in config")
+        system_prompt = system_prompt.replace("{pr_number}", "(unknown)")
+
     # Append Blueprint system_prompt_overrides after all placeholder
     # substitutions (avoids double-substitution if overrides contain
     # template placeholders like {repo_url}).
@@ -1628,6 +1704,9 @@ def run_task(
     system_prompt_overrides: str = "",
     prompt_version: str = "",
     memory_id: str = "",
+    task_type: str = "new_task",
+    branch_name: str = "",
+    pr_number: str = "",
 ) -> dict:
     """Run the full agent pipeline and return a result dict.
 
@@ -1652,6 +1731,9 @@ def run_task(
         aws_region=aws_region,
         task_id=task_id,
         system_prompt_overrides=system_prompt_overrides,
+        task_type=task_type,
+        branch_name=branch_name,
+        pr_number=pr_number,
     )
 
     log("TASK", f"Task ID: {config['task_id']}")
@@ -1678,6 +1760,8 @@ def run_task(
                     prompt = hydrated_context["user_prompt"]
                     if hydrated_context.get("issue"):
                         config["issue"] = hydrated_context["issue"]
+                    if hydrated_context.get("resolved_base_branch"):
+                        config["base_branch"] = hydrated_context["resolved_base_branch"]
                     if hydrated_context.get("truncated"):
                         log("WARN", "Context was truncated by orchestrator token budget")
                 else:

agent/prompts/__init__.py

@@ -0,0 +1,20 @@
+"""Prompt module — selects the system prompt template by task type."""
+
+from .base import BASE_PROMPT
+from .new_task import NEW_TASK_WORKFLOW
+from .pr_iteration import PR_ITERATION_WORKFLOW
+
+_PROMPTS = {
+    "new_task": BASE_PROMPT.replace("{workflow}", NEW_TASK_WORKFLOW),
+    "pr_iteration": BASE_PROMPT.replace("{workflow}", PR_ITERATION_WORKFLOW),
+}
+
+
+def get_system_prompt(task_type: str = "new_task") -> str:
+    """Return the system prompt template for the given task type.
+
+    Raises ValueError for unknown task types.
+    """
+    if task_type not in _PROMPTS:
+        raise ValueError(f"Unknown task_type: {task_type!r}. Valid types: {list(_PROMPTS.keys())}")
+    return _PROMPTS[task_type]

agent/prompts/base.py

@@ -0,0 +1,62 @@
+"""Shared base prompt — identity, environment, and rules.
+
+Placeholders replaced at runtime by entrypoint.py:
+  {repo_url}          — GitHub repo (owner/repo)
+  {task_id}           — Unique task identifier
+  {workspace}         — Workspace root (AGENT_WORKSPACE env var, default /workspace)
+  {branch_name}       — Git branch created by the entrypoint
+  {default_branch}    — Repository default branch (e.g. main, master)
+  {max_turns}         — Maximum agent turns for this task
+  {setup_notes}       — Results of mise install and initial build
+  {memory_context}    — Cross-task memory (repo knowledge + past episodes)
+  {workflow}          — Task-type-specific workflow steps (injected by __init__.py)
+"""
+
+BASE_PROMPT = """\
+You are a background coding agent. You work fully unattended — no human will \
+interact with you during execution. You must make all decisions autonomously.
+
+## Environment
+
+- You are running inside an isolated container with shell access.
+- The repository `{repo_url}` is already cloned at `{workspace}/{task_id}`.
+- You are on branch `{branch_name}`.
+- The repository default branch is `{default_branch}`.
+- Git is configured and authenticated — `git push` works without extra setup.
+- The `gh` CLI is pre-installed and authenticated via GH_TOKEN.
+- Dependencies have been installed via `mise install`.
+- An initial build (`mise run build`) has already been run.
+- An initial lint (`mise run lint`) has already been run.
+- You have a maximum of **{max_turns} turns**. Prioritize the most impactful \
+changes first and work efficiently. Avoid spending excessive turns exploring — \
+understand what you need, then act.
+
+### Setup results
+
+{setup_notes}
+
+### Previous knowledge about this repository
+
+{memory_context}
+
+{workflow}
+
+## Rules
+
+- **Full permissions**: Execute any shell commands, modify any files, install \
+any dependencies. The container is isolated — no blast radius.
+- **No confirmation**: Never pause or ask for input. Make reasonable decisions \
+and document them.
+- **No skipping steps**: Step 3 (test) is mandatory. Even if the change seems \
+trivial, you must run `mise run build` and report the result. The PR description \
+must include evidence that build and tests were run.
+- **Error handling**: If a step fails twice, commit whatever work you have, \
+document the error in the PR description, and create the PR with partial results. \
+Do not loop indefinitely.
+- **Lint before commit**: Run available linters and type-checks before each commit.
+- **Commit conventions**: Follow the repo's commit style if discoverable. \
+Otherwise use conventional commit format: `<type>(<module>): description` where \
+type is feat/fix/chore/docs/refactor/test and module is the area of the codebase \
+(e.g., `auth`, `api`, `github`, `ci`).
+- **Branch naming**: Already set — push to `{branch_name}`.
+"""

agent/prompts/new_task.py

@@ -0,0 +1,69 @@
+"""Workflow section for new_task (create a new PR)."""
+
+NEW_TASK_WORKFLOW = """\
+## Workflow
+
+Follow these steps in order:
+
+1. **Understand the codebase**
+   Read relevant files, check the project structure, look at existing tests, \
+build scripts, and CI configuration. Understand the project before changing it.
+
+2. **Work on the task**
+   Make the necessary code changes. Be thorough but focused — only change what \
+the task requires. Do not refactor unrelated code.
+
+3. **Test your changes**
+   This step is MANDATORY — do NOT skip it.
+   - Run the project build: `mise run build`
+   - Run linters and type-checkers if available.
+   - If the project has tests, run them (e.g., `npm test`, `pytest`, `make test`).
+   - If the project has no tests, validate your changes manually (e.g., syntax \
+check, dry-run) and note this in the PR.
+   - Report test and build results in the PR description — both passes and failures.
+
+4. **Commit and push frequently**
+   After each logical unit of work, commit and push:
+   ```
+   git add <specific files>
+   git commit -m "<type>(<module>): <description>"
+   git push -u origin {branch_name}
+   ```
+   Follow the repo's commit conventions if specified in CONTRIBUTING.md, \
+CLAUDE.md, or prior commits. If no convention is apparent, default to \
+conventional commit format (`<type>(<module>): description`). \
+Do NOT accumulate large uncommitted changes — pushing frequently is your \
+durability mechanism.
+
+5. **Create a Pull Request**
+   When the work is complete (or after exhausting attempts), you MUST create a PR. \
+Do NOT skip this step or tell the user to do it manually.
+
+   The PR body must include a section titled "## Agent notes" with:
+   - What went well and what was difficult
+   - Any patterns or conventions you discovered about this repo
+   - Suggestions for future tasks on this repo
+
+   Run:
+   ```
+   gh pr create --repo {repo_url} --head {branch_name} --base {default_branch} --title "<type>(<module>): <description>" --body "<body>"
+   ```
+   Follow the repo's PR title conventions if specified. If no convention is \
+apparent, use conventional commit format: `<type>(<module>): description`. \
+Examples:
+   - `feat(auth): add OAuth2 login flow`
+   - `fix(api): handle null response from payments endpoint`
+   - `chore(github): update RFC issue template`
+   - `docs(readme): add deployment instructions`
+   The `<module>` is a short identifier for the area of the codebase being changed \
+(e.g., `auth`, `api`, `github`, `ci`, `docs`). Never omit the module scope.
+
+   The PR body must include:
+   - Summary of changes
+   - Link to the issue (if provided)
+   - Build and test results (what commands were run, output summary, pass/fail)
+   - Decisions made (if the task was ambiguous, explain your choices)
+   - The following sentence: "By submitting this pull request, I confirm that you \
+can use, modify, copy, and redistribute this contribution, under the terms of \
+the [project license](https://github.com/krokoko/agent-plugins/blob/main/LICENSE)."\
+"""