AgenticFlowX — Low-barrier spec-driven AI coding

—

Pause. Think. Plan. Ship.

A capable model is non-deterministic: run the same prompt twice and you can get two different architectures. A spec doesn't slow that down — it fixes what "right" means, so each run executes toward a target instead of inventing one.

Without a spec, one prompt produces three different designs across runs; with a spec, every run converges on the design you approved

—

Tried this before? You've hit these.

Real frustrations from people doing spec-driven work today — and how AFX answers each one.

trusting the agent

It swears the build is green — then the first click in the actual app goes nowhere.

Nothing ships on the model's word. Verify checks the evidence per task; the Work Sessions log needs the agent's tick and your human one.

after the review

A year on, the spec still tells me what we decided — but not why, and not what we ruled out to get there.

The reasoning survives, not just the outcome. The journal keeps decisions and the verbatim prompt that changed a spec; ADRs record the roads not taken.

in code review

The spec and the code quietly diverge, and it only surfaces at PR review — if someone happens to look.

Fail the build, not the reviewer. /afx-check trace runs headless; a broken @see link surfaces as a ghost reference instead of rotting silently.

mid-session

The plan was hands-off. In practice I hover over every step so the agent doesn't drift or grind to a halt.

Guardrails, not vibes. Explore mode is read-only, enforced host-side; gates stop work advancing past an unapproved spec.

coming from vibe-coding

Next to the rush of just vibing, all this structure feels like homework.

Start loose. Chat first, add structure only when the work earns it — and watch the Quality Pulse climb as the spec tightens.

evaluating tools

There are a dozen spec tools now — which one is even worth learning?

One that's both. A VS Code extension and standard skills any agent runs — your models, your repo, Apache-2.0. No new editor, no lock-in.

—

Two guides and a reference.

The whole system, written for a first-timer and kept honest with real screenshots. Skim one before the tour below, or bookmark them for when you start.

Guide · the workflow

The SDD guide

Dash, Sprint, or the full spec — which to pick, the whole click-through journey, the previewer up close, and every command with its button. The struggle-ender.

Open the SDD guide → Reference · the notation

Document anatomy

Every section of a spec, design, and tasks file — the node-ID system, what's required vs flexible, how the stepper and previewer read it, and where the notation came from. The meat, in full.

Open the reference → Guide · setup

Help & setup

Install, connect any model — Anthropic, DeepSeek, Ollama, llama.cpp and more — configure skills, and go headless. Copy-paste recipes for every provider.

Open help & setup →

01

Chat that stays fast.

Pick how each message is treated with the intent selector — Default sends exactly what you type. Zero injection, zero extra tokens.

AFX chat with Start-here actions and quick commands

Three ways in

Chat about the repo, open the workflow surfaces, or start traceable planning — the panel offers all three without forcing any.

Intents: Default · Ask · Architect · Code
Start here: plan a feature, ask about the repo, start a sprint
Composer: @-mentions, active-file context, model picker, memory toggle
Slash autocomplete: type / for a filterable command dropdown
Keyboard-first: Ctrl+Alt+A chat · Ctrl+Shift+M mode · Ctrl+Alt+M intent
History: sessions persist — search and reopen any transcript
Images: attach screenshots when the selected model supports image input; text-only models explain why the action is unavailable
Capability-aware: thinking levels (off → max), live usage counters, and warnings follow what Pi reports for the chosen model — no assuming every provider behaves the same

AFX Explore mode: read-only repo investigation

Explore, read-only

Investigate a repo without touching a line — not a polite request, a runtime guardrail: write, patch, and mutating shell tools are blocked host-side.

Modes: Code · Explore · Spec
PRD intent: Explore adds a PRD slot for product thinking
Explore: answers stay grounded in the workspace

The SDD guide inside chat walking through the workflow

The workflow, guided

Spec mode walks serious work through the chain — the guide shows where you are and what's next, inside chat.

Chain: spec → design → tasks → journal
Opt-in: reach for it only when work needs traceability

The spec stepper in chat tracking document progress

The stepper keeps you honest

Each document step is visible — what's drafted, what's approved, what's next. Context survives between turns.

Steps: tracked per document, per feature
Preview preserved while you keep chatting

The History tab: searchable session list with reopenable transcripts

Nothing gets lost

Every conversation is kept — searchable, reopenable, safe across window reloads. It keeps transcript and trace events per session.

Search across all past sessions
Reopen a transcript and continue where you stopped
Rename & export a session; copy any single message to the clipboard
Cancel a retry mid-flight — stop a regenerating turn without losing the thread
Handoff: /afx-context save bundles state for the next agent

Skills settings: the bundled AFX core plus externally discovered standard skills, with source paths and trust controls

Bring your own skills

Not just AFX anymore — the extension discovers any standard skills Pi supports and loads them alongside the bundled core. Your team's skills, your personal ones, other packs.

Bundled: the AFX core ships inside the extension at resources/skills/agenticflowx
Global: Pi scans ~/.pi/agent/skills (or $PI_CODING_AGENT_DIR/skills) and ~/.agents/skills
Workspace: project skills load from .pi/skills/ and .agents/skills/ after project trust
Custom: add more folders with afx.skills.extraPaths — including ~/.claude/skills or ~/.codex/skills
Cheap by design: progressive disclosure — only names + descriptions sit in context; the full skill loads on demand
Where from: every skill shows its source path and scope in Settings
Trust: workspace skills and Pi project resources are opt-in per project

/afx-spec/afx-design/afx-task/afx-sprint/afx-check/afx-next/afx-session/afx-context/afx-adr/afx-research

02

Documents that grade themselves.

The AFX Previewer puts workflow actions on top of your repo's markdown — and Quality Pulse reviews the document as you write it: strategy, structure, clarity, completeness. The Refinement Coach suggests the fix.

A living spec

A real spec from the AFX repo — status, owner, and version pills from frontmatter, document actions on the page.

Actions: Refine · Author · Validate · Review
Quality Pulse: grades every section live
Coach: "Success metrics missing → add measurable outcomes"
Journal nudges: capture decisions as you go

Design, anchored

Every heading carries a [DES-…] anchor that code links back to. The outline tracks the whole document.

Anchors: [DES-ARCH], [DES-API], [DES-UI]…
@see links resolve across specs and code

A task list in the AFX Previewer with runnable tasks

Tasks you can run

The task list isn't a description of work — selecting a task can send it to chat and start the implementation.

Run: start coding the selected task
Progress tracked in the document itself

A single-document sprint in the AFX Previewer: spec, design and tasks in one file

Sprint — one file, whole feature

The middle step between a quick fix and a full spec: spec, design, and tasks in a single document with per-section approval — graduates to four files when scope grows.

Command: /afx-sprint new · spec · design · task · code · verify
Graduate: promotes to the four-file workflow intact

An Architecture Decision Record rendered in the AFX Previewer

ADRs, first-class

Architecture decisions live in docs/adr/ with their own lifecycle — create, review, list, supersede.

Command: /afx-adr create · review · supersede
Promote: a journal discussion can become an ADR

A research document rendered in the AFX Previewer

Research, captured

Explorations and comparisons live next to the spec they inform — and can be promoted into ADRs or spec sections when a decision lands.

Command: /afx-research discover · compare · promote

Journals, notes, and generic markdown render here too — any AFX-managed file in the repo.

03

The workflow, made visible.

SDD Studio shows where every feature stands in the chain — what's living, what's blocked, and the next best step. Powered by the same AFX workflow that runs headless: four files per feature, in your repo.

spec.md

The WHAT

Requirements with stable [FR-X] anchors.

design.md

The HOW

Architecture with [DES-…] anchors per section.

tasks.md

The WHEN

Atomic checklist — then implement.

journal.md

The MEMORY

Append-only decisions; any session resumes.

Not every change deserves four files. /afx-dash gives a surgical fix just a purpose and tasks; /afx-sprint carries spec, design, and tasks in one document with per-section approval — and both graduate upward when scope grows. The full SDD guide →

When a conversation changes a spec, /afx-session capture stores the verbatim prompt that triggered it — so future sessions know why, not just what. And before any large multi-file write, a persistence checkpoint asks for your confirmation first.

SDD Studio overview: feature progress across spec, design, tasks and sessions

SDD Studio in Overview — SPEC · DESIGN · TASKS · SESSIONS columns per feature, with Focus-doc and Compare-docs modes and inline actions like Refine spec and Code all.

04

Code that can prove itself.

This is the loop nobody else closes. Every function carries an @see link back to the requirement that justified it — and VS Code understands those links. Ask any codebase: which requirements still have nothing behind them? AFX can answer.

The editor with @see CodeLens links and an inline hover preview of the linked requirement

The editor knows the spec

Hover an anchor and the linked requirement previews inline — no context switch. Rename a file or retire an ID and the now-broken link shows up as a ghost reference you can catch in review.

CodeLens: "Open spec" / "Open design" above the function
Go-to: jump to [FR-1], [DES-API], or task [2.1]
Autocomplete: @see targets complete as you type
Right-click: Send Selection · Insert into Composer · Save to Notes · Explain
Audit: /afx-check trace runs headless too — CI-friendly
Measured: Analytics counts coverage, orphans, and ghosts

05

Bring the access you already have.

The Pi harness talks to 33 providers from one picker — switchable mid-conversation. No vendor billing: your keys, your sign-ins, your local runtimes.

Subscription sign-in

Use your existing plan

Anthropic, GitHub Copilot, and ChatGPT (Codex) — proper OAuth sign-in, no key handling.

Provider key

Stored in SecretStorage

OpenAI, Gemini, DeepSeek, Groq, Mistral, OpenRouter, Bedrock, Azure, xAI… keys live in VS Code's secret store — or come from an env var or a shell command. Existing harness configs are read and reused, not migrated.

Local runtime

Run it on your machine

Ollama, LM Studio, vLLM — or point a custom preset at any OpenAI-compatible endpoint.

Providers Pi supports upstream

OpenAIAnthropicGoogle GeminiGoogle VertexGitHub CopilotOpenRouterAmazon BedrockAzure OpenAIGroqDeepSeekMistralMiniMaxKimiFireworksCerebrasHugging FaceVercel AI GatewayxAIZ.aiOllamalocal

Plus presets for OpenAI-compatible endpoints & local runtimes

OllamalocalLM StudiolocalvLLMlocalOpenRouterVercel AI GatewayMoonshot / KimiAnthropic-compatible proxyGoogle AI StudioCustom (OpenAI-compatible)

The AFX model selector, segmented by provider

One picker

Every configured provider's models in one segmented selector — switch mid-conversation without losing the thread.

Provider settings with OAuth subscription sign-ins

Sign in, don't paste

Subscription providers use proper OAuth flows — sign in with the plan you already pay for, including device-code sign-in that opens the right URL for you.

Provider settings for local runtimes and Pi login

Local & Pi runtimes

Point AFX at a local runtime, or let it use your installed Pi CLI and existing config.

06

No VS Code? Same workflow.

The workflow behind the extension is a set of standard skills — the open agentskills.io format — so any compatible coding agent runs it natively: specs, designs, tasks, journals, traceability. No runtime, no lock-in. The AFX CLI is just the installer: one command drops the skills and packs into your project.

CLI skills · files · traceability = Extension skills · files · traceability

Claude Code — heavily testedCodex — testedGitHub Copilot — tested

—

And a workbench of tools.

Beyond the core loop, the bottom panel is a growing set of repo-owned tools — board, journal, notes, analytics, documents, pipeline, and an experimental canvas. Every view is plain markdown in your repo; more land here over time.

Board

Markdown-backed Kanban — lanes and cards stored as files, no external database.

Journal

The append-only session timeline — decisions and discussions, so any agent resumes where the last one stopped.

Notes

Quick capture with time labels, reader mode, edit and delete — saved straight into .afx/.

Analytics

Velocity, task completion, and feature-stage KPIs with an activity heatmap — plus trace health and ghost-reference counts, so coverage gaps show up as numbers, not surprises.

Documents

Browse and read every spec, design, and ADR in the repo tree without leaving the panel.

Pipeline

Feature progress and next actions in one place — what's moving, and what's next.

Project Canvas: freeform cards for specs and architecture ideas

Canvas Experimental

A freeform surface for specs, notes, ADRs, and architecture ideas — link cards, then send material back into chat as work. Stored as one portable JSON Canvas 1.0 file that round-trips with other canvas tools.

—

Get the skills.

Every skill is a slash command — the SKILL.md name maps 1:1 to the command you type. Two ways to install:

Claude Code · marketplace

Two commands, done

claude plugin marketplace add AgenticFlowX/afx
claude plugin install afx-agenticflowx

The 18 core skills register as /afx-* commands — ~1k tokens always-on for the whole pack. Role packs install the same way: afx-dev, afx-qa, afx-security, afx-architect, afx-product-owner.

Any agent · afx-cli

One curl, prompts for your agents

curl -sL https://raw.githubusercontent.com/AgenticFlowX/afx/main/afx-cli | bash -s -- .
./afx-cli --pack qa --pack security .

Installs into .claude/skills/ and/or .agents/skills/ for Claude Code, Codex, and Copilot. Add role packs with --pack, list with --pack-list, update with --update --packs.

What each pack installs:

agenticflowx — 18 workflow skills → /afx-next · /afx-task · /afx-spec … dev — /afx-tdd · /afx-clean-code · /afx-git-workflow +2 qa — /afx-qa-methodology · /afx-spec-test-planning security — /afx-owasp-top-10 · /afx-security-audit architect — /afx-deep-research product-owner — /afx-product-owner starter — /afx-hello (vibe check)

Want a sandbox first? afx-cli example basic . scaffolds a full sample project with approved specs and traceable code. Full pack & command reference →

—

Watch it work.

Real captures from the AFX end-to-end suite — not mockups.

Chat flow — intents, models, and the SDD guide

Workbench & Previewer flow — from studio into a living spec

—

How it fits together.

Three open-source projects, two doors, one source of truth: the markdown in your repo.

—

Where AFX sits.

Spec-driven tools tend to come in two shapes — thin CLI scaffolders, or a whole separate spec-first editor. AFX sits in the corner neither reaches: a rich surface, in the tools you already use, with code and spec kept in sync.

Shape one

CLI scaffolders

Templates and slash commands that generate specs forward — then leave them behind. No visual surface, no link from code back to requirement, no memory between sessions.

Shape two

Spec-first IDEs

A whole separate editor with its own agent and its own billing. Powerful — but you switch editors to get it, specs are still forward-only, and the workflow can't leave the IDE.

AFX

Both doors, loop closed

An extension in the VS Code you already use and standard skills any agent runs. Living docs that grade themselves, bidirectional @see traceability, session memory — your models, your repo, Apache-2.0.

—

Things worth knowing.

How do pi.dev and provider keys work together?

If you already use pi.dev, AgenticFlowX talks to your installed Pi CLI and uses your existing config. If you don't, it stores provider keys in VS Code SecretStorage and passes them through the Pi SDK.

Do I need to install another SDD tool?

No. The extension includes the chat surface, Spec mode, Workbench views, and AFX workflow actions. Specs, tasks, notes, and journals stay as plain markdown in your workspace.

Do I have to use the spec-driven workflow?

No. Most coding stays in chat. The spec-driven workflow is opt-in — reach for it when a piece of work needs traceability between intent, design, tasks, and code.

Is it free?

AgenticFlowX is open source under Apache 2.0. No vendor billing — you bring your own provider keys, subscription sign-ins, or local runtimes.

Can I make it look like mine?

The Meridian design system ships with seven selectable style variants — lyra, luma, maia, nova, vega, mira, sera — so the panels match your taste, not just your theme.

Does it phone home?

Anonymous usage telemetry with a clear opt-out, and API-key fields are masked from capture. Your code, specs, and keys stay yours.

—

The meat inside — determinism by notation.

AI output is fuzzy; a parser can't be. AFX threads that needle by making headings free and IDs fixed. Sections can move, get renamed, or be added — as long as the node ID is present and unique, every reference still resolves.

# spec.md | ID | Requirement | Priority | | FR-1 | Export as CSV | Must Have | # design.md ## [DES-ARCH] Architecture // @see spec.md [FR-1] # tasks.md ### 1.1 CSV writer // @see [DES-ARCH] [FR-1] // csv-writer.ts /** @see spec.md [FR-1] · design.md [DES-ARCH] */

One FR-1 resolves from spec → design → tasks → code. Rename any heading and it still holds — that stable anchor is what the CLI, extension, and CodeLens parse against.

spec.md — FR-N / NFR-N, sequential and unique
design.md — a [DES-*] anchor on every section; custom ones welcome
tasks.md — ### N.N groups, scoped to files, linked by @see

Full breakdown — every section, every rule →

—

Credits & colophon.

AFX stands on open source and open standards. The workflow is a hybrid of decades of proven practice; the app is built from tools worth naming.

Built with

Pi — the coding harness: sessions, tools, skill discovery, and the model catalog.
JSON Canvas — the open file format behind the Canvas tab, so your project map stays readable by other tools.
React Flow — renders that canvas.
react-markdown + remark-gfm — the previewer's markdown engine.
shadcn/ui · Radix · Tailwind — the UI primitives, with Lucide icons.

Notation, borrowed honestly

MoSCoW priorities · Connextra user stories · IEEE 830 requirements.
C4 architecture · Nygard ADRs · WBS task numbering.
JSDoc @see traceability · Obsidian / Dataview frontmatter.
The full lineage — who we borrowed each part from →