Factorial Code — agent workflow

How to build Factorial Code processes and modules through an iterative, confirmation-driven approach, using the Factorial Code MCP tools. Pair this with fcode-core-concepts, fcode-javascript/fcode-python, and fcode-cli.

Core principles

• Explain before acting — describe what you'll do and why.
• Confirm before changing — get explicit approval before significant or

destructive changes (refactors, dependency changes, variable changes).

• Iterate in small steps — deliver working increments, validate, then expand.
• Be safe by default — never hardcode or log secrets.

Workflow

Phase 1 — Plan & confirm

Before writing code or using any tool, produce a short plan and confirm it.

1. Analyze current context. Check the process language (index.js → JS,

main.py → Python; new code must match), what the current script does, which variables/dependencies/modules already exist (don't remove or overwrite them).

1. Identify alternatives. For common needs (email, SMS, payments, storage),

present options — third-party service vs direct protocol, library choices — with brief trade-offs, and ask the user to choose. Don't assume an approach when alternatives exist.

1. Identify needed components: config variables, secrets (the user must

create these), input parameters (+ types), dependencies (verify they exist, prefer recent stable versions), and modules worth creating for reuse.

1. Define input-parameter requirements (fields, types, validations, any

dynamic fields needing API calls). See fcode-json-schema.

1. Present the plan (what you'll build, variables you'll create vs the user

must create, input parameters, dependencies, reusable modules, expected behavior) and ask "Shall I proceed?"

1. Wait for explicit confirmation before proceeding.

Phase 2 — Iterative development

Work in small steps, confirming at each one.

• Iteration 1 (setup & discovery): create config variables and ask the user

to create the sensitive ones; if useful, write a discovery script and run it with runcode to validate connectivity and learn the API/data shapes. Share results. - When a secret value is needed for discovery/testing, ask the user for it — or, if they prefer not to share it, ask them to put it in variables.local.env themselves. For FACTORIALTOKEN, follow the OAuth procedure in fcode-cli. - Remind the user that local secret values aren't pushed — they must create those variables manually in the remote demo environment (except FACTORIAL_TOKEN, which is auto-populated remotely).

• Iteration 2+: for each step — explain it, get confirmation, implement

following the language code rules (validation, error handling, logging), validate pieces with run_code, then create/update the process (code, parameters, descriptions). Tell the user what changed and let them review before the next iteration.

Phase 3 — Test & refine (via the CLI)

Propose a full execution test using the fcode CLI (see fcode-cli), get confirmation, run it with test parameters, review results together, and iterate. Then offer next steps: scheduling, webhooks (public, inheriting the workspace webhookAuth configuration, or with their own header and team variable), a form (public, or restricted to Factorial users), a button inside the Factorial UI (fcode-ui-triggers), or exposing the process as an MCP tool — and pushing to cloud when ready. Pushing never affects consumers pinned to the stable alias (model in fcode-core-concepts); don't create workspace versions or move stable unless explicitly asked.

Creating MCP tools

Do not write standalone MCP server code. Any Factorial Code process becomes an MCP tool: (1) create a process implementing the logic, (2) define its input parameters via parametersSchema.json (they become the tool's parameters), (3) tag the process (e.g. mcp-tool). It's then automatically available in any MCP client connected to the Factorial Code MCP Server — tag and go.

Available MCP tools

• run_code — execute JS/Python for validation and testing before updating

process files.

• ycapi<method> — manage Factorial Code resources (e.g.

ycapicreateprocess, ycapiupdateprocess, ycapidelete_process).

• getlocales / getlocale / savelocale / deletelocale — manage

workspace translation files. save_locale replaces the whole file, so read-modify-write when adding keys; model in fcode-i18n.

• Use other Factorial Code MCP tools when needed.

Code quality & security

• Try/catch (try/except) with meaningful messages; validate all inputs

(external ones included) at the start; log key steps; extract reusable logic into modules; clean up resources.

• See the module-naming and variables.env gotchas in fcode-core-concepts.

Error handling

Explain what went wrong, propose a fix, and get confirmation — don't silently retry or trial-and-error. Ask the user instead of guessing on: ambiguous requirements, missing info (credentials, endpoints, package names), repeated failures, architecture or trade-off decisions, security concerns, or an unclear root cause.

Example

For a full worked example of this workflow (a Shopify → email integration), read references/example-interaction.md.