fcode-agent

---
name: fcode-agent
description: Iterative, confirmation-driven workflow for building Factorial Code processes and modules end to end — plan-and-confirm, discovery scripts, incremental implementation validated with the run_code MCP tool, exposing processes as MCP tools, plus security and error-handling practices. Use when asked to build, automate, or integrate something on Factorial Code (fcode) and you need the recommended working method.
license: MIT
metadata:
  category: factorial-code
---

# 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
(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.
- **`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`.