What are Formulas?

Formulas are the essential building blocks that enable modular reuse of AI coding specs and tools.
By organizing your rules, slash commands, subagents and more into sets of formulas, reuse and sync across projects and AI coding platforms become super simple and straightforward.

Structure of a formula

A formula can contain the following files:

The formula.yml file
AGENTS.md, platform root files
Rules
Slash commands
Subagent configs
AI files (for general uncategorized markdown files)

Formulas are stored to the local registry using the following directory structure:

Structure

formula
├── formula.yml
├── AGENTS.md # Platform root file
├── rules/
│   └── # Rule files
├── commands/
│   └── # Command files (slash commands)
├── agents/
│   └── # Agent files (subagents)
└── ai/
    └── # AI files (Other .md files)

Formulas are stored locally in ~/.groundzero on your local machine.

The formula.yml file

A formula.yml file contains metadata and configurations for a formula.

formula.yml

name: <formula-name>
description: <formula-description>
keywords: [keyword1, keyword2]
version: 0.1.0
formulas:
  - name: <some-formula>
    version: ^0.1.2
dev-formulas:
  - name: <some-dev-formula>
    version: ^0.1.2

Most fields are auto managed by the CLI, but you are free to edit the contents of a formula.yml file as required. See the save, install, and uninstall commands for more details on how fields are updated by the CLI.

The GroundZero formula.yml file is structurally and functionally similar to popular package manager files, such as npm's package.json, poetry's pyproject.toml, etc.

The index.yml files

The GroundZero CLI uses index.yml files to specify/detect which directories belong to which formula. You can manually add index.yml files to directories or use the tag command.

index.yml

# GroundZero formula
formula:
  name: <formula-name> # Name of formula it belongs to

Markdown (.md) files and formulas

The GroundZero CLI can also use yaml frontmatter to specify/detect which markdown files belong to which formula. You can manually add the frontmatter to your md files or use the tag command.

some-file.md

---
# GroundZero formula
formula:
  name: <formula-name> # Name of formula it belongs to
---

// Markdown content

You can also mark a platform file as platform specific, which will tell the CLI to keep this file only for this platform and not sync it across all detected platforms.

.cursor/rules/some-rule.md

---
# GroundZero formula
formula:
  name: <formula-name>
  platformSpecific: true # This file will only appear in .cursor
---

// Markdown content

Formulas in codebases

When a formula is installed to a codebase, the CLI tool automatically copies the files from the formula to your codebase into their respective locations, synced across existing supported AI coding platforms. Refer to the install and uninstall commands for more details.

Formula "essentials"

essentials
├── formula.yml
├── rules
│   └── essentials
│       └── clean-code.md
├── commands
│   └── essentials
│       └── clean-files.md
└── ai
    └── guidelines
        ├── dry.md
        └── modular.md