Skip to content

Rephrased Agent Architecture

Lead-facing. Other disciplines do not need this page. Engineers talk normally in their coding agent (Cursor, Claude Code, Codex, Antigravity, or another MCP-capable IDE); the agent is supposed to run the harness without anyone naming tools.

1. Design goals

  • Sync + /onboard is enough. No per-person agent profile.
  • After work: convention check → human compile → server-side review → human PIE → devlog → submit.
  • Perforce is the VCS. Git is legacy reference only.
  • Unreal MCP (5.8) is suggested editor reach. It does not replace Rephrased MCP.

2. Architecture overview

Engineer: "fix the overlap" / "what should I work on?" / "load LV_2ndPlayable"
    │
    ▼
IDE (Cursor / Claude Code / Codex / Antigravity / other MCP)
    │
    ├── Rephrased MCP (always)     sync_latest, start_task, convention_check, request_review, submit, wiki, devlog
    └── Unreal MCP (editor open)   maps, assets, actors, PIE start/stop

Shared toolkit: tools/rephrased-mcp/. Shipped configs: .cursor/mcp.json and .claude/mcp.json (rephrased only). Other IDEs get the same JSON. Suggested unreal-mcp on port 6388 is added for editor tools.

3. Review gate

  1. sync_latest / start_task — p4 sync, open a described changelist
  2. convention_check — C++ diff (p4 diff) vs UE conventions in AGENTS.md
  3. Compile — human, Development Editor | Win64
  4. request_review — Source/ C++, Config/ text, Content/ asset+map paths → team review server (Rephrased-design review LLM); optional p4 shelve
  5. PIE — human
  6. devlog — then submit (p4 submit)

Enforcement that a change was reviewed before it lands is a server-side Perforce submit trigger (USC admin required) — there is no local guard hook. Exclusive checkout on binary assets prevents concurrent clobbering.

4. What engineers see vs what agents see

Engineers Agents (must call, unprompted)
Sync, /onboard, build, PIE onboarding
Speak in normal language sync_latest / start_task at the start
wiki_query before doc-dependent decisions
convention_check then request_review before submit
devlog after meaningful C++ / systems work
Suggested Unreal MCP while the editor is running

Do not add a skill-name checklist to first-day docs. If a skill file exists on a lead machine, it is backup — MCP is the path.

5. Engineer daily loop

# sync the project from Perforce (P4V "Get Latest Revision", or p4 sync)
uv tool install tools/rephrased-mcp
# MCP config: .cursor/mcp.json, .claude/mcp.json, or paste the same block — then /onboard

p4 sync
# work in Source/ / Content/ (editor checks out files; binaries lock)
# In chat: done / help me submit  →  agent runs the gate, then p4 submit

6. Lead view

  1. Break milestones into tracked work items (team board / lead)
  2. Assign owners
  3. Review shelved changelists before submit
  4. Escalate blocks in Discord

7. Coding-agent fit

Agent Notes
Cursor .cursor/mcp.json
Claude Code .claude/mcp.json
Codex Same MCP JSON in Codex settings. AGENTS.md
Antigravity Same MCP JSON in Antigravity settings. AGENTS.md
Others Same MCP if the IDE can run it. Do not invent a second pipeline.

8. Status

  • [x] Local Rephrased MCP (Perforce flow: sync_latest, start_task, submit)
  • [x] Onboarding (review key + P4 workspace verify)
  • [x] convention_check + request_review (Source/ + Config/ + Content/ paths, p4 diff)
  • [ ] Server-side Perforce submit trigger (USC admin) — enforcement follow-up
  • [x] Unreal MCP on 5.8 (port 6388), verified PIE start on LV_2ndPlayable

Change history

  • 2026-09-05 — Gabriel Li — Migrated the agent architecture to Perforce: gate is sync_latest/start_task → convention_check → compile → request_review (+shelve) → PIE → devlog → submit; dropped local git hooks (enforcement is now a server-side submit trigger, admin-only); git is legacy.

  • 2026-09-05 — Gabriel Li — Updated sandbox references to PreProShowcase (Content/Rephrased/Levels/Prepro/) after the content reorganization (PR #19).

  • 2026-08-14 — Gabriel Li — Review gate names the team review server, not a vendor model; harness list includes Codex and Antigravity; Unreal MCP labeled suggested.

  • 2026-08-13 — Gabriel Li — Invisible-harness rewrite; Unreal MCP + port 6388; review covers Content/Config; skills off the engineer path.
  • 2026-08-10 — Gabriel Li — English rewrite; aligned with shipped MCP toolkit and Source/-scoped review.
  • 2026-07-10 — Gabriel Li — V2 draft: shared pipeline (not profile-per-role), Claude Code agents sketch.
  • 2026-07-10 — Gabriel Li — Initial draft (profile-based architecture, deprecated).