docs: plan workspace agent context

[mariusvniekerk]

Workspace agents currently infer PR and issue context from branch names, paths, repo instructions, and UI state. That works surprisingly well for provider-backed items, but Kata task workspaces need an explicit source-aware context path because their task identity is not a provider issue or pull request number.

This draft captures the proposed generated-context design, including a canonical workspace context file, launch-scoped agent-specific files, and guardrails against overwriting repo-owned AGENTS.md or CLAUDE.md.

^{generated by a clanker}

[roborev-ci]

roborev: Combined Review (8bebd53)

Medium-risk issue found in the implementation plan; security review found no additional issues.

Medium

• docs/superpowers/plans/2026-06-29-workspace-agent-context-implementation.md:252
  The plan writes generated context files such as .middleman/agent-context.md, CLAUDE.md, and AGENTS.local.md inside the Git worktree without excluding them from Git status or workspace diffs. Existing dirty checks count untracked files, so prepared workspaces could appear dirty, pollute diffs, and block workflows requiring a clean worktree.
  Fix: Add implementation and tests to keep generated context files out of Git status/diff, for example by writing outside the worktree or adding exact generated paths to .git/info/exclude before writing. Include setup/launch tests asserting git status --porcelain remains clean.

---

Panel: ci_default_security | Synthesis: codex, 8s | Members: codex_default (codex/default, done, 1m59s), codex_security (codex/security, done, 12s) | Total: 2m19s

[roborev-ci]

roborev: Combined Review (81e5f0a)

Summary verdict: two Medium findings need addressing; no High or Critical findings were reported.

Medium

• docs/superpowers/plans/2026-06-29-workspace-agent-context-implementation.md:277

  • Problem: The plan writes generated context files into the checked-out worktree, but the dirty-worktree task never requires excluding or cleaning them. This could make workspaces show middleman-generated untracked files and risk accidental commits or diff pollution.
  • Fix: Add an implementation/test step to keep generated paths out of git status, such as updating the per-worktree git exclude for .middleman/agent-context.md and safe generated agent files, or storing the canonical context in a git-private path.

• docs/superpowers/plans/2026-06-29-workspace-agent-context-implementation.md:142

  • Problem: The associated-PR test treats MRTitle on an issue workspace as the associated PR title, but existing workspace summaries use those fields for the owner item. For issue workspaces, the title is the issue title and associated PR metadata is not joined.
  • Fix: Either only render the associated PR number from AssociatedPRNumber, or add an explicit associated-PR lookup/model and tests that keep issue title data separate from linked PR data.

---

Panel: ci_default_security | Synthesis: codex, 12s | Members: codex_default (codex/default, done, 2m7s), codex_security (codex/security, done, 9s) | Total: 2m28s

[roborev-ci]

roborev: Combined Review (5498679)

Documentation-only review combined: 2 Medium findings, no High or Critical findings.

Medium

• docs/superpowers/plans/2026-06-29-workspace-agent-context-implementation.md:89
  The plan writes generated context files directly into the worktree but does not require excluding them from Git status/diff output or protecting an existing unmarked .middleman/agent-context.md. Implemented as written, setup/launch could make every workspace dirty and may overwrite repo/user-owned files.
  Fix: Add an explicit task to either store generated context outside the worktree or add local Git excludes and ownership-marker checks for every generated path, including .middleman/agent-context.md, with tests proving workspace diffs stay clean and unmarked files are preserved.

• docs/superpowers/plans/2026-06-29-workspace-agent-context-implementation.md:26
  The plan says to build source-aware context from WorkspaceSummary, but the proposed context includes source URLs and the test snippets use issue-specific title fields that the current summary shape does not provide as such. This leaves no concrete data path for rendering provider issue/PR URLs and risks an implementation that silently omits the most useful source link.
  Fix: Add a task to fetch or expose generic source item fields such as title, state, and URL from the existing issue/MR rows, and update the planned tests to assert those fields are populated.

---

Panel: ci_default_security | Synthesis: codex, 9s | Members: codex_default (codex/default, done, 3m2s), codex_security (codex/security, done, 15s) | Total: 3m26s

[roborev-ci]

roborev: Combined Review (b78bd4f)

Documentation-only PR has medium-risk design issues to address before implementation.

Medium

• docs/superpowers/plans/2026-06-29-workspace-agent-context-implementation.md:412
  The plan appends generated ignore rules to the worktree’s .gitignore, which can modify a tracked repo file or create an untracked .gitignore, polluting workspace diffs and risking accidental PR changes.
  Fix: Write these entries to a Git-local exclude file, such as the path from git rev-parse --git-path info/exclude, and add a test that context generation leaves git status --porcelain clean except for user edits.

• docs/superpowers/plans/2026-06-29-workspace-agent-context-implementation.md:609
  Target-specific files are only written when absent and are never refreshed afterward, so a CLAUDE.local.md or AGENTS.local.md created by middleman on the first launch can become stale even though launch-time freshness is a stated requirement.
  Fix: Make companion files stable pointers to .middleman/agent-context.md, or safely distinguish and refresh middleman-owned files while still leaving user-owned files untouched; add a test for an existing generated local file after workspace metadata changes.

---

Panel: ci_default_security | Synthesis: codex, 9s | Members: codex_default (codex/default, done, 1m39s), codex_security (codex/security, done, 14s) | Total: 2m2s

[mariusvniekerk]

If we don't add the gitignore changes it will be WORSE

[roborev-ci]

roborev: Combined Review (40c0edc)

Review verdict: changes need follow-up before merge due to medium coverage and instruction-injection risks.

Medium

• internal/server/huma_routes.go:6376
  The launch-time agent context behavior is only covered by a direct handler test, not an API/e2e test through ServeHTTP with the real route, SQLite row, and worktree side effects. This is a user-visible workspace runtime workflow, and repo guidance expects route-level coverage for API/data-flow changes.
  Fix: Add an API/e2e test for POST /api/v1/workspaces/{id}/runtime/sessions that launches an agent target and asserts stale canonical context is refreshed, the correct companion file is created/preserved, and generated paths are ignored.

• internal/workspace/agent_context.go:116
  Kata metadata is written into agent context as raw Markdown list values. A task/project name, short ID, qualified ID, or UID containing embedded newlines can break out of the - Label: value line and inject apparent top-level instructions into .middleman/agent-context.md, which local agents are then pointed at via AGENTS.local.md/CLAUDE.local.md.
  Fix: Treat Kata/provider-derived strings as untrusted. Render them in a safer form such as blockquoted sections, or normalize scalar fields by removing/rejecting CR/LF and Markdown structure. Add tests with newline-bearing Kata metadata fields, not just hostile titles.

---

Panel: ci_default_security | Synthesis: codex, 9s | Members: codex_default (codex/default, done, 5m37s), codex_security (codex/security, done, 2m32s) | Total: 8m18s