Works with
AgenticFlowX VSCode Extension (Alpha) — A dedicated visual interface for the AFX workflow. Track your feature pipeline, navigate specifications, and manage skill packs directly in the editor. Read more →
Warning
Alpha Status — Not yet on the VS Code Marketplace. Expect bugs. Some features may be unstable.
- 🔒 Repository is private — not yet public on GitHub.
- 📦 Download the
.vsixfrom the Releases page. - 🤝 Companion tool — not a replacement for agents like Claude Code or Codex.
- 🖥 Tested on macOS and WSL — not yet verified on native Windows.
Install
# Option 1 — One-liner (download + install)
curl -L -o vscode-afx.vsix https://github.com/rixrix/afx/releases/download/v2.1.0/vscode-afx-2.0.0-alpha.1.vsix && code --install-extension vscode-afx.vsixOr from VS Code: download the .vsix from the Releases page, then Cmd+Shift+P → Extensions: Install from VSIX... and select the file.
See it in action — Open the vscode-showcase example project used in the screenshots below:
git clone https://github.com/rixrix/afx.git && code afx/examples/vscode-showcasePause. Think. Plan. Ship.
AFX is a spec-driven development framework for AI coding assistants (Claude Code, Codex, Gemini Code Assist, GitHub Copilot).
AFX is NOT a "one-prompt-builds-all" generator.
We are currently in an era of rapid, sloppy AI generation where speed is prioritized over technical debt. AFX forces developers and AI agents to slow down, build a "bird's-eye view" of the architecture, and follow a strict, deliberate plan before a single line of code is written.
It prevents AI agents from going off-spec by enforcing bidirectional traceability between specifications and code, preserving context across sessions, and requiring quality gates before tasks close.
journey
title The AFX Philosophy
section Pause
Stop rapid generation: 5: Agent
Review current state: 4: Agent
section Think
Define the WHAT: 5: Team
Architect the HOW: 4: Team
section Plan
Create atomic tasks: 5: Agent
Get human approval: 5: Human
section Ship
Write traced code: 4: Agent
Verify execution path: 5: Agent
AI coding assistants are incredibly fast, but they suffer from fundamental flaws when building serious software:
graph TD
A[The Fast AI Problem] --> B[Context Amnesia]
A --> C[Scope Creep]
A --> D[Orphaned Code]
A --> E[Hallucinated Completion]
B -->|Close terminal = restart brain| F(Frustration)
C -->|Fix a bug = refactors everything| F
D -->|Why does this function exist?| F
E -->|Code written but never called| F
style A fill:#f8d7da
style F fill:#dc3545,color:white
AFX gives your AI coding agents a memory, a strict set of rules, and a deliberate workflow.
1. Specs as Source of Truth & Traceability
Every function gets an automatic @see link mapping it back to the exact spec requirement (spec.md [FR-X] and design.md [DES-ID] are required; tasks.md links are optional).
graph LR
A[spec.md] --> B[design.md]
B --> C[tasks.md]
C -. "@see" .-> D[Code]
D -. "@see" .-> A
style A fill:#fff3cd
style B fill:#cfe2ff
style C fill:#d1e7dd
style D fill:#f8d7da
2. Execution Verification
Code isn't done just because it exists. /afx-check path traces logic from the UI down to the database to cryptographically prove the path works.
graph TD
A[UI / Controller] -->|Click| B[Business Logic]
B -->|Query| C[Database / API]
A -.->|AFX Verifies| C
style A fill:#e1f5ff
style C fill:#d4edda
3. Two-Stage Quality Gates
AI agents can hallucinate completion. AFX forces tasks to require both Agent [x] and Human [x] before they can be closed.
stateDiagram-v2
state "Agent Implementation" as AI
state "Human Review" as HR
state "Task Closed" as C
[*] --> AI
AI --> HR : Agent [x]
HR --> AI : Rejected
HR --> C : Human [x]
C --> [*]
4. Stateful Session Contexts & Continuity
Close your laptop without losing context. /afx-session log records your train of thought, and /afx-context save bundles it so another agent can instantly resume tomorrow.
sequenceDiagram
participant A as Agent 1 (Day 1)
participant H as afx-context.md
participant B as Agent 2 (Day 2)
A->>H: /afx-context save
Note over A,H: Saves tasks, decisions, uncommitted files
B->>H: /afx-context load
Note over H,B: Loads exact mental state
B->>B: Continues deliberate work
AFX isn't just a script you run; it's made up of three parts that work together:
- The Workflow: The actual rules and methodology. This is the "pause, think, plan" philosophy, the commands you use, and the verification steps that keep your project from turning into a mess.
- The Skills (
afx/skills): These are the literal prompt instructions we feed to Claude, Codex, or Copilot. They follow the open agentskills.io standard format, teaching your AI assistant how to follow the workflow, what commands like/afx-nextdo, and how to format their output. - The Templates: The physical markdown files (
spec.md,design.md, etc.) that hold your project's rules and history.
Agent Compatibility: Skills follow the open agentskills.io standard. Tested and verified tools:
| Agent | Status | Notes |
|---|---|---|
| Claude Code | ✅ Heavily tested | Primary development environment |
| GitHub Codex | ✅ Tested | Several validation runs |
| GitHub Copilot | ✅ Tested | Via .github/prompts/ |
| Gemini CLI | ✅ Tested | Via .gemini/commands/ |
| Cline | May work, not verified | |
| AugmentCode | May work, not verified | |
| KiloCode | May work, not verified | |
| OpenCode | May work, not verified |
Let's look at those templates.
Every feature gets four files. The sequence is mandatory — you cannot start design until spec is approved, and you cannot open tasks until design is approved:
1. spec.md → define WHAT to build (get human approval)
2. design.md → define HOW to build it (get human approval)
3. tasks.md → define WHEN / atomic checklist (then implement)
4. journal.md → append-only log of decisions (every session)
mindmap
root((Feature))
spec_md["1. spec.md"]
The WHAT
Requirements
User Stories
design_md["2. design.md"]
The HOW
Architecture
Data Models
tasks_md["3. tasks.md"]
The WHEN
Atomic Checklist
Quality Gates
journal_md["journal.md"]
Memory
Session Logs
Decisions & Context
-
spec.md: Requirements only. No implementation details.[FR-X]and[NFR-X]IDs are stable anchors that code links back to.--- afx: true type: SPEC status: Draft owner: "@rix" version: "1.0" created_at: "2025-10-20T10:00:00.000Z" updated_at: "2025-10-20T10:00:00.000Z" tags: ["user-management"] --- # User Management - Product Specification ## Functional Requirements | ID | Requirement | Priority | | ---- | ------------------------------------------------- | --------- | | FR-1 | Paginated, sortable list of all users. | Must Have | | FR-2 | Filter by Role, Status, and Verification Context. | Must Have | ## Non-Functional Requirements | ID | Requirement | Target | | ----- | ----------- | ------------------- | | NFR-1 | Performance | Page load < 2s | | NFR-2 | Security | Auth on all actions |
-
design.md: Technical architecture. How you'll implement the spec. Every##heading has a[DES-ID]Node ID.--- afx: true type: DESIGN status: Draft owner: "@rix" version: "1.0" created_at: "2025-10-21T09:00:00.000Z" updated_at: "2025-10-21T09:00:00.000Z" tags: ["user-management"] spec: spec.md --- # User Management - Technical Design ## [DES-DATA] Data Model | Column | Type | Description | | ------ | ------ | ----------------- | | `id` | UUID | Primary Key | | `role` | String | User Access Level | ## [DES-API] Server Actions <!-- @see spec.md [FR-1] [FR-2] --> ```typescript export async function createUser(data: CreateUserSchema): Promise<Result<User>> { // 1. Validate permissions via CASL // 2. Insert into PostgreSQL } ```
-
tasks.md: Implementation checklist. Structured using dot-notation derived from traditional Work Breakdown Structures (WBS). Requires two-stage verification (Agent + Human) before a phase is closed.--- afx: true type: TASKS status: Draft owner: "@rix" version: "1.0" created_at: "2025-10-22T08:00:00.000Z" updated_at: "2025-10-22T08:00:00.000Z" tags: ["user-management"] spec: spec.md design: design.md --- # User Management - Implementation Tasks ## Phase 1: Data Layer - [ ] 1.1 Add User model to schema and run migrations - [ ] 1.2 Implement repository interface and adapter ## Phase 2: Frontend UI - [ ] 2.1 Build `<UsersTable />` with Tailwind styling - [ ] 2.2 Wire table to server action with Zod validation ## Work Sessions | Date | Task | Action | Files Modified | Agent | Human | | ---- | ---- | ------ | -------------- | ----- | ----- |
-
journal.md: Append-only historical log of all discussions and decisions.--- afx: true type: JOURNAL status: Living owner: "@rix" created_at: "2025-10-20T10:00:00.000Z" updated_at: "2025-10-24T14:00:00.000Z" tags: ["user-management"] --- # Journal - User Management <!-- prefix: UM --> ## Captures ## Discussions ### UM-D001 - Schema decision `created:2025-10-24` Chose `uuid` over autoincrement integer for `id` to prevent enumeration. API route `/api/users` completed. Next agent should wire frontend table.
-
research/: (Auxiliary) Dedicated space for feature-local decision records (ADRs).
Traceability in action: When the agent writes code, every major function gets a @see backlink to the spec or task that required it. This is how AFX eliminates orphaned code.
// ✅ AFX-compliant: every function is traceable back to its requirement
/**
* @see docs/specs/user-auth/spec.md [FR-1]
* @see docs/specs/user-auth/design.md [DES-AUTH]
*/
export async function generateVerificationToken(email: string): Promise<string> {
// Implementation...
}
/**
* @see docs/specs/user-auth/spec.md [FR-2]
* @see docs/specs/user-auth/design.md [DES-API]
*/
export async function signInWithEmail(data: SignInSchema) {
// Implementation...
}Looking for the full templates or a working example?
- Templates are bundled inside each skill's
assets/directory (e.g.,skills/agenticflowx/afx-spec/assets/spec-template.md) for the exact YAML frontmatter and document structures expected by AFX coding agents.- Explore the
examples/minimal-project/directory to see how a complete AFX continuous-development environment is structured in practice.
AFX prevents AI context window bloat and conflicting instructions by separating global rules from local rules.
graph TD
A[CLAUDE.md<br/>Global Brain] -->|System-wide Tokens<br/>Tailwind, Shadcn, Colors| C[AI Session]
B[docs/specs/*/design.md<br/>Feature Brain] -->|Specific Layouts<br/>Grid, Forms, Composition| C
style A fill:#e1f5ff
style B fill:#e1f5ff
style C fill:#d1e7dd
/afx-next - Context-aware guidance
Analyzes your project state and tells you exactly what to work on next. Checks for unapproved specs, incomplete tasks, pending verifications, and stale sessions.
/afx-discover [capabilities|scripts|tools|project] - Project intelligence
Scans your codebase to understand build systems, test runners, package managers, and available tooling. Claude learns how to build, test, and deploy your project.
/afx-spec validate|discuss|review|approve - Specification management (owns spec.md)
/afx-design author|validate|review|approve - Technical design authoring, validation, and approval
/afx-task plan|pick|code|verify|complete|sync - Implementation lifecycle — plan, pick, code, verify, complete, sync
/afx-dev debug|refactor|review|test|optimize - Advanced diagnostics — debug, refactor, review, test, optimize
/afx-scaffold spec|research|adr <name> - Scaffold new work
/afx-adr create|review|list|supersede - ADR management
/afx-check path|trace|links|deps|coverage - Quality gates
path- BLOCKING GATE: Trace execution from UI → business logic → databasetrace- Verify all code has valid@seeannotationslinks- Check spec integrity and cross-referencesdeps- Check dependency health and compatibilitycoverage- Measure spec-to-code coverage
/afx-hello - Environment diagnostics and installation verification
/afx-session note|log|active|recap|promote - Discussion capture and context preservation
/afx-context save|load - Context transitions
Package current context for transfer to another agent or future session. Includes spec state, task progress, verification status, and discussion history.
/afx-report orphans|coverage|stale - Traceability metrics and project health
afx-scaffold spec → afx-spec approve → afx-design author → afx-design approve
→ afx-task plan → afx-task pick → afx-task code → afx-check path → afx-task complete
↑ |
└────────── afx-next (resume next session) ──────┘
Note on OS Support: The AFX CLI and commands are heavily tested on macOS and Unix-like systems (Linux/WSL). They have not been formally tested on native Windows.
# From your project directory
curl -sL https://raw.githubusercontent.com/rixrix/afx/main/afx-cli | bash -s -- .Or if you have AFX cloned locally:
./path/to/afx/afx-cli /path/to/your/projectThe installer prompts you to select which AI agents you use, then installs:
- AFX skills to selected skill targets (
.claude/skills/and/or.agents/skills/), including templates bundled in skillassets/directories - Configuration file
.afx.yaml - AFX documentation to
docs/agenticflowx/ - Context files for selected agents (
CLAUDE.md,AGENTS.md, and optionallyGEMINI.md) - Directory structure:
docs/specs/anddocs/adr/
A common difficulty for new users is translating a raw idea into structured AFX specifications (the "blank canvas" problem). You don't have to write these specifications manually - you can use Claude Code, Codex, Gemini CLI, or GitHub Copilot to scaffold them for you.
graph TD
A[Raw Idea<br/>'Build a SaaS Landing Page'] --> B[Claude Code]
B -->|Asks Clarifying Questions| C[User Answers]
C -->|Auto-executes /afx-scaffold| D[docs/specs/saas-landing/]
D --> E[spec.md<br/>FRs & NFRs]
D --> F[design.md<br/>Architecture & UI]
D --> G[tasks.md<br/>Implementation Checklist]
style A fill:#f8d7da
style B fill:#d1e7dd
style C fill:#cfe2ff
style D fill:#e1f5ff
Step 1: Start the CLI
Navigate to your project directory and start the CLI by typing claude.
Step 2: Paste the Kickoff Prompt Copy the prompt below and paste it directly into Claude. By default, it uses a simple "SaaS Landing Page" example so you can safely test how the framework operates. You can replace the first sentence with your actual feature idea:
I want to build a single-page landing page for my SaaS product. Make it plain, static HTML/CSS/JS with no frameworks (no React, Next.js, etc) so I can easily preview it in my browser.
Please act as my Product Manager and Technical Architect:
1. Ask me 1-3 clarifying questions about this idea. Wait for my response.
2. Once answered, use the `/afx-scaffold` command to scaffold the folder structure.
3. Write the `spec.md`, `design.md`, and `tasks.md` files based on our discussion. Remember to check `CLAUDE.md` for global UI conventions before writing the design document.
When you're done, ask me if I'm ready to run `/afx-task pick` to start coding!
Step 3: Answer the Questions Claude will act as your Product Manager and pause to ask you a few clarifying questions.
Step 4: Review the Generated Output
Once you answer, Claude will automatically run /afx-scaffold and build out your specification files tailored to your answers:
spec.md: Contains your User Stories, Functional Requirements, and Non-Functional Requirements.design.md: Contains your system architecture, color palettes, and component layouts.tasks.md: Contains Phase 1, Phase 2, etc., with atomic checkboxes mapped back to the spec via@see.
Important caveat: The skills driving these AFX commands are still a work in progress and are rapidly evolving.
From extensive experience, we know that LLMs (like Claude, Codex, and others) can sometimes "drift" or hallucinate, even when provided with heavy instructions and stringent AFX guidelines. There will inevitably be times when tools and commands do not execute exactly as expected.
As a user, you should anticipate a hybrid workflow. You will often need to use a mix of strict AFX slash commands (e.g., /afx-spec review) combined with your own on-the-fly custom prompting to course-correct the agent when it loses context or drifts from the instructions. AFX provides the crucial rails, but you are still the driver.
Pipeline — feature health across the pipeline
|
Tasks — phases, checkboxes, and work session history
|
Analytics — project health KPIs and pipeline gauge
|
Documents — master-detail doc browser with markdown preview
|
Journal — discussions across all spec journals
|
Board — kanban boards backed by YAML in .afx/kanban/
|
Notes — quick capture with markdown timeline
|
Architecture — dependency graph and cycle detection
|
AFX's template system is a pragmatic hybrid of established industry standards:
- IEEE 830 / ISO/IEC/IEEE 29148 -- Software Requirements Specification structure, adapted for agile feature-level specs
- MoSCoW (Dai Clegg, 1994 / DSDM) -- Requirement prioritization: Must Have / Should Have / Could Have / Won't Have
- User Stories (Mike Cohn / XP) -- Connextra format: "As a [role], I want [feature], So that [benefit]"
- C4 Model (Simon Brown) -- Software architecture diagram levels (Context, Container, Component, Code)
- ADR (Michael Nygard, 2011) -- Architecture Decision Records: Context, Decision, Consequences
- WBS (PMI PMBOK Guide) -- Work Breakdown Structure for hierarchical task decomposition
- Traceability Matrix (IEEE 29148 / DO-178C) -- Cross-reference mapping from Requirements to Design to Code
Contributions are welcome! Please read CONTRIBUTING.md before submitting PRs.
MIT License - see LICENSE for details.
AFX was developed as part of real-world production projects and refined through extensive use with Claude Code, Codex, Gemini CLI, and GitHub Copilot.