Getting Started

Installation

agentic-fy is a Node.js CLI. You need version 20.19.0 or newer. Check your Node:

node --version

Install the CLI globally:

npm install -g @agentic-fy/agentic-fy

If you can't install globally (permission error under /usr/local), run it directly without installing:

npx @agentic-fy/agentic-fy --version

Verify it worked

agentic-fy --version

If it prints the logo and a version number, the CLI is on your PATH.

Your first five minutes

The whole loop:

$ npm install -g @agentic-fy/agentic-fy
$ cd your-project && agentic-fy init
$ agentic-fy explore                    (optional: think it through first)
$ agentic-fy propose add-dark-mode      (drafts the plan; you review it)
$ agentic-fy apply                      (tracks the tasks)
$ agentic-fy verify                     (checks it's ready)
$ agentic-fy archive                    (change archived)

What agentic-fy creates

After running agentic-fy init, your project gets this structure:

agentic-fy.config.yaml  # project configuration
agentic-fy/
├── specs/              # project specs
├── changes/            # proposed changes (one folder per change)
│   └── archive/        # completed changes

The init command creates the base structure idempotently (running it again does not overwrite the existing agentic-fy.config.yaml) and configures the MCP integration for the AI tools you select. Pass --tools kiro,cursor to skip the prompt, or --tools none for just the base structure.

When you create a change with propose, it looks like this:

agentic-fy/changes/<change-name>/
├── proposal.md
├── design.md
├── tasks.md
├── specs/
│   └── <change-name>.delta.yaml
└── .agentic-fy.yaml    # metadata (name, status, dates)

Understanding the artifacts

Artifact	Purpose
proposal.md	The "why" and "what" — intent, scope, and approach
specs/<capability>.delta.yaml	Spec delta: how the requirements change (merged into the project specs on archive)
design.md	The "how" — technical approach and architecture decisions
tasks.md	Implementation checklist with checkboxes

Example: your first change

Let's add dark mode to an application.

1. Initialize the project

cd your-project
agentic-fy init

2. Create the change

$ agentic-fy propose add-dark-mode

[propose] add-dark-mode
Created: proposal.md
Created: design.md
Created: tasks.md
Created: specs/add-dark-mode.delta.yaml

3. Fill in the artifacts

Edit the files in agentic-fy/changes/add-dark-mode/. Write the real tasks in tasks.md and describe the requirement changes in the spec delta:

# Tasks — add-dark-mode

- [ ] 1. Create ThemeContext with light/dark state
- [ ] 2. Add a theme toggle to settings
- [ ] 3. Persist the preference in localStorage

4. Track the implementation

$ agentic-fy apply

[apply] add-dark-mode
Applying change "add-dark-mode".
Tasks: 0 completed, 3 pending.
  [ ] 1. Create ThemeContext with light/dark state
  [ ] 2. Add a theme toggle to settings
  [ ] 3. Persist the preference in localStorage

Implement the tasks and mark them as [x] in tasks.md as you go.

5. Verify

$ agentic-fy verify

[verify] add-dark-mode
All artifacts present (proposal, design, tasks).
All tasks marked as completed.
Status updated to "verified".

6. Archive

Archiving merges the change's spec delta into the project's consolidated specs, then moves the change to history. Preview the merge first with agentic-fy archive --dry-run.

$ agentic-fy archive

[archive] add-dark-mode
Spec "dark-mode" created: +1 ~0 -0
Change "add-dark-mode" archived at agentic-fy/changes/archive/add-dark-mode.

Letting the AI drive (MCP)

The commands above run in the terminal. To let your AI assistant drive the workflow, connect the MCP server:

agentic-fy mcp

It exposes the explore, propose, apply, verify, merge, archive, list, show, validate, status, and context tools to any MCP-compatible agent. See the Commands page for setup in editors like Kiro.