Agentic-Fy

A performant, lean TypeScript CLI for spec-driven workflows, with MCP support.

agentic-fy structures the spec-driven development cycle — from draft to archive — and exposes that flow both in the terminal and as an MCP server, so an AI agent can drive the work inside your IDE.

Why agentic-fy

• Lean. Few dependencies, no ceremony. Easy to understand and extend.

• MCP-first. Integrates with your editor via the Model Context Protocol, and also generates slash commands / skills for the tools that read them.

• Spec-driven. Every change starts from clear artifacts: proposal, design, tasks, and a structured spec delta.

• Verifiable. Requirements can carry a command that proves them — verify runs it, so a change is only done when there is executable evidence, not just a checked box.

Related MCP server: SkyDeckAI Code

Requirements

• Node.js >= 20.19.0

Installation

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

Or run without installing:

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

Quick start

cd your-project
agentic-fy init                    # creates the structure and integrates your IDE (MCP)
agentic-fy explore                 # (optional) think before coding
agentic-fy propose "dark mode"     # drafts proposal, design, tasks, and a spec delta
agentic-fy apply                   # tracks the tasks
agentic-fy verify                  # runs evidence; loops until everything is proven
agentic-fy archive                 # merges the spec deltas and archives the change

What init creates

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

init is idempotent and also configures the editor integration. In the terminal it opens an interactive multi-select (arrows + space); to skip the prompt use --tools:

agentic-fy init --tools claude,cursor   # configures the chosen tools
agentic-fy init --tools all             # all supported tools
agentic-fy init --tools none            # only the base structure

The config merge is non-destructive and idempotent: an existing mcp.json keeps its other servers; agentic-fy only adds (or updates) its own entry.

Supported tools

init configures the MCP server and generates slash commands / skills for:

Any other MCP-compatible client can connect manually to agentic-fy mcp.

Commands

Full reference in docs/commands.html.

The artifacts of a change

When you run propose, the change gets:

Spec deltas (YAML)

A change doesn't rewrite whole specs — it describes how it changes a capability, referencing requirements by a stable id:

capability: data-export
operations:
  - op: add
    id: user-can-export-data
    title: User can export data
    statement: The system SHALL let users export their data as CSV.
    verify: npm test -- export     # optional: a command that proves this requirement
    scenarios:
      - when: the user clicks Export
        then: a CSV file is downloaded
  - op: modify
    id: user-can-export-data
    set:
      statement: The system SHALL let users export as CSV or JSON.
    addScenarios:
      - when: the user selects JSON
        then: a JSON file is downloaded
  - op: remove
    id: legacy-export

The structure is validated by a schema (malformed deltas fail loudly, never silently). On archive (or merge), the deltas are applied into the consolidated spec at agentic-fy/specs/<capability>.md.

Evidence and the convergence loop

If a requirement declares a verify command, agentic-fy verify runs it (exit 0 = proven). The change is only marked verified when every requirement is proven and there are no gaps. Otherwise it enters a converging state and verify reports an actionable plan:

Evidence: 1/2 requirement(s) proven.
  ✓ user-can-export-data  (npm test -- export)
  ✗ export-is-async  FAILED: npm test -- async — exit 1  → fix the implementation, then run verify again

Converging — not ready yet: 1 failed evidence.

Evidence is command-only by design: a requirement with no command is an honest, visible gap (use --allow-gaps to accept it) — never a self-declared pass.

Letting the AI drive (MCP)

If you chose a tool during init, your editor's MCP config has already been written — just reload the editor. To start the server manually:

agentic-fy mcp

It exposes the explore, propose, apply, verify, merge, archive, list, show, validate, status, context, doctor, and config tools to any MCP-compatible agent. Per-editor setup in docs/commands.html.

Language

agentic-fy is written in TypeScript (ESM, Node >= 20.19) and ships compiled JavaScript in dist/. Runtime dependencies are kept minimal: @modelcontextprotocol/sdk, commander, chalk, yaml, and zod. There is no bundled AI model — the CLI creates and tracks the artifacts; the intelligence comes from the AI agent that drives it via MCP.

Development

npm install
npm run build       # compiles TypeScript to dist/
npm run dev         # tsc in watch mode
npm test            # runs the suite (vitest)
node bin/agentic-fy.js --version

Contributing

Contributions are welcome. Please open an issue to discuss significant changes first. When sending a pull request, fill in the PR template so reviewers can understand the change quickly:

• Keep PRs focused and small where possible.

• Run npm run build and npm test before submitting.

• Add a CHANGELOG entry for user-facing changes.

Documentation

• Getting started

• Concepts

• Commands

• Changelog

License

MIT — see LICENSE.