agentic-fy logo
Reference

Commands

Every agentic-fy CLI command. They all run in your terminal.

Global flags:

Most commands (except init and mcp) require an already-initialized project — an agentic-fy.config.yaml in the current directory or a directory above it.

init

agentic-fy init [path] [--tools <list>]

Creates the base project structure in path (default: current directory):

agentic-fy.config.yaml
agentic-fy/
├── specs/              (with .gitkeep)
├── changes/
│   └── archive/        (with .gitkeep)

Idempotent: running it again ensures the directories exist and does not overwrite the agentic-fy.config.yaml. It also configures the MCP integration for your AI tools.

Use --tools to skip the interactive prompt: --tools all, --tools none, or a comma-separated list such as --tools kiro,cursor. The mcp.json merge is non-destructive: an existing config keeps its other servers.

explore

agentic-fy explore

Thinking mode. Confirms an agentic-fy project exists and lists the active changes with their status. It doesn't create or change anything — it's a starting point to map the problem before proposing.

propose

agentic-fy propose <name>

Creates a change and drafts the artifacts from templates: proposal.md, design.md, tasks.md, and a spec delta at specs/<name>.delta.yaml. The <name> is normalized to a slug (e.g., "add login" becomes add-login). It does not overwrite existing files. At the end, it marks the change status as proposed.

apply

agentic-fy apply [name]

Reads the change's tasks.md, parses the checkboxes, and reports how many tasks are done and pending, listing the pending ones. Marks the status as applying. If name is omitted and there is exactly one active change, it is used; if there are several, the command asks you to specify the name.

verify

agentic-fy verify [name] [--allow-gaps]

Checks that the artifacts (proposal, design, tasks) exist and that all tasks are checked — and then collects evidence. Each requirement can declare a verify command in its spec delta; verify runs those commands (exit 0 = proven) and reports per requirement:

Evidence: 2/3 requirement(s) proven.
  ✓ dark-mode-toggle   (npm test -- theme)
  ✗ persist-preference FAILED: npm test -- persist — exit 1
  ✗ os-default-theme   NO EVIDENCE — no verify command

The change is only marked verified when nothing fails and there are no gaps. A requirement with no command is an honest gap, not a pass — there is no self-declared "manual" evidence. Use --allow-gaps to accept requirements that declare no command.

merge

agentic-fy merge [name] [--dry-run]

Applies the change's spec deltas (specs/*.delta.yaml) into the project's consolidated specs at agentic-fy/specs/<capability>.md, keeping the change active (no archive). This "early-sync" keeps the specs — and the context an AI agent reads — current while the change is still in progress. It uses the same idempotent, fail-loud merge engine as archive. Use --dry-run to preview without writing.

archive

agentic-fy archive [name] [--dry-run]

Merges the change's spec deltas (specs/*.delta.yaml) into the project's consolidated specs at agentic-fy/specs/<capability>.md, then moves the change to agentic-fy/changes/archive/<name>/ and marks the status as archived. The merge is deterministic and idempotent, and fails loudly if a delta references a requirement that doesn't exist. Use --dry-run to preview the merge without writing or archiving.

list

agentic-fy list [--specs] [--long] [--json]

Lists the active changes. Use --specs to list the project specs instead, --long to include the title and task progress, and --json for machine-readable output.

show

agentic-fy show <name> [--artifact <id>] [--spec <id>] [--json]

Shows a change summary (status, title, artifacts, tasks). Use --artifact proposal|design|tasks to print a raw artifact, or --spec <id> to print a project spec. Suggests close names ("did you mean?") when the name doesn't match.

validate

agentic-fy validate [name] [--all] [--strict] [--json]

Validates a change's artifacts: missing artifact, untouched template, empty body, and tasks.md without a real checkbox. It also validates each spec delta (specs/*.delta.yaml): malformed YAML or an invalid structure is a hard error, an untouched delta template is a warning. Use --all to validate every active change and --strict to treat warnings as failures.

status

agentic-fy status [--json]

Overview of the active changes by stage, with task progress and any validation issues.

doctor

agentic-fy doctor [--json]

Checks project integrity: valid config, intact change metadata, orphaned directories, and consistent artifacts. Read-only — it does not repair anything.

context

agentic-fy context [--json]

Gathers the project context (config, active changes, and specs) into a single brief for the agent.

config

agentic-fy config show [--json]
agentic-fy config set <key> <value>

Reads and edits agentic-fy.config.yaml. Editable keys: version and schema. Every write is validated against the schema before saving.

completion

agentic-fy completion [shell]

Prints an autocompletion script for powershell, bash, or zsh. It does not install anything automatically — pipe it into your shell config as you prefer.

view

agentic-fy view [--static] [--json]

A dashboard of specs and changes, with a summary (Changes · Merged · Specs · Tasks · Evidence) and progress bars for tasks and evidence coverage. In an interactive terminal it opens a number-navigable view; --static prints the panel and exits, and --json returns the raw data.

mcp

agentic-fy mcp

Starts the MCP (Model Context Protocol) server over stdio, exposing the workflow commands as tools an AI agent can consume. Registered tools: explore, propose, apply, verify, merge, archive, list, show, validate, status, and context.

Connect to Kiro

The easiest way is to let agentic-fy init --tools kiro configure it for you. To do it manually, create (or edit) Kiro's MCP configuration file:

{
  "mcpServers": {
    "agentic-fy": {
      "command": "npx",
      "args": ["-y", "@agentic-fy/agentic-fy", "mcp"],
      "disabled": false,
      "autoApprove": ["explore", "list", "show", "validate"]
    }
  }
}

If agentic-fy is installed globally, you can use the binary directly:

{
  "mcpServers": {
    "agentic-fy": {
      "command": "agentic-fy",
      "args": ["mcp"],
      "disabled": false,
      "autoApprove": ["explore", "list", "show", "validate"]
    }
  }
}

autoApprove lets the read-only tools run without confirmation; the ones that write (propose, apply, archive) still ask for approval.

Connect to other editors

VS Code-based editors with MCP support use the same format, changing the file:

Getting Started → Concepts →