What the agent does
The agent reads the security setup first. In an app shaped like symfony/demo, composer.json requires PHP >=8.4 and Symfony 8 packages (security-bundle, form, validator, twig-bundle, monolog-bundle, mailer, ux-live-component and stimulus-bundle among them), with phpunit ^11.5, phpstan ^2, php-cs-fixer and dama/doctrine-test-bundle in require-dev, and no two-factor package. config/packages/security.yaml hashes with auto, loads users from App\Entity\User by username, and has one main firewall with form_login (check and login paths both security_login, CSRF on, default target blog_index), remember_me with a one-week lifetime and logout; when@test lowers the hasher cost and adds http_basic to the same firewall. src/Entity/User.php maps symfony_demo_user with id, fullName, username, email, password and a JSON roles column, implements UserInterface and PasswordAuthenticatedUserInterface, and serializes only id, username and password. src/Controller/SecurityController.php renders templates/security/login.html.twig, a Bootstrap form with a Stimulus controller and a table of the fixture users. src/Controller/UserController.php under /profile has user_edit and user_change_password, the latter logging the user out after a change. The database is SQLite at data/database.sqlite from .env, there is no migrations directory, and src/DataFixtures/AppFixtures.php loads jane_admin, tom_admin and john_user with the password kitten.
The plan uses scheb/2fa-bundle with its TOTP provider and a QR-code library for the setup page. User gains a nullable totpSecret column and implements the bundle's TwoFactorInterface: enabled when the secret is set, the username as the account name, and a TOTP configuration with the site as issuer. security.yaml's main firewall gets a two_factor section with the form and check paths, access control lets ^/2fa through for a session that has passed the password step only, and a new config/packages/scheb_2fa.yaml names the TOTP provider and the template. A 2fa_login route renders templates/security/2fa_form.html.twig in the style of login.html.twig with the same CSRF handling, and remember_me stays, since the bundle can trust a device after one successful code. UserController gets user_two_factor under /profile: GET shows a QR code and the secret for an authenticator app, POST verifies one code before the secret is saved, and a second action disables it after a password check through the UserPassword constraint that ChangePasswordType already uses. The new labels go into the translation catalogues under translations/, because lint:translations in lint.yaml reports a key with no translation.
Tests go in tests/Controller next to UserControllerTest.php, which logs in with $client->loginUser($user) and submits forms by button label: one test enables two-factor for jane_admin with a code computed from the stored secret, one shows that a login with the password alone lands on the 2FA form and a wrong code stays there, one shows a correct code reaches the admin, and one keeps john_user, who has no secret, logging in as before. The when@test firewall still carries http_basic, so the agent checks that the existing admin tests, which authenticate that way, are unchanged by the new section. Then it runs what the workflows run: vendor/bin/phpunit from tests.yaml, and from lint.yaml composer validate --strict, lint:yaml config --parse-tags, lint:twig templates --env=prod, lint:xliff translations, lint:translations, lint:container --no-debug, doctrine:schema:validate --skip-sync, composer audit, php-cs-fixer and vendor/bin/phpstan analyze at level 6 against phpstan-baseline.neon.
In its sandbox the agent also serves the app, loads the fixtures with doctrine:fixtures:load, enables two-factor for jane_admin in its browser, logs out, and logs in again with a code from a command-line TOTP implementation, so the pull request can show the second step as a user sees it rather than only as a test.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add TOTP two-factor authentication to this Symfony app. Read composer.json, config/packages/security.yaml, config/bundles.php, .env, src/Entity/User.php, src/Controller/SecurityController.php, src/Controller/UserController.php, src/Form/ChangePasswordType.php, src/DataFixtures/AppFixtures.php, templates/security/login.html.twig, templates/user/change_password.html.twig, tests/Controller/UserControllerTest.php, the translation files and the workflows under .github/workflows first. Add scheb/2fa-bundle with its TOTP provider and a QR-code library, a nullable totpSecret on User implementing the bundle's interface, the two_factor firewall section and access control, a 2FA form template in the style of the login page, and a profile page under /profile where a signed-in user enables two-factor by scanning a QR code and confirming one code, or disables it after a password check. Keep remember-me and the test environment's http_basic working. Add translation keys to every catalogue. Write WebTestCase tests for enabling, a login that stops at the second step, a wrong code, a right code and a user without a secret. Run phpunit, every lint step in lint.yaml, php-cs-fixer and phpstan as CI does, serve the app and walk through enabling and logging in once in the browser, and open a pull request that explains how the schema change is applied and quotes the test and lint output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request on its own branch that changes composer.json and composer.lock, config/bundles.php, config/packages/security.yaml, src/Entity/User.php, src/Controller/SecurityController.php, src/Controller/UserController.php and the translation catalogues, and adds config/packages/scheb_2fa.yaml, templates/security/2fa_form.html.twig, templates/user/two_factor.html.twig and the new tests. Because the project has no migrations directory, the description says which Doctrine schema command applies the new column, and symfony.lock records the new bundle the way Flex expects.
The description quotes the phpunit run with the new tests among the controller tests, the lint and phpstan results, and a short walkthrough with screenshots of the setup page and the second login step from the sandbox browser. It names the issuer string the QR code carries so a reviewer can check what an authenticator app will display.
Before merging, a reviewer decides whether ROLE_ADMIN accounts should be required rather than allowed to enable it, whether to add the bundle's backup codes or trusted-device cookie, and what an administrator does when a user loses the authenticator (clearing the secret with a console command next to app:add-user is the natural follow-up). Each is a follow-up on the same session.
Run it on every admin area protected by a password alone
This is a change to start from the terminal and come back to: one POST /o/{org}/sessions with this prompt and the repository in resources, and the run reads the firewall, adds the bundle, writes the pages and tests and opens the pull request on its own. The sandbox parks with its disk when the turn ends, so require two-factor for ROLE_ADMIN as a follow-up wakes it with vendor/, the SQLite database and the branch in place.
A team with several Symfony apps sends the same body once per repository, one run each, and each run reads that app's own security.yaml and user entity. Give the API key a webhook_url and Rush posts run.completed or run.failed with the session_url when each turn ends, so the pull request links collect in one channel. Send a request_id with each body so a retried POST returns the run it already started.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Two-factor login touches the firewall, the user entity, two templates, translations and the tests at once, and the only way to know the pieces fit is to log in through them. The agent does that in its own sandbox, with a browser for the setup page and a TOTP implementation for the code, and the pull request carries the test output and the screenshots rather than a description of the bundle.
The record also shows the choices being made: the transcript has the agent reading that the test firewall uses http_basic, checking that the new section leaves those tests alone, and deciding that remember-me stays. A reviewer who wants backup codes or an admin-only requirement says so and the parked sandbox adds it on the same branch.
Frequently asked questions
Why scheb/2fa-bundle?
It is the bundle Symfony's own documentation points to for two-factor authentication, it plugs into the existing form_login firewall as a second step, and it ships a TOTP provider, backup codes and trusted devices, so the follow-ups a reviewer is likely to ask for are configuration rather than new code.
Is two-factor required for every user?
No. It is enabled per user from the profile page, so john_user keeps logging in with a password alone and the fixtures and existing tests still pass. A follow-up can require it for ROLE_ADMIN or for everyone.
What about the remember-me cookie?
It stays. A remembered session still has to pass the second step once, and the bundle's trusted-device option, if a reviewer turns it on, lets a browser skip the code for a period after a successful login.
What if a user loses the authenticator app?
The secret is a single nullable column, so an administrator can clear it and the user logs in with a password and sets it up again. The pull request leaves that as a console command for a follow-up, and the bundle's backup codes are another option.
Do the existing tests still pass?
Yes. The test environment authenticates with http_basic on the same firewall, and the agent checks that the new two_factor section does not intercept those requests before it runs the full suite.