[P0] Unify Forge agent/workforce model for Claude, Codex, editable prompts, and Workspace roadmap

[Joncallim]

Priority

P0. This is a product-architecture clarity issue that should be resolved before the next Workforce execution slices become more visible or harder to unwind.

Outcome

Forge should have one coherent agent/workforce model that works for both Claude Code and Codex, with editable worker prompts managed inside the authenticated Forge app/workspace.

Claude Code and Codex should be treated as execution providers/runtimes, not as separate product taxonomies. The actual Forge catalogue should use broad, understandable role families such as Product, UX, Frontend, Backend, QA, Review, Security, DevOps, Documentation, and Release, with narrower specialist behaviour expressed as harness/prompt overlays or workforce-role assignments.

The implementation and docs should stop implying that the agent breakdown is only for Codex. Users logged into Forge should be able to plainly view and edit the different worker prompts; unauthenticated users and the outside world should not see the private prompt/workforce catalogue through the app.

Current confusion to resolve

• AGENTS.md is titled and framed around Codex PM orchestration. It says the role applies when Forge is operated through Codex and that manual Codex operation should spawn agents from .codex/agents/.
• web/CLAUDE.md only points at @AGENTS.md, so Claude inherits a Codex-framed instruction surface instead of a Claude/Codex-neutral Forge agent model.
• web/db/seed-agents.ts currently bootstraps defaults from .codex/agents/*.toml into the workspace prompt store, with .claude/agents only as a legacy fallback when no .codex files exist.
• The Agents page already supports editing system prompts and grouping agents into workforces, but the language still reads like a generic seeded-agent list rather than a deliberate Claude/Codex-neutral Forge workforce catalogue.
• docs/roadmap.md has an Initial specialist catalog with detailed specialists, while the app-level Agents section mostly reflects broad seeded roles. These need a clear relationship rather than two competing catalogues.
• The roadmap does not yet include the long-term Forge Workspace concept as a first-class goal.

Product principles

1. One Forge taxonomy. Product/UX/Frontend/etc are Forge roles. Claude Code, Codex, OpenRouter, Anthropic API, OpenAI API, LiteLLM, Ollama, and ACP are runtimes/providers.
2. Broad app agents, detailed harness overlays. Keep the visible Agents catalogue broad and comprehensible. Map detailed specialists such as Product planner, Requirements analyst, UX flow designer, Accessibility specialist, React implementation specialist, E2E test specialist, Security reviewer, and Release manager to harness overlays, role labels, or workforce-specific prompt overlays.
3. Editable prompts are product surface, not hidden repo trivia. Logged-in Forge users should be able to inspect, edit, duplicate, reset, and export/import worker prompts without digging through .codex/agents.
4. Authenticated/private by default. The in-app catalogue, prompt bodies, provider choices, workspace paths, and workforce definitions must require a Forge session. Public docs can describe the concept, but not expose a user’s configured catalogue or private prompts.
5. Docs and app copy must match runtime reality. Do not promise parallel autonomous agents, host-repo writes, commits, PR creation, or merge automation until those features are actually safe and enabled.
6. Forge Workspace is the long-term container. The roadmap should describe Forge Workspace as the private operator control plane for projects, providers, prompts, workforces, tasks, artifacts, approvals, GitHub issues, MCP tools, and run history.

Proposed taxonomy

Layer 1 — Provider/runtime

Examples:

• Claude Code via ACP
• Codex CLI via ACP
• Anthropic API
• OpenAI API
• OpenRouter
• LiteLLM
• Ollama
• Custom provider

These answer: "where/how does the worker run?"

Layer 2 — Broad Forge agent role

Suggested seeded app-level roles:

• Architect
• Product
• UX
• Frontend
• Backend
• QA
• Review
• Security
• DevOps
• Documentation
• Release
• MCP Installer, optional and outside normal core delivery

These answer: "what kind of worker is this?"

Layer 3 — Specialist harness or prompt overlay

Examples mapped from the roadmap's initial specialist catalogue:

• Product planner
• Requirements analyst
• UX flow designer
• Accessibility specialist
• Web design specialist
• React implementation specialist
• Design system specialist
• Frontend performance specialist
• Animation/motion specialist
• API specialist
• Database specialist
• Auth/security specialist
• Integration specialist
• Unit test specialist
• E2E test specialist
• Regression specialist
• CI specialist
• Local install specialist
• Deployment specialist
• Code reviewer
• Security reviewer
• Documentation specialist
• Release manager

These answer: "what exact bounded job shape/prompt/tool policy should be used for this package?"

Layer 4 — Workforce template

Workforces should be configurable teams assembled from broad agents plus role labels/harnesses. Seed more than one useful workforce instead of only one generic Core delivery workforce.

Suggested defaults:

• Core Delivery: Architect, Product, UX, Frontend, Backend, QA, Review, Security, DevOps, Documentation.
• Product Discovery: Product, UX, Documentation, Review.
• UX/UI Delivery: Product, UX, Frontend, QA, Accessibility/Review.
• Frontend Delivery: Product or UX as needed, Frontend, QA, Review, Performance.
• Backend/API Delivery: Backend, Database, QA, Security, Review.
• Release/Deployment: DevOps, QA, Security, Release, Documentation.
• MCP Setup/Tooling: MCP Installer, DevOps, Security, Documentation.

Implementation plan

Phase 0 — Decision record and naming contract

• Add or update an ADR defining the four-layer model: provider/runtime, broad Forge agent role, specialist harness/prompt overlay, and workforce template.
• Define canonical terms for Agent, Provider, Runtime, Harness, Workforce, Work Package, Architect, Prompt, and Forge Workspace.
• Decide whether detailed specialists live in agent_harnesses, prompt overlays, workforce role labels, or a new explicit catalogue table.
• State clearly that Claude/Codex are runtimes/providers, not separate specialist catalogues.

Phase 1 — Repository prompt/source layout

• Stop treating .codex/agents as the product source of truth.
• Introduce a Claude/Codex-neutral default prompt bundle location or naming convention, for example prompts/agents, web/defaults/agents, or web/lib/agents/default-catalog.ts.
• Keep .codex/agents only as optional manual Codex helper files, or generate/sync them from the neutral Forge catalogue if still useful.
• Replace web/CLAUDE.md -> @AGENTS.md with Claude-appropriate guidance that points to the same neutral Forge taxonomy.
• Update AGENTS.md so it no longer reads as "Forge agents are only used for Codex." It can still include a manual Codex workflow section, but the product model must be Claude/Codex-neutral.

Phase 2 — Seed and migration changes

• Update web/db/seed-agents.ts so seeded defaults come from the neutral Forge catalogue, not directly from .codex/agents as the primary source.
• Add broad default agents: Product, UX, Security, and Release if they are missing.
• Preserve existing seeded agents and user-created records where possible. Do not break existing agentType references.
• Exclude MCP Installer from normal Core Delivery, but keep it available for MCP-specific workforces.
• Seed multiple workforces by discipline using the taxonomy above.
• Add migration/backfill logic that avoids overwriting user-edited prompts unless an explicit overwrite/reset path is chosen.

Phase 3 — Prompt editing UX

• Make prompt editing an explicit first-class part of the Agents page, not an incidental textarea.
• For each worker prompt, show:
  • display name,
  • broad role,
  • runtime/provider assignment,
  • active/archived state,
  • whether it is seeded or custom,
  • last edited time/user,
  • workspace prompt file path where applicable,
  • diff-from-default state where applicable.
• Add plain actions:
  • Edit prompt,
  • Save prompt,
  • Reset to Forge default,
  • Duplicate/fork as custom worker,
  • Archive/unarchive,
  • Export/import prompt where safe.
• Keep prompt bodies and workspace paths behind authenticated API routes only.
• Preserve the DB-to-workspace-file sync path and make errors understandable.

Phase 4 — Agents/Workforces UI reconciliation

• Update the Agents section so the visible catalogue uses broad Forge roles, not narrow one-off specialists as top-level app agents.
• Move detailed specialist catalogue concepts into workforce role labels, harnesses, overlays, or a separate Specialist/Harness section.
• Update Workforces so users can see discipline-specific teams such as Product, UX/UI, Frontend, Backend/API, QA/Review, Release/Deployment, and MCP Setup.
• Make it obvious that the same workforce can run through Claude Code, Codex, or another provider depending on provider/runtime configuration.
• Avoid language that implies future routing already exists if it is still gated, sandbox-only, or planning-only.

Phase 5 — Documentation language pass

Update these docs for consistent terminology and current behaviour:

• README.md
• AGENTS.md
• web/CLAUDE.md
• web/README.md
• docs/wiki.md
• docs/operator-guide.md
• docs/developer-guide.md
• docs/roadmap.md
• docs/acp-zed-connector.md
• docs/design.md
• relevant ADRs under docs/adr/

Required language changes:

• Replace Codex-only framing with Claude/Codex-neutral Forge language.
• Use "provider/runtime" for Claude Code and Codex.
• Use "Agent" for broad Forge worker identity.
• Use "Harness" or "specialist overlay" for detailed specialist execution contracts.
• Use "Workforce" for reusable teams assembled from agents/harnesses.
• Make current limits explicit: no host-repo writes, commits, PR creation, merge automation, parallel execution, or unrestricted MCP runtime grants unless a future issue implements them.

Phase 6 — Roadmap: Forge Workspace long-term goal

Add a roadmap section for Forge Workspace as a long-term product goal.

Suggested framing:

Forge Workspace is the private, authenticated control plane that ties together:

• projects and repositories,
• GitHub issues and roadmap state,
• MCP tools and provider/runtime configuration,
• editable agent prompts and workforce templates,
• task queue, work packages, run logs, and artifacts,
• approval gates and review history,
• operator settings, workspace files, and recovery flows.

The near-term app remains local/single-operator. The long-term direction is a coherent workspace where the operator manages AI coding work across projects without exposing private prompt/workforce configuration publicly.

Acceptance criteria

• AGENTS.md no longer implies Forge's agent breakdown is Codex-only.
• web/CLAUDE.md gives Claude a correct Claude/Codex-neutral Forge context instead of only inheriting Codex-framed wording.
• The docs define Claude Code and Codex as providers/runtimes, not separate product taxonomies.
• The app-level Agents catalogue uses broad Forge roles such as Product, UX, Frontend, Backend, QA, Review, Security, DevOps, Documentation, and Release.
• The roadmap's detailed initial specialist catalogue is mapped into harnesses, overlays, or workforce role labels rather than competing with the app-level Agents catalogue.
• Workforces are broken down into useful discipline/team templates, not only one generic Core Delivery team.
• Logged-in users can plainly edit worker prompts in the Forge UI.
• Prompt edits persist to the database and workspace prompt files without overwriting user edits during normal upgrades.
• Users can reset seeded prompts to Forge defaults intentionally.
• Agent/workforce/prompt APIs require a valid session and do not expose private prompt bodies or workspace paths to unauthenticated users.
• Public docs describe concepts without exposing any user-specific configured prompt catalogue.
• docs/roadmap.md includes Forge Workspace as a long-term goal.
• Current limitations are consistently stated across README, roadmap, wiki/operator/developer docs, AGENTS.md, and ACP docs.

Verification

• Seed test confirms the broad default agent catalogue and discipline-specific default workforces.
• Migration/backfill test confirms existing user-created agents/workforces and user-edited prompts are preserved.
• API tests confirm unauthenticated access to agents, workforces, and prompt bodies is rejected.
• API/UI tests confirm prompt edit, reset-to-default, duplicate/fork, and archive flows.
• Docs review confirms the terms Agent, Provider, Runtime, Harness, Workforce, Work Package, and Forge Workspace are used consistently.
• Manual smoke path: configure Claude Code and Codex providers, assign either runtime to the same broad Forge role/workforce, edit a prompt, run an Architect planning task, and verify the displayed language does not imply Codex-only operation.

Related

• [OTHER] Iteratively define and build the Workforce concept #30 — Workforce concept umbrella
• [UX] Simplify Agents/Workforces naming, slugs, and default workforce membership #108 — completed naming/slug cleanup for Agents and Workforces
• [FEATURE] Project workspace layout: Roadmap, GitHub Issues, MCP Tools, and Tasks #109 — Project workspace layout
• Add ACP model-selection strategies for remaining runtimes #114 — ACP model-selection strategies
• [EPIC] Executable Workforce Beta: capability-brokered sequential specialist execution #119 — Executable Workforce Beta

Out of scope for this P0 issue

• Parallel specialist execution.
• Host-repository writes from specialists.
• Branch, commit, pull request, merge, or issue auto-closure automation.
• Full multi-user/team workspace permissions beyond preserving authenticated/private behaviour for the current app.
• Real MCP runtime grants beyond the already planned brokered/sandboxed path.