fcode-agent

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).
2. 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.
3. 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.
4. Define input-parameter requirements (fields, types, validations, any dynamic fields needing API calls). See fcode-json-schema.
5. 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?"
6. 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 run_code 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 FACTORIAL_TOKEN, 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 (every form is public), a button inside the Factorial UI (fcode-ui-triggers) or any other Factorial Action entry point (fcode-factorial-actions), 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.
• yc_api_<method> — manage Factorial Code resources (e.g. yc_api_create_process, yc_api_update_process, yc_api_delete_process).
• get_locales / get_locale / save_locale / delete_locale — 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.