______           ______   _  __
     /\             |  ____|         |  ____| | |/ /
    /  \      __ _  | |__     _ __   | |__    | ' /
   / /\ \    / _` | |  __|   | '_ \  |  __|   |  <
  / ____ \  | (_| | | |____  | | | | | |      | . \
 /_/    \_\  \__, | |______| |_| |_| |_|      |_|\_\
              __/ |
             |___/

AgEnFK: Agentic Engineering Framework

Welcome to AgEnFK, a high-reliability, measurable, and visual framework designed to turn "Vibe Coding" into rigorous Agentic Engineering. AgEnFK enforces a structured workflow that bridges the gap between autonomous AI agents and professional software engineering practices.

---

Table of Contents

• Overview
• How do I use AgEnFK?
• Supported Platforms
• Installation & Setup
• Post-Install Steps
• Rules Scope — Global vs Project
• Pausing & Resuming Integrations
• Uninstalling AgEnFK
• Multi-Project Support
• GitHub Issues Sync
• Corporate Hub
• Architecture Deep Dive
• Custom Workflow Flows
• Quick Start
• Operation Modes
• Telemetry
• FAQ

---

Overview

AgEnFK is built on six core mandates to ensure your AI-assisted development is consistent and high-quality:

• Agile: Uses Epics, Stories, Tasks, and Bugs as first-class workflow items.
• Measurable: Automatically tracks input/output tokens and models used for every single unit of work.
• Visual: A real-time, hierarchical Kanban board provides instant oversight of the entire project state.
• Repeatable: Uses standardized tools, prompt protocols, and context engineering to make AI behavior deterministic.
• Reliable: Enforces mandatory verification (build/lint/test) before any work is declared "Done".
• Flexible: Plugin-based architecture with support for MCP (Model Context Protocol), usable across multiple AI coding agents.

How do I use AgEnFK?

The core experience is simple: you describe what you want in plain language, and AgEnFK turns it into a structured, verified workflow. Here is what happens end-to-end using the default flow (TODO → IN_PROGRESS → REVIEW → TEST → DONE).

1. You make a request

Open your AI coding agent (Claude Code, pi, Opencode, Gemini CLI, etc.) and invoke the skill followed by what you need — /agenfk in most clients, /skill:agenfk in pi, $agenfk in Codex:

/agenfk Add a retry mechanism to the API client with exponential backoff

The agent reads your request, classifies it (Task, Story, or Epic depending on complexity), and creates a card on the Kanban board in the TODO column.

2. The agent plans and codes

The agent advances the card to IN_PROGRESS and begins implementation. It explores your codebase, understands the context, writes the code, and logs progress comments on the card as it goes — giving you full visibility on the Kanban dashboard.

3. Build verification

Once the implementation is complete, the agent moves the card to REVIEW and performs a self-review of every file it modified. It then runs your project's build command (e.g. npm run build, cargo build) to verify the code compiles cleanly.

4. Test verification

The card advances to TEST, where AgEnFK runs your project's full test suite using the configured verifyCommand. If tests fail, the card is automatically moved back to IN_PROGRESS and the agent fixes the issues — no manual intervention needed.

5. Done

When all verification passes, the card moves to DONE, the agent commits the changes, and pushes the branch. You get a summary of everything that was implemented, and can choose to cut a release, start a new task, or keep iterating.

---

This default flow is the main workflow, but AgEnFK is designed to adapt to how you work — not the other way around.

Define your own flows. The default pipeline is just a starting point. You can create custom flows with any steps and exit criteria you need — for example, a BDD flow (TODO → WRITE_TESTS → IMPLEMENT → REVIEW → DONE) or a minimal flow (TODO → CODING → DONE). Share your flows with the community via the AgEnFK Community Registry, and download flows published by other engineers — all from the Flow Editor in the Kanban UI. See Custom Workflow Flows for details.

Bring your own cards. You don't have to start every task from a chat prompt. Import cards from JIRA or GitHub Issues to pull work items directly into your AgEnFK board (see GitHub Issues Sync), or create and organise cards manually on the Kanban dashboard using drag-and-drop — then let the agent pick them up when you're ready.

Supported Platforms

Platform	Support Level	Enforcement	Notes
Claude Code	Fully Supported	PreToolUse hooks (mechanical)	Automatic blocking of workflow violations; gatekeeper + mcp-enforcer hooks install even in CLI-only mode
pi (0.79+)	Fully Supported	Native extension (mechanical)	~/.pi/agent/extensions/agenfk.ts, auto-loaded via jiti (no build, no node_modules). Full enforcement parity with Claude Code — pre-edit gatekeeper + bash mcp-enforcer + PR-sizing reminder, all delegating to the same ~/.agenfk/bin/*.mjs scripts. Resolves the model deterministically — primarily from pi's ~/.pi/agent/settings.json defaultModel, with ctx.getModel() when pi exposes it live — so PR events carry the real model id + harness=pi
Opencode	Fully Supported	CLI + skill integration	Native slash commands and skill system; MCP optional (--with-mcp)
Google Gemini CLI	Fully Supported	CLI + workflow rules	Native slash commands and skill system; MCP optional (--with-mcp)
Cursor	Experimental	Instructional (.mdc rules)	alwaysApply: true rule file
OpenAI Codex CLI	Fully Supported	CLI + skills	Skills invoked via $agenfk (type $ in Codex to browse); AGENTS.md workflow rules; MCP optional (--with-mcp)

All platforms drive the workflow through the agenfk CLI by default — MCP is opt-in everywhere via --with-mcp (see Installation & Setup). Claude Code and pi are the two clients with mechanical enforcement: Claude Code via PreToolUse hooks, pi via a native in-process extension. Both block edits when no AgEnFK task is active and both block the direct-DB / curl localhost bypass routes. Cursor remains experimental because it relies on instructional rules without mechanical enforcement hooks. Codex CLI accesses skills with $skill-name (not /).

Installation & Setup

AgEnFK installs with a single command — no cloning required:

npx github:cglab-public/agenfk

This will: * Download the framework directly from GitHub. * Install all dependencies and build the full stack. * Symlink the agenfk CLI to ~/.local/bin for global access — this is the primary, fully server-enforced interface for the entire workflow. * Install workflow rules into each detected platform (CLAUDE.md, AGENTS.md, GEMINI.md, .mdc for Cursor). * Install the /agenfk and /agenfk-release slash commands and the Agent Skills in your AI editors (including the universal skills at ~/.agents/skills/, which pi loads natively). * Install the pi native extension to ~/.pi/agent/extensions/agenfk.ts when pi is detected — auto-loaded via jiti, giving pi the same mechanical enforcement as Claude Code. * Configure the start:services Node script to launch the API and Web UI.

AgEnFK is CLI-only by default. The agenfk MCP server is not registered on install. MCP is opt-in: * npx github:cglab-public/agenfk --with-mcp — also register the MCP server with every detected client. * npx github:cglab-public/agenfk --no-mcp — force CLI-only (and unregister any previously registered agenfk MCP server).

Your choice is persisted in ~/.agenfk/config.json and honored on every upgrade, so you only need to pass the flag once. You can also flip it later per-platform with agenfk integration install <platform> --with-mcp / --no-mcp. When MCP tools are present, agents may use them interchangeably with the CLI — the CLI commands remain the canonical, equivalent path.

Requirements: Node.js 22.5+, git, and npm. To create GitHub releases, install the gh CLI.

To update, run the same command again — npm will fetch the latest from GitHub and re-run setup. A default (no --with-mcp) upgrade cleanly unregisters any stale agenfk MCP server, so you never end up in a half-state.

Post-Install Steps

After installation, complete the setup:

1. Restart your AI editor (Opencode, Cursor, Codex, and Gemini CLI need a restart to pick up MCP if you opted in; pi needs a restart to load its native extension).
2. Start the services in a dedicated terminal — this keeps the API and Web UI running in the background: bash agenfk up This launches the API server on http://localhost:3000 and the Kanban UI (typically http://localhost:5173).
3. Service Lifecycle: Manage your installation with the following commands:
   • agenfk upgrade: Fetch the latest release and auto-restart services.
   • agenfk upgrade --beta: Opt-in to pre-release/beta versions.
   • agenfk restart: Quickly cycle both the API and UI.
   • agenfk down: Stop all running AgEnFK processes.
   • agenfk health: Verify configuration, database, and connectivity.
   • agenfk integration list: Show the supported editor and agent integrations.
   • agenfk pause <platform>: Temporarily disable a specific integration (removes MCP config and skills). Use all to pause every integration.
   • agenfk resume <platform>: Re-enable a previously paused integration. Use all to resume everything.
4. Initialize a project — go to any repository and type /agenfk in your AI editor to link it to the framework.

Rules Scope — Global vs Project

During first install, AgEnFK asks where workflow rules (CLAUDE.md, AGENTS.md, GEMINI.md, agenfk.mdc) should be installed:

• Global (default) — rules go to ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, etc. They are picked up automatically by every AI coding tool, across all repositories — no per-repo setup needed.
• Project — rules go to .claude/CLAUDE.md, AGENTS.md in the project root, etc. Scoped to the current repository only. You must install rules in each repo you want AgEnFK to manage.

Your choice is saved in ~/.agenfk/config.json and respected on every upgrade. To manage rules after installation:

agenfk skills install            # install rules & skills globally (default)
agenfk skills install --project  # install into the current repo (uses git root)
agenfk skills uninstall          # remove global rules & skills (default)
agenfk skills uninstall --project  # remove project-scoped rules & skills
agenfk skills status             # show current scope (global, project, or none)

Switching automatically removes rules from the old location and installs them in the new one.

Pausing & Resuming Integrations

You can temporarily disable one or all editor integrations without fully uninstalling AgEnFK. This is useful when you want to stop AgEnFK from appearing in a specific AI editor without losing your configuration or workflow data.

Pause removes the MCP server registration and all AgEnFK skills/slash commands from the target editor. The framework itself (server, database, CLI) continues running normally.

# Pause a single integration
agenfk pause claude
agenfk pause opencode
agenfk pause cursor
agenfk pause codex
agenfk pause gemini

# Pause all integrations at once
agenfk pause all

# Use --yes to skip the confirmation prompt
agenfk pause claude --yes

Resume re-installs the MCP registration and skills for the target editor, restoring it to fully operational state.

# Resume a single integration
agenfk resume claude
agenfk resume opencode

# Resume all previously paused integrations
agenfk resume all

# Use --yes to skip the confirmation prompt
agenfk resume all --yes

Paused integrations are tracked in ~/.agenfk/config.json under pausedIntegrations. Resume respects your configured rulesScope (global or project) so rules are reinstalled in the correct location.

Supported platform IDs: claude, opencode, cursor, codex, gemini. You can also use the alias claude-code for claude.

Note on pi: pi's native extension is managed by the main installer (and removed by agenfk uninstall), not by the agenfk integration / pause / resume commands. To remove just the pi extension, delete ~/.pi/agent/extensions/agenfk.ts; re-run the installer to restore it.

Uninstalling AgEnFK

To fully remove AgEnFK from your system:

agenfk uninstall

This removes: - All slash commands and skills from Claude Code, Opencode, and Gemini CLI - MCP server configuration from all editors (Claude Code, Opencode, Cursor, Codex CLI, Gemini CLI) - Cursor workflow rules (agenfk.mdc) - The pi native extension (~/.pi/agent/extensions/agenfk.ts) - Workflow rules from all scopes (CLAUDE.md, AGENTS.md, GEMINI.md) - The AgEnFK PreToolUse hook from ~/.claude/settings.json - The ~/.agenfk-system framework files - The agenfk CLI symlink from `~/.l