ui_implementation

This phase extends the implementing phase. Each batch is built one item at a time and code-evaluated exactly as in implementing, and then passes through two additional verification loops before it commits:

1. A QA placement loop — a QA sub-agent drives the running app through the Playwright MCP, judges placement and controls, and emits an end-to-end step list.
2. An end-to-end loop — those steps are authored into Playwright test files, run, and verified, with remediation when they fail.</task>

The UI implementation plan (plan.json, kind: ui) is a required input for this phase. It is not generated during implementation — it is produced during the planning phase. Confirm the plan and its companion notes/ directory exist before starting. Follow the exact workspace path forgectl prints; do not assume it.

Running application + e2e runner

This phase needs a launchable app and a Playwright test runner. The following config keys are required and init is rejected if any is empty:

• ui_implementing.app.launch_command — starts the app for QA
• ui_implementing.app.url — the URL the QA sub-agent navigates to via the Playwright MCP
• ui_implementing.e2e.test_command — runs the authored Playwright suite
• ui_implementing.e2e.test_dir — where authored Playwright test files are written

Playwright MCP

The QA loop drives the running app through the Playwright MCP. Confirm the Playwright MCP is available before starting QA — the QA sub-agent needs browser_navigate, browser_snapshot, browser_click, browser_type, browser_console_messages, and browser_take_screenshot. See references/qa-playwright.md. </prerequisites>

1. session_start
2. state_loop

<session_start> Session Start

You need a domain — the user MUST supply this. All paths below are relative to {domain}.

1. Read {domain}/CLAUDE.md for project-specific operational notes (how to launch the app, where tests live).
2. Run forgectl status to check for an active session.
3. If no state file exists — initialize:

   forgectl init \
     --from {domain}/.forgectl_workspace/ui_plan/plan.json \
     --phase ui_implementing

   All batch sizes, round limits, eval modes, app config, and e2e config are read from .forgectl/config (TOML) and locked into the state file at init time.
4. If a state file exists — read the output to understand the current state and loop.
5. Enter the state loop.

See: references/forgectl-workflow.md for init flags and options. </session_start>

<state_loop> State Loop

Forgectl drives a state machine. Every forgectl advance and forgectl status prints the current state and an Action: line. Read and follow the Action guidance, then handle the state per the workflow reference.

The states in the ui_implementing phase are:

ORIENT → IMPLEMENT → EVALUATE → QA_TEST ⟲ UI_REFINE → E2E_AUTHOR → E2E_VERIFY ⟲ E2E_REMEDIATE → ORIENT → … → DONE, with a COMMIT state in between only when enable_commits: false (when enable_commits: true, the batch-terminal commit happens inline at the terminal E2E_VERIFY transition and COMMIT never appears).

Each batch passes through three sequential gates — code EVALUATE, then the QA loop, then the e2e loop — before the batch-terminal commit. The three loops have independent round budgets; any of them may force-accept at its maximum rounds, which marks the batch's items failed at that commit boundary (but does not abort the phase). Every IMPLEMENT round auto-commits its item when enable_commits: true, and under eval.eval_mode: "direct" the code loop re-evaluates directly on FAIL rather than re-entering IMPLEMENT.

For detailed per-state instructions — including the Playwright MCP QA step, Playwright test authoring, the handoff command, required flags, and exact commands — see:

See: references/forgectl-workflow.md </state_loop>

<contextual_information>

Domain

The root directory for the project being implemented. The user supplies this. All workspace files, specs, source code, and operational notes live under {domain}/.

Forgectl Scaffold

The forgectl scaffold is the single source of truth for what to do next and where files live. Do NOT choose items yourself, and do NOT assume workspace paths — every output includes the resolved paths and an Action: line. Follow them. See: references/forgectl-workflow.md

Two sub-agent commands: eval and handoff

In every evaluator state (EVALUATE, QA_TEST, E2E_VERIFY) there are two actors:

• The sub-agent runs forgectl eval to receive its full context (evaluator prompt, items, app URL, step-list/report target paths), does its work, and then runs forgectl handoff <file>… to register the files it produced.
• You (the engineer) review the agent-provided files named on the Review: line, then run forgectl advance --verdict PASS|FAIL (with --eval-report in report mode).

handoff is how the file the sub-agent wrote becomes the file forgectl tells you to review. It carries no verdict.

QA via the Playwright MCP

In QA_TEST the sub-agent drives the running app through the Playwright MCP — navigate to the app URL, snapshot the accessibility tree to judge placement and control structure, exercise each control, read the console for runtime errors, and capture screenshots as evidence. It always writes the e2e step list and hands it (and its report) off. See: references/qa-playwright.md

E2E via Playwright test files

In E2E_AUTHOR you author one Playwright test file per scenario from the QA step list into ui_implementing.e2e.test_dir, mapping each scenario's steps to Playwright actions and each expected to a Playwright assertion, then run the suite via ui_implementing.e2e.test_command. These are permanent test assets, unlike the live Playwright MCP driving used in QA.

Subagents

See: references/subagent-usage.md

CLAUDE.md

{domain}/CLAUDE.md is for operational notes only (how to launch the app, run the e2e suite). Update it (via subagent) when you learn something new about running the application. Keep it brief.

</contextual_information>

<IMPORTANT_INFO>

99999. Forgectl is the driver. Run forgectl status when unsure. Read and follow the Action: line and the resolved paths in every output — never assume a workspace path.
100000. Every batch passes through all three gates (code eval → QA → e2e) before the batch-terminal commit (COMMIT, or the inline auto-commit at terminal E2E_VERIFY when enable_commits: true). Do not try to skip a loop.
100001. The QA sub-agent QAs the running app through the Playwright MCP. If the app will not launch or the URL will not load, that is a real defect — record it as a QA FAIL and fix it in UI_REFINE.
100002. E2E tests are authored only from the QA step list — do not invent scenarios absent from it. The most recent step list wins.
100003. The sub-agent hands its outputs back with forgectl handoff before you record a verdict. The step list is handed off in every mode. 9999999999. Implement functionality completely. No placeholders, no stubs. 99999999999. For any bugs you notice, fix them as part of the current item or note them in the implementation log — even if unrelated to the current piece of work. 999999999999. When authoring documentation and tests, capture the why.

</IMPORTANT_INFO>