# FUTURE-FEATURES.md — Post-Roadmap Development

_Added: 2026-03-09 | Source: Framework research (Anthropic Skills guide, OpenAI Agents SDK, Google ADK)_

These features are NOT part of the initial roadmap. Build them AFTER the v4 mockup is 100% complete and verified.

---

## 🔴 High Priority (unlocks "App Factory" overnight runs)

### 1. Iterative Refinement Loop

**What:** Verification doesn't stop at one tsc pass. Loop: run tsc → errors? → send back to agent → fix → re-run. Max 3 iterations before escalating to human review.
**Why:** Anthropic explicitly identifies this as the pattern that makes agents reliable. Current single-pass fails silently.
**Where:** `workspace-daemon/src/verification.ts` + `checkpoint-builder.ts`
**Pattern source:** Anthropic Skills Guide — "Iterative Refinement" design pattern

### 2. Agent Handoffs (Context Passing Between Agents)

**What:** When one agent finishes a wave, it passes structured context (git diff, error log, what it built, what it skipped) to the next agent. No more blind starts.
**Why:** Current agents start each task cold. Handoffs are first-class in OpenAI Agents SDK — explicit control transfer with context. This is what keeps overnight runs coherent.
**Where:** New `workspace-daemon/src/handoff.ts`, update adapter interfaces
**Pattern source:** OpenAI Agents SDK — "Handoffs" primitive

### 3. Specialized Agent Roles

**What:** Replace generic Codex adapter with role-specific agents:

- **Researcher** — reads codebase, produces spec/context doc
- **Planner** — takes spec, produces task breakdown with deps
- **Builder** — executes tasks (Codex)
- **Validator** — runs tsc, tests, reviews diff
- **Deployer** — git ops, PR creation, notifications
  **Why:** The "App Factory" screenshot runs specialized roles. Generic agents miss domain context.
  **Where:** `workspace-daemon/src/adapters/` — one file per role
  **Pattern source:** Anthropic Skills — "Domain-specific intelligence" + App Factory pattern

---

## 🟡 Medium Priority

### 4. Parallel Guardrails (tsc watcher during agent run)

**What:** Run tsc in watch mode alongside Codex, not just after. Flag errors in real-time without waiting for checkpoint.
**Why:** OpenAI SDK runs guardrails in parallel with the agent — catches issues without blocking the main flow.
**Where:** New process spawned alongside agent in `agent-runner.ts`
**Pattern source:** OpenAI Agents SDK — "Guardrails" primitive

### 5. Rollback on Checkpoint Rejection

**What:** When a checkpoint is rejected, auto-revert to pre-task git state rather than leaving dirty code in tree.
**Why:** Currently a rejection leaves broken code that the next agent inherits.
**Where:** `workspace-daemon/src/git-ops.ts` — add `revertToCheckpoint()` method

### 6. Context-Aware Tool Selection

**What:** Agent routing logic that picks different tools based on file size, task type, and context. Large refactors → Codex. Small surgical fixes → Claude ACP session. Research tasks → Claude with web search.
**Pattern source:** Anthropic Skills — "Context-aware tool selection" pattern

---

## 🔵 Lower Priority (Enterprise / Scale)

### 7. Session Persistence Surfaced to Agents

**What:** Pass previous run context (what worked, what failed, git history) to agent at start of each task. Agents currently start blind even when re-running.
**Where:** Update adapter `buildPrompt()` to include run history from SQLite

### 8. Progressive Skill Loading for Agent Prompts

**What:** Agent system prompts use Anthropic's 3-level progressive disclosure — minimal header always loaded, full instructions only when triggered, reference docs on demand.
**Why:** Keeps context lean when running many agents in parallel.
**Pattern source:** Anthropic Skills Guide — core architecture

### 9. Skills Marketplace / Agent Skill Definitions

**What:** Define agent "skills" as portable SKILL.md-style files that can be shared, versioned, and swapped. A "React Builder" skill vs "Python API Builder" skill.
**Pattern source:** Anthropic agentskills.io open standard

---

## Summary Table

| Feature                      | Impact  | Effort | Priority    |
| ---------------------------- | ------- | ------ | ----------- |
| Iterative refinement loop    | 🔥 High | Low    | Do first    |
| Agent handoffs               | 🔥 High | Med    | Do second   |
| Specialized agent roles      | 🔥 High | High   | Do third    |
| Parallel guardrails          | Med     | Med    | After roles |
| Rollback on rejection        | Med     | Low    | After roles |
| Context-aware tool selection | Med     | High   | Later       |
| Session persistence          | Low     | Low    | Later       |
| Progressive skill loading    | Low     | Med    | Later       |
| Skills marketplace           | Low     | High   | Much later  |