The Transformation Modes

Seven of Nexgile Code’s built-in specialist modes exist for one job: modernizing existing code. Translate, Refactor, Test Gen, Doc Gen, Security, API Mod, and Dep Upgrade are focused chat personas — each with a tuned role, detailed built-in playbooks, and the tool permissions its work needs. They live in the mode dropdown alongside every other mode and need no setup.

Be clear about what they are: conversational agent modes you drive task by task. You pick the mode, scope a request, review the diffs, and approve — then scope the next request. There is no batch pipeline that transforms a whole codebase unattended, and that is a feature: modernization done in reviewable increments is modernization you can trust.

Mode	Ask it to
🌐 Translate	Port code between programming languages
🔧 Refactor	Modernize code within the same language
🧪 Test Gen	Generate unit and integration tests for existing code
📝 Doc Gen	Produce READMEs, architecture docs, ADRs, API docs
🛡 Security	Find and fix vulnerabilities, OWASP-style
🌐 API Mod	Modernize service interfaces — SOAP to REST, OpenAPI specs
⬆ Dep Upgrade	Upgrade dependencies and fix the breaking changes

🌐 Translate

What it does. Translates code between languages — Java, C#, Python, JavaScript, TypeScript, Go, Rust, Ruby, PHP, Kotlin, Swift, and more than a dozen others including SQL dialects — while preserving business logic, error handling, data structures, and API contracts. It writes idiomatic target code rather than “Java in Python”, adapts frameworks (Spring Boot → FastAPI, ASP.NET → Express), maps libraries to target-language equivalents (Lombok → dataclasses, Hibernate → SQLAlchemy), translates the tests alongside the production code, and ends with a migration summary of every translated file and key decision.

Example request:

Translate src/billing/InvoiceService.java and its test class to TypeScript
under src/billing/. Target Node 20 + Vitest. Keep the public method
signatures; flag anything that can't map 1:1.

What to expect. Translated files plus a migration summary; anything that could not be translated one-to-one is flagged rather than silently dropped, and the agent verifies the result compiles or runs in the target language.

Review guidance. Run both test suites and diff their results — behavior parity is the contract. Scrutinize the dependency mapping table hardest; a subtly different library semantics (date handling, decimal math) is where ports rot.

🔧 Refactor

What it does. Same-language modernization: replaces deprecated APIs, extracts long methods, breaks up god classes, moves callbacks to async/await, removes dead code, and applies language-specific strategies — records and pattern matching in Java and C#, f-strings, pathlib, and type hints in Python, strict mode and discriminated unions in TypeScript. Its first rule is absolute: never change business logic. Risky refactorings that could change behavior are flagged for human review instead of applied, and each change carries a comment explaining why.

Example request:

Refactor src/legacy/report_builder.py: replace %-formatting with f-strings,
os.path with pathlib, and split build_report (180 lines) into focused
functions. Do not change output format. Run the tests after.

What to expect. Behavior-preserving diffs, verified against compilation and the existing test suite.

Review guidance. The existing tests are your safety net — if coverage is thin, run Test Gen first to pin current behavior, then refactor against those tests.

🧪 Test Gen

What it does. Reads the source, identifies every public method’s contract, edge cases, boundary conditions, and error paths, and generates tests using the project’s existing framework (JUnit 5, xUnit, pytest, Jest, Vitest, Go testing, RSpec, PHPUnit, and others — detected from your dependencies). It targets >80% line coverage (higher for critical paths), names tests test_[method]_[scenario]_[expected], mocks external services but not pure functions, then runs the generated tests, fixes failures, and reports coverage before and after.

Example request:

Generate tests for src/utils/dateRange.ts. Cover boundary values (empty
range, single day, DST transitions) and invalid input. Use the existing
Vitest setup.

Review guidance. Coverage numbers are easy; assertions are what matter. Read the generated assertions and ask: do they encode the intended contract, or just snapshot whatever the code currently does? Fix the intent, keep the scaffolding.

📝 Doc Gen

What it does. Generates documentation from code analysis: README.md, ARCHITECTURE.md with Mermaid diagrams, ADRs, inline comments for complex logic, API documentation (OpenAPI 3.0+ specs with schemas, examples, and error responses), and changelog entries. Its rules require reading the code before writing and verifying every claim against it. Note the permission shape: Doc Gen reads and edits but has no command group — it cannot run anything, which keeps a documentation pass side-effect-free by construction.

Example request:

Generate an ARCHITECTURE.md for this repo: component map, request flow from
route to database, and a Mermaid diagram of the module dependencies.

Review guidance. Check freshness-sensitive claims (setup steps, port numbers, env vars) by actually following them once. For a spec-grade, audited wiki rather than narrative docs, use Spec Bootstrap instead.

🛡 Security

What it does. Scans for vulnerabilities following OWASP guidance: SQL injection, XSS, insecure deserialization, hardcoded secrets, weak cryptography, missing input validation, insecure file operations, missing authentication/authorization, insecure HTTP configuration, and known CVEs in dependencies. Every finding is classified Critical / High / Medium / Low, explained in plain language, mapped to its CWE and OWASP category, and paired with a before/after fix.

The report. A scan ends with two things: a readable Markdown summary — a severity table (critical/high/medium/low counts, files and lines scanned) followed by the Critical and High findings called out by id, file, and line — and a machine-readable json:security-report fenced block carrying the same findings in full, each with its id, severity, category, CWE, file and line, the vulnerable snippet, the remediation, and usually the corrected snippet. The Markdown summary is what you read in chat; the JSON block displays as an ordinary code block and is there for you to copy into a ticket, a spreadsheet, or your own tooling.

Example request:

Security-scan src/routes/ and src/db/. Fix anything Critical or High
directly; report Medium and Low without changing code.

Review guidance. Treat it as a strong first pass, not a penetration test. Verify each applied fix still passes the tests, and never auto-approve edits to auth or token-handling code — approve those diffs by hand.

🌐 API Mod

What it does. Modernizes service interfaces: SOAP-to-REST conversion (WSDL analyzed operation by operation into an OpenAPI 3.0 spec, GetUser → GET /users/{id}), generating OpenAPI/Swagger specs from existing code, retrofitting versioning, pagination, and proper error responses onto aging REST APIs, generating client SDKs, and adding rate limiting and authentication. Modernization is not a rewrite — preserving existing functionality is its first rule, and it verifies endpoints work after the change.

Example request:

Generate an OpenAPI 3.0 spec (YAML) for the Express routes in src/api/,
including request/response schemas and error envelopes. Don't change the
routes themselves yet.

Review guidance. Diff the generated contract against real traffic or existing integration tests before changing implementations — a spec that mis-describes today’s API will mislead every client generated from it. Watch for silent compatibility breaks (renamed fields, changed status codes).

⬆ Dep Upgrade

What it does. Scans every dependency manifest (package.json, pom.xml, requirements.txt, Cargo.toml, go.mod, Gemfile, composer.json, …), identifies outdated packages and known CVEs, then upgrades one dependency at a time, security-critical first: read the changelog and migration guide, bump the version, fix the breaking changes in your code, run the tests, move on. Major upgrades with extensive breakage are flagged for human review, each upgrade keeps a rollback plan, and the run ends with an upgrade report.

Example request:

Upgrade express and jsonwebtoken to latest. One at a time, tests between
each. If a major bump needs API changes in more than 5 files, stop and
show me the plan first.

Review guidance. Per the Human-in-the-Loop Playbook, major version bumps belong on the never-auto-approve list — cascading breakage is the classic failure mode. Approve lockfile and manifest diffs deliberately.

Working safely at modernization scale

• Checkpoints on, always. Every agent edit lands in the checkpoint shadow repository, so any transformation step is one click to undo.
• Small scopes, many tasks. “Translate this module”, not “translate the repo”. Each task stays reviewable, and a bad step costs one checkpoint restore, not an afternoon.
• Branch first. Do large transformations on a feature branch — or a separate worktree so your main checkout stays untouched.
• Independent verification. After a big Translate or Refactor pass, switch to 🔬 Tester and ask it to verify the change against the original requirement — it builds its own test plan and reports a structured verdict.
• Combine with Workflow Mode. Workflow Mode auto-routes Code and Debug tasks through the implement → test → review → ship chain. Transformation modes run directly, so use both: specialist modes for the transformation itself, and Workflow Mode for the follow-up integration changes you make in Code mode.

Related

• Specialist Modes
• Workflow Mode
• Checkpoints
• Human-in-the-Loop Playbook