feat: agent harness rewrite -- Bun/TS launcher + Tilt orchestration + prompt assembly

[henry-nsheaps]

Closes #118, Closes #111, Closes #116, Closes #72, Closes #71, Closes #73, Closes #74, Closes #75

Priority: p1

What

Full rewrite of the agent harness: replace the bash launcher with a Bun/TypeScript launcher, integrate Tilt for orchestration, implement prompt assembly (extend/replace modes), remove legacy .ai/ directory, and migrate Alex Picard as the first agent on the new harness.

Checklist

Phase 1: Tiltfile

• Tiltfile with local_resource for agent processes (PR feat: Tiltfile Phase 1 — tmux/local_resource agent orchestration #124 in progress)
• local_tmux_resource integration (depends on ISSUE-04)
• Agent health checks via Tilt

Phase 2: Prompt Assembly

• Agent file discovery + YAML frontmatter parsing (from Implement agent file discovery + YAML frontmatter parsing #71)
• Prompt assembly: extend/replace modes + base prompt selection (from Implement prompt assembly (extend/replace modes + base prompt selection) #72)
• CLAUDE_SETTINGS_DIR per agent for multi-agent isolation (from feat: agent harness should set CLAUDE_SETTINGS_DIR per agent for multi-agent isolation #116)
• Team name as configurable first-class parameter (from Make team name a configurable first-class parameter (end-to-end) #75)
• Launcher field support in agent frontmatter (from Update agent file frontmatter with launcher fields #74)

Phase 3: .ai/ Removal

• Migrate all .ai/ content to .claude/ equivalents
• Remove .ai/ directory
• Update all references across repos

Phase 4: Alex Picard Migration

• Migrate Alex Picard agent to new harness as validation
• Full agent spawning module: CLI construction, tmux, PID tracking (from Implement full agent spawning module (CLI construction, tmux, PID tracking) #73)
• Unified runtime across shared PC, VM, and containers (from Agents monorepo: unified runtime across shared PC, VM, and containers #111)
• End-to-end validation: launch, run, review, shutdown

PR Procedure

Current State

PR	Branch	Status	Conflicts	Review
#124	feat/tiltfile-v2	OPEN	None (MERGEABLE)	None
#106	claude/agents-dev	OPEN	CONFLICTING	Reviewed (COMMENTED, 91/100 ✅)
(new)	feat/harness-phase2-prompt-assembly	Not created	—	—
(new)	feat/harness-phase3-ai-removal	Not created	—	—
(new)	feat/harness-phase4-alex-picard	Not created	—	—

Note on PR #106 (claude/agents-dev): This PR has merge conflicts with main and contains agent templates + behaviors that partially overlap with Phase 2/4 scope. It has been reviewed at 91/100 (COMMENTED, not approved). It should be rebased to resolve conflicts and then merged independently as it does not directly implement harness code — it adds agent definitions that the new harness will load.

Step-by-Step Procedure

Step 1 — Merge PR #124 (Phase 1: Tiltfile)

1. PR feat: Tiltfile Phase 1 — tmux/local_resource agent orchestration #124 (feat/tiltfile-v2) is MERGEABLE with no review decision yet
2. Review the Tiltfile changes against the spec in docs/specs/tilt-orchestration.md
3. Confirm CI passes; merge to main
4. This unblocks Phase 2 work

Step 2 — Rebase and merge PR #106 (agent templates/behaviors)

1. Rebase claude/agents-dev onto main: git fetch origin && git rebase origin/main
2. Resolve merge conflicts (expected in agent definition files)
3. Address P3 QA findings from existing review (absolute path in version-prompt-tracking.md, incomplete github-issue-creator coverage — non-blocking per review)
4. Update PR body with template below
5. Request final approval and merge
6. This delivers new agent templates independently of harness phases

Step 3 — Open PR for Phase 2 (prompt assembly)

1. Create branch feat/harness-phase2-prompt-assembly from main (after feat: Tiltfile Phase 1 — tmux/local_resource agent orchestration #124 merges)
2. Implement: agent file discovery, YAML frontmatter parsing, extend/replace prompt assembly, CLAUDE_SETTINGS_DIR, team name param, launcher field
3. Scope: closes Implement agent file discovery + YAML frontmatter parsing #71, Implement prompt assembly (extend/replace modes + base prompt selection) #72, Make team name a configurable first-class parameter (end-to-end) #75, feat: agent harness should set CLAUDE_SETTINGS_DIR per agent for multi-agent isolation #116, Update agent file frontmatter with launcher fields #74
4. Open draft PR with template body below; move to ready when CI passes

Step 4 — Open PR for Phase 3 (.ai/ removal)

1. Create branch feat/harness-phase3-ai-removal from main (after Phase 2 merges)
2. Pure migration: move .ai/ content to .claude/ equivalents, no functional changes
3. Update all references across repos
4. Scope: closes feat: Rewrite agent harness in Bun/TS with tilt.dev orchestration #118 (partially)
5. Open draft PR; validate no functionality regressed before merging

Step 5 — Open PR for Phase 4 (Alex Picard migration)

1. Create branch feat/harness-phase4-alex-picard from main (after Phase 3 merges)
2. Implement: full agent spawning module (CLI, tmux, PID tracking), unified runtime, end-to-end validation
3. Scope: closes Implement full agent spawning module (CLI construction, tmux, PID tracking) #73, Agents monorepo: unified runtime across shared PC, VM, and containers #111, feat: Rewrite agent harness in Bun/TS with tilt.dev orchestration #118
4. Open draft PR; requires end-to-end test passing before merge

PR Body Template

Each PR body must include:

Part of nsheaps/agents#134

<!-- List specific issues closed by this PR, e.g.: -->
Closes nsheaps/agents#124  <!-- Phase 1 -->

Phase-specific close lines:

• Phase 1 PR (feat: Tiltfile Phase 1 — tmux/local_resource agent orchestration #124): Closes nsheaps/agents#134 only if this is the final phase — otherwise Part of nsheaps/agents#134
• Phase 2 PR: Closes nsheaps/agents#71, Closes nsheaps/agents#72, Closes nsheaps/agents#75, Closes nsheaps/agents#116, Closes nsheaps/agents#74
• Phase 3 PR: Closes nsheaps/agents#118 (partial)
• Phase 4 PR: Closes nsheaps/agents#73, Closes nsheaps/agents#111, and Closes nsheaps/agents#134 (final close)

CI & Merge Checklist

• Rebase onto latest main
• All merge conflicts resolved
• CI passing (lint, typecheck, tests)
• PR body links back to nsheaps/agents#134
• No unrelated changes in diff
• Review approved
• Phase dependencies respected (Phase N+1 not merged before Phase N)

Git Spice Stacking

The phases have hard dependencies. Use git-spice to stack them:

# After Phase 1 merges, create Phase 2 stacked on main:
gs branch create feat/harness-phase2-prompt-assembly --base main

# Phase 3 stacks on Phase 2:
gs branch create feat/harness-phase3-ai-removal --base feat/harness-phase2-prompt-assembly

# Phase 4 stacks on Phase 3:
gs branch create feat/harness-phase4-alex-picard --base feat/harness-phase3-ai-removal

# Submit all as a stack:
gs stack submit

Cleanup

• All superseded issues (feat: Rewrite agent harness in Bun/TS with tilt.dev orchestration #118, Agents monorepo: unified runtime across shared PC, VM, and containers #111, feat: agent harness should set CLAUDE_SETTINGS_DIR per agent for multi-agent isolation #116, Implement prompt assembly (extend/replace modes + base prompt selection) #72, Implement agent file discovery + YAML frontmatter parsing #71, Implement full agent spawning module (CLI construction, tmux, PID tracking) #73, Update agent file frontmatter with launcher fields #74, Make team name a configurable first-class parameter (end-to-end) #75) auto-close via Closes in their respective phase PRs
• Delete branches after merge: feat/tiltfile-v2, claude/agents-dev, feat/harness-phase2-prompt-assembly, feat/harness-phase3-ai-removal, feat/harness-phase4-alex-picard

Context

• PR feat: Tiltfile Phase 1 — tmux/local_resource agent orchestration #124 status: OPEN, mergeable, no review yet
• Related specs (all in agents/docs/specs/):
  • agent-harness-lifecycle.md
  • agent-launcher.md
  • agents-cli.md
  • tilt-orchestration.md
  • directory-taxonomy.md
  • agent-team-architecture.md
  • sub-agent-architecture.md
• Superseded issues: #118, #111, #116, #72, #71, #73, #74, #75

---

🤖 Created as part of issue migration

Related Discord Threads

• feat(agents): basic tiltfile with tmux local_resources
• docs(spec): agent-teams for agent-delegated behaviors and thought processes
• feat(agent-teams): work distribution between automated agents
• feat(bin/agent): system prompt override — replace or append via agent config (tracked as agents#72)
• feat: tilt (tracked as agents#118)
• chore: remove .ai/ folder pattern across all repos
• 999 - migrate alex picard to agent harness
• 999 - agent teams coordination foundation