Formula create

Formula Create - Generate agentfactory Workflow Formulas

Create new formulas from natural language descriptions, following agentfactory conventions.

Usage

/formula-create "description of what the formula should accomplish"
/formula-create .claude/skills/<name>/SKILL.md

Examples

/formula-create "Review a PR for security vulnerabilities and generate a report"
/formula-create "Convert markdown docs to HTML and deploy to S3"
/formula-create .claude/skills/rapid-implement/SKILL.md

Implementation

When invoked with a description, create a formula following these rules:

1. Determine Formula Type

Use step-based workflow (default) when:

• Steps have sequential dependencies (output of one feeds into next)
• Work must happen in order
• Iteration/looping may be needed

Use convoy type only when:

• Multiple agents can work on the SAME input in parallel
• Each leg examines the input from a different perspective
• A synthesis step combines parallel outputs

2. Formula Structure

description = """
One-sentence summary ending with a period.

Remaining paragraphs describe the workflow overview and expected outcomes.
The first sentence (up to the first period) becomes the agent's short description
in agents.json — it MUST be a plain sentence, not a heading or markdown.
"""
formula = "<name>"
version = 1
skills = ["skill-a", "skill-b"]  # Skills invoked by Skill() calls in step descriptions

# Inputs - parameters provided at runtime
[inputs]
[inputs.example_input]
description = "What this input is for"
type = "string"  # string, number, boolean
required = true  # or false with default

[inputs.optional_input]
description = "Optional parameter"
type = "string"
required = false
default = "default-value"

# Steps - sequential workflow with dependencies
[[steps]]
id = "step-id"
title = "Human-readable step title"
description = """
**Entry criteria:** What must be true before this step runs.

**Actions:**
1. First action to take
2. Second action to take
3. Third action to take

**Exit criteria:**
- What must be true when step completes
- Verifiable outcomes
"""

[[steps]]
id = "next-step"
title = "Next step title"
needs = ["step-id"]  # CRITICAL: Enforce sequencing
description = """..."""

# Variables - template substitution
[vars]
[vars.example_var]
description = "Variable description"
required = true

3. Step Design Rules

Every step MUST have:

• id: lowercase-kebab-case identifier
• title: Short human-readable name
• description: Detailed instructions with entry/exit criteria

Sequential steps MUST have:

• needs = ["previous-step-id"] to enforce ordering

Step descriptions should include:

**Entry criteria:** [preconditions]

**Actions:**
1. [specific action]
2. [specific action]
...

**Exit criteria:**
- [verifiable outcome]
- [verifiable outcome]

4. Common Patterns

Quality Gate with Iteration:

[[steps]]
id = "quality-gate"
title = "Assess quality and decide iteration"
needs = ["validation-step"]
description = """
**Entry criteria:** Validation complete.

**Actions:**
1. Run quality checklist
2. Count issues found

3. **Decision logic:**
   - IF all checks pass → proceed to finalize
   - ELSE IF iteration < max_iterations → loop back to review step
   - ELSE → force completion with warnings

**Exit criteria:**
- Quality assessment complete
- Next action determined
"""

Load/Parse Input:

[[steps]]
id = "load-input"
title = "Load and parse input"
description = """
**Entry criteria:** Input source available.

**Actions:**
1. Read input from {{input_path}} or {{input_bead}}
2. Parse and extract structured data
3. Store parsed data in step bead for downstream steps

**Exit criteria:**
- Input fully loaded and parsed
- Structured data available for next steps
"""

Finalize/Commit:

[[steps]]
id = "finalize"
title = "Finalize and commit results"
needs = ["quality-gate"]
description = """
**Entry criteria:** Quality gate passed.

**Actions:**
1. Write final output to {{output_path}}
2. git add && git commit with descriptive message
3. git push to remote
4. Create PR with summary

**Exit criteria:**
- Output committed and pushed
- PR created
"""

5. Convoy Formula Structure (Parallel Execution)

Only use when legs genuinely work in parallel on same input:

formula = "convoy-<name>"
type = "convoy"
version = 1

[prompts]
base = """
Context injected into all legs.
"""

[[legs]]
id = "perspective-1"
title = "First perspective"
focus = "What this leg focuses on"
description = """Instructions for this parallel worker."""

[[legs]]
id = "perspective-2"
title = "Second perspective"
focus = "Different focus area"
description = """Instructions for this parallel worker."""

[synthesis]
title = "Combine results"
description = """Combine all leg outputs into final result."""
depends_on = ["perspective-1", "perspective-2"]

6. Naming Conventions

• Formula name: <descriptive-name> for molecules, convoy-<name> for convoys
• Step IDs: lowercase-kebab-case
• Input names: snake_case
• File: <formula-name>.formula.toml

7. Output Location

Write the formula to:

.agentfactory/store/formulas/<formula-name>.formula.toml

This is the runtime formula directory for the current project. Formulas here are discoverable by af sling and the formula system at runtime.

8. Post-Creation

After creating the formula, inform the user:

Formula created: .agentfactory/store/formulas/<name>.formula.toml

To inspect:
  af formula show <name> --json    # View formula inputs and vars

To use immediately (current workspace):
  af sling --formula <name> --var x=y   # Execute the formula

To embed in agentfactory binary:
  make build && make install             # Rebuild with new formula embedded

To test: Create a sample input and run af sling --formula <name> --var input=path

9. Reference Existing Formulas

Before creating a new formula, examine existing formulas for patterns:

ls .agentfactory/store/formulas/                                  # List available formulas
cat .agentfactory/store/formulas/*.formula.toml                   # View formula patterns

Key reference formulas:

• gherkin-breakdown.formula.toml - Iteration pattern with quality gates
• factoryworker.formula.toml - Standard work execution pattern
• mergepatrol.formula.toml - Patrol/monitoring pattern
• design.formula.toml - Human-in-the-loop review pattern

10. SKILL.md Input Mode

When invoked with a path to a SKILL.md file (instead of a prose description), read and follow the instructions in skillmd-mode.md in this skill directory.

Detection: If the argument is a file path ending in SKILL.md, use this mode.

Anti-Patterns to Avoid

1. Convoy with sequential legs - If legs depend on each other's output, use steps instead
2. Missing needs - Steps without needs may run out of order
3. Vague descriptions - Always include specific actions and exit criteria
4. No iteration mechanism - For review workflows, add a quality gate
5. Hardcoded paths - Use input variables for flexibility
6. Writing outside .agentfactory/store/formulas/ - Formulas must be written to .agentfactory/store/formulas/
7. Claiming completion without verification - Always verify the formula file exists after creation
8. Assuming a proposal file exists - Agents get requirements from beads, which may contain inline text, a file path, or a GitHub issue link. Use source-agnostic language ("requirements" not "proposal")
9. Omitting invariant steps - Every work execution formula MUST include all 10 invariant steps: load-context, branch-setup, validate-contract, preflight-tests, self-review, run-tests, self-verify, cleanup-workspace, prepare-for-review, submit-and-exit. Source the 8 standard steps from factoryworker and the 2 architecture gates (validate-contract, self-verify) from rapid-implement. Skills don't know about agentfactory architecture — that's formula-create's job to inject