Understand it deeply

Concepts

The ideas behind agentic-fy, from the change to archiving.

The problem agentic-fy solves

When you work with an AI assistant, it's easy to ask for something vague and watch the AI confidently build the wrong thing. agentic-fy inserts a lightweight agreement layer: you and the AI write and review a short plan before any code is written. The plan lives in the repository, next to the code, so it stays useful months later.

Change

A change is the central unit of work. Whenever you want to add, modify, or remove behavior, you create a change with agentic-fy propose <name>. Each change is a folder in agentic-fy/changes/<name>/ that gathers everything about that work:

agentic-fy/changes/add-dark-mode/
├── proposal.md              # why and what
├── design.md                # how
├── tasks.md                 # steps
├── specs/
│   └── add-dark-mode.delta.yaml   # spec delta: how this change alters a capability
└── .agentic-fy.yaml         # metadata: name, status, dates

The name you pass is normalized to a disk-safe slug: "Add Dark Mode" becomes add-dark-mode.

Artifacts

Each change contains four kinds of artifact, created in a natural order where each one feeds the next:

Artifact	Question it answers
`proposal.md`	Why do this, and what changes?
`specs/<capability>.delta.yaml`	How do the requirements of a capability change?
`design.md`	How will it be built?
`tasks.md`	What are the concrete implementation steps?

proposal ──► specs ──► design ──► tasks ──► implement
    why        what      how       steps      do it

The propose command generates these files from templates. From there, you (or the AI) fill them in with the real content. tasks.md uses Markdown checkboxes (- [ ] / - [x]), which agentic-fy understands to track progress.

Spec deltas

A change does not rewrite whole specs. It carries a spec delta per capability at specs/<capability>.delta.yaml — a structured description of what the change adds, modifies, or removes. Requirements are referenced by a stable id, so renaming a requirement is just changing its title, and references never break.

capability: data-export
purpose: Lets users take their data out in a portable format.   # only for a new capability
operations:
  - op: add
    id: user-can-export-data
    title: User can export data
    statement: The system SHALL let users export their data as CSV.
    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
    reason: Replaced by the new export

The structure is validated by a schema: a malformed delta fails loudly (never silently), and modify is a partial patch — you never recopy a whole requirement or drop a scenario by accident.

Enablers, not gates

The order of the artifacts shows what becomes possible next, not what you're forced to do. Discover during implementation that the design was wrong? Edit design.md and keep going. Nothing locks. The dependencies exist only to give context — not to box you into a waterfall process.

Status and lifecycle

Each change carries a status in its .agentic-fy.yaml, which moves through the workflow:

exploring ──► proposed ──► applying ──► verified ──► archived

exploring — initial state of a newly created change.
proposed — after propose, with the artifacts drafted.
applying — after apply, while you implement the tasks.
verified — after verify passes (artifacts present and tasks done).
archived — after archive, with the change moved to history.

Archiving and consolidated specs

When the work is done, agentic-fy archive does two things. First it merges the change's spec deltas into the project's consolidated specs at agentic-fy/specs/<capability>.md — a living, readable description of what the system does now (not a diary of changes). Then it moves the change folder to agentic-fy/changes/archive/<name>/ and marks the status as archived.

The merge is deterministic and idempotent, and it fails loudly if a delta references a requirement that doesn't exist. Preview it without writing anything using agentic-fy archive --dry-run.

You don't have to wait for archive. agentic-fy merge runs the same merge but keeps the change active — an "early-sync" that keeps the consolidated specs (and the context an AI agent reads) current while the change is still in progress.

changes/<name>/specs/<cap>.delta.yaml  ──►  merge  ──►  specs/<cap>.md
        (how it changes)                                  (what it is now)

The model: CLI + agent

An important, honest point: agentic-fy does not contain an AI model. It makes no calls to any LLM provider. The CLI is the tool that creates and tracks the artifacts and status; the intelligence that reads the design, writes the code, and checks off tasks comes from the AI agent that uses the tool.

There are two ways to use it:

Manual (terminal). You run the commands, edit the artifacts by hand, and implement the code yourself.
Assisted (MCP). You start agentic-fy mcp and connect an MCP-compatible AI assistant (like Kiro). The agent then uses the tools and drives the flow, writing the code and checking off tasks.

Project config

The agentic-fy.config.yaml, created by init, holds the base configuration:

version: 1
schema: spec-driven
workflow:
  - explore
  - propose
  - apply
  - verify
  - archive

It is read to resolve the project root (agentic-fy walks up the directory tree looking for this file) and to know the active workflow.

Getting Started → Commands →