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 SideBar Menu 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

If your requirements declare a verify command in the spec delta, verify runs them and reports evidence per requirement. A change is only marked verified when the evidence passes and there are no gaps (use --allow-gaps to accept requirements without a command).

$ agentic-fy verify

[verify] add-dark-mode
All artifacts present (proposal, design, tasks).
All tasks marked as completed.
Evidence: 2/2 requirement(s) proven.
  ✓ dark-mode-toggle    (npm test -- theme)
  ✓ persist-preference  (npm test -- persist)
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.