Enhance ResearchAgent and CodegenBackgroundAgent documentation to improve clarity and usability. Updates include:

- Added canonical storage location for general research packets in ResearchAgent.md.
- Revised General Research operating mode to specify packet creation and inline findings delivery.
- Updated CodegenBackgroundAgent.md to include repository context requirements and improved task specification details.

These changes streamline the research process and clarify expectations for agent operations.

Author: jaruesink

.devagent/agents/ResearchAgent.md

@@ -13,6 +13,7 @@
 
 ## Resource Strategy
 - `.devagent/templates/research-packet-template.md` — base outline for spec- and task-mode packets; duplicate and prune optional sections.
+- `.devagent/research/` — canonical storage for general research packets (format: `YYYY-MM-DD_<topic>.md`).
 - `.devagent/features/YYYY-MM-DD_feature-slug/research/` — canonical storage for feature-spec research artifacts (one folder per feature).
 - `.devagent/features/YYYY-MM-DD_feature-slug/tasks/<task-id>/research/` — storage for task-level research; create subfolders per task when first used.
 - `.devagent/research/drafts/` — scratch space for in-progress packets before filing.
@@ -23,7 +24,7 @@
 - #TaskPlanner — confirm task context, backlog slice, and validation expectations for task-mode research.
 
 ## Operating Modes
-- **General Research:** Triggered by exploratory questions or early discovery. Provide findings inline in chat (summary + key bullets + citations). Log notable open questions in `guiding-questions.md` when future work is implied. No filesystem artifact unless explicitly requested.
+- **General Research:** Triggered by exploratory questions or early discovery. Produce a dated packet at `.devagent/research/YYYY-MM-DD_<topic>.md` using the research packet template. Include summary, key findings, citations, open questions, and recommended next steps. Also provide findings inline in chat when delivering results. Log notable open questions in `guiding-questions.md` when future work is implied.
 - **Spec Research:** Supports feature-level specs. Produce a dated packet at `.devagent/features/YYYY-MM-DD_feature-slug/research/YYYY-MM-DD_<descriptor>.md` using the research packet template. Cross-link to the related spec and mission artifacts.
 - **Task Research:** Informs a specific backlog item. Create a packet at `.devagent/features/YYYY-MM-DD_feature-slug/tasks/<task-id>/research/YYYY-MM-DD_<descriptor>.md`. Include task context (plan excerpt, acceptance criteria, code entry points) so Executor can act with full detail.
 
@@ -40,7 +41,7 @@
 5. **Synthesize:** Summarize answers per question with citations, highlight key findings, and note implications on scope, solution direction, or implementation.
 6. **Validation / QA:** Check alignment with constitution clauses, ensure freshness notes are included, and identify unresolved gaps requiring follow-up by the executing developer.
 7. **Output packaging:**
-   - General mode: Reply in chat with summary, key findings, sources, and explicit open questions.
+   - General mode: Populate the research packet template, store in `.devagent/research/`, and reply in chat with summary, key findings, sources, explicit open questions, and link to the saved packet.
    - Spec mode: Populate the research packet template, store in the feature research folder, and link to it in the status update.
    - Task mode: Populate the template with task context, dependencies, and recommended follow-ups; store in the task research folder and work with the #TaskPlanner/#TaskExecutor as needed.
 8. **Post-run logging:** Update `.devagent/product/guiding-questions.md` with new unknowns, annotate relevant feature or task hubs with research links, and note unresolved escalations.
@@ -56,7 +57,7 @@
 - Restricted access or unavailable sources — log blocker, propose alternate sources/SMEs, and escalate if unresolved within the agreed SLA.
 
 ## Expected Output
-- General: Chat response with summary, findings, citations, and open questions; optional note added to `guiding-questions.md`.
+- General: Markdown packet in `.devagent/research/` directory plus chat response with summary, findings, citations, open questions, and link to the packet; optional note added to `guiding-questions.md`.
 - Spec: Markdown packet in feature research directory, linked summary, and list of recommended next steps for #SpecArchitect.
 - Task: Markdown packet in task research directory containing task context, findings, implementation implications, and follow-up owners for #TaskPlanner/#Executor.
 

.devagent/agents/codegen/CodegenBackgroundAgent.md

@@ -7,9 +7,9 @@
 - Invocation assumption: The executing developer has CODEGEN_API_TOKEN in environment and standing approval to create agent runs; note any resource-intensive or production-impacting tasks for review.
 
 ## Inputs
-- Required: Task specification (from #TaskPlanner or #TaskPromptBuilder), Codegen CLI installed and authenticated.
-- Optional: Specific research packets to include, additional context files, custom prompt sections.
-- Request missing info by: Enumerate gaps with example values (e.g., "Provide task ID from tasks.md", "Link research packet for context"); if CLI not authenticated, provide login instructions.
+- Required: Task specification (from #TaskPlanner or #TaskPromptBuilder), Codegen CLI installed and authenticated, repository ID and base branch.
+- Optional: Specific research packets to include, additional context files, custom prompt sections, PR number (if working from existing PR).
+- Request missing info by: Enumerate gaps with example values (e.g., "Provide task ID from tasks.md", "Specify base branch (main/develop)", "Link research packet for context"); if CLI not authenticated, provide login instructions.
 
 ## Resource Strategy
 - **Codegen CLI** (`codegen` command) - Primary interface for creating agent runs; assumes CLI is installed and authenticated.
@@ -37,6 +37,7 @@
 
 2. **Context gathering:** 
    - Read task specification from `.devagent/tasks/<slug>/tasks.md`
+   - Identify repository context (repo ID, base branch, or relevant PR)
    - Pull linked research packets from `.devagent/features/*/research/`
    - Extract spec sections from `.devagent/features/*/spec/`
    - Identify file hints and code entry points from task
@@ -48,6 +49,7 @@
    **a) Task Overview**
    - Clear, concise objective statement
    - Link to source task ID and feature slug
+   - Repository context (repo ID/name, base branch, or PR number)
 
    **b) Context & Research**
    - Key findings from research packets
@@ -82,8 +84,8 @@
    - Include all context sections in structured format
 
 5. **Agent run creation:**
-   - Create agent via CLI: `codegen create <prompt-file>`
-   - Or pipe prompt directly: `echo "<prompt>" | codegen create -`
+   - Create agent via CLI with repo context: `codegen agent --prompt "$(cat /tmp/prompt.md)" --repo-id <repo-id>`
+   - Include base branch info in prompt (agent will create branch from it)
    - Capture output: agent run ID and web URL
    - Display web URL for monitoring progress
 
@@ -119,6 +121,7 @@
   - Use `--json` flag for structured output
   - Telemetry prompt will default to "no" if stdin unavailable
 - **Incomplete task context:** List missing pieces (research, specs, file hints) and request from #TaskPlanner or #ResearchAgent.
+- **Missing repository context:** Request repo ID and base branch; check task specification or git config for defaults.
 - **Rate limiting (>10 req/min):** Wait and retry after 60 seconds; notify requester of delay.
 - **CLI errors:** Display error output, suggest checking authentication (`codegen org --list`) or CLI version (`codegen update`)
 - **Unclear acceptance criteria:** Request clarification before creating agent run; prompt quality depends on clear requirements.
@@ -214,32 +217,6 @@ EOF
 codegen agent --prompt "$(cat /tmp/prompt.md)"
 ```
 
-**Output (formatted):**
-```
-╭─────────────────────────── 🤖 Agent Run Created ───────────────────────────╮
-│                                                                              │
-│  Agent Run ID: 105016                                                        │
-│  Status:       ACTIVE                                                        │
-│  Created:      October 01, 2025 at 03:43                                     │
-│  Web URL:      https://codegen.com/agent/trace/105016                        │
-│                                                                              │
-╰──────────────────────────────────────────────────────────────────────────────╯
-
-💡 Track progress with: codegen agents
-🌐 View in browser:  https://codegen.com/agent/trace/105016
-```
-
-**Output (JSON):**
-```json
-{
-  "agent_run_id": 105016,
-  "status": "ACTIVE",
-  "web_url": "https://codegen.com/agent/trace/105016",
-  "created_at": "2025-10-01T03:43:00Z"
-}
-```
-
-
 **Pull agent work:**
 ```bash
 codegen pull  # Download branches/changes from completed agents
@@ -310,6 +287,11 @@ codegen update
 ```
 # Task: [Clear, actionable objective]
 
+## Repository Context
+- Repository: [repo name or ID]
+- Base Branch: [main/develop/feature-xyz or PR #123]
+- Target Branch: [branch to create for this work]
+
 ## Context
 [2-3 sentence background on what this task achieves and why]
 
@@ -365,13 +347,17 @@ codegen update
 ```
 #CodegenBackgroundAgent
 - Task: feature-auth-001
+- Repository: devagent (ID: 456)
+- Base branch: main
 - Include research from: .devagent/features/2025-10-01_auth/research/
 ```
 
 **Output:**
 ```bash
 ✓ Prompt constructed (1,247 tokens)
 ✓ Context included:
+  - Repository: devagent (ID: 456)
+  - Base branch: main
   - Research: .devagent/features/2025-10-01_auth/research/jwt-comparison.md
   - Spec: .devagent/features/2025-10-01_auth/spec/core.md
   - Files: src/middleware/auth.ts, tests/auth.test.ts