Afkode Documentation

Everything you need to know about planning and building features with Afkode.

What is AFK Coding?

AFK — away from keyboard.

Building software with AI today means managing the AI. You write the prompt, review the output, re-explain context when the model forgets, copy-paste between files, fix what it got wrong, and start over when the conversation drifts. The real work isn't the coding — it's the context management. Making sure the AI knows about the right files, the right patterns, the right requirements, the right tests. Every session, you rebuild this from scratch.

AFK coding separates the work that only you can do from the work a system can handle better.

Your job: describe what you want to build and make the decisions that shape the product. What should this feature do? Who is it for? What are the acceptance criteria? What's in scope and what's not? This is where your expertise matters most — the product thinking, the business context, the priorities that no AI can decide for you.

The system's job: everything else. Analyze the codebase. Plan the architecture. Break the work into tasks with the right dependencies. Assemble the exact context each task needs — the relevant requirements, the right files, the patterns to follow. Implement each task in a fresh session that never loses context, never gets confused by previous conversations, never cuts corners because it's "running low on tokens." Write real tests. Verify every acceptance criterion. Commit working code. Run for hours without intervention, with the same thoroughness on the last task as the first.

No re-explaining. No context pollution. No skipped tests. No "I'll just manually check this one." The system doesn't get tired, doesn't rush, and doesn't decide that testing isn't worth the effort. It follows the plan you approved, all the way through.

You spend your time where it creates the most value — defining what to build, talking to customers, growing your business. The engineering runs in the background, methodically and completely, until it's ready for your review.

That's AFK coding. That's what Afkode is built for.

Features, Not Chats

Most AI coding tools work in chat sessions. You open a chat, describe something, iterate back and forth. The session has no structure — just a conversation. When you start a new one, the context is gone.

Afkode works in features. In Afkode, a "feature" is any scoped piece of work — a new capability, a refactor, a batch of bug fixes, a migration, an architecture change. Whatever it is, when you define it, you're not starting a conversation. You're creating a structured unit of work with its own lifecycle:

• Its own requirements document with traceable acceptance criteria
• Its own technical blueprint with architecture decisions
• Its own task breakdown with dependencies and verification steps
• Its own git worktree with an isolated branch
• Its own execution queue where tasks run with fresh context
• Its own QC verification ensuring every requirement is tested
• Its own review phase where you can ask questions, fix bugs, and merge

This is why the initial definition matters. It's not a prompt that gets one response — it's the seed for an entire engineering pipeline. The clearer you define the work, the better every downstream artifact becomes.

Think of it this way: other tools let you talk to an AI about code. Afkode lets you commission a piece of engineering.

System Requirements

• macOS (Intel or Apple Silicon)
• Git installed (Afkode includes a bundled fallback if not found)
• At least one AI coding agent CLI: Claude Code, OpenAI Codex, Gemini CLI, or Kimi CLI
• Internet connection (required for authentication and AI provider access)

Download & Install

Download the latest version from afkode.ai. Drag the app to your Applications folder. The app checks for updates automatically and downloads them in the background.

Onboarding Wizard

When you first launch Afkode, a four-step wizard walks you through setup. This takes about two minutes and only happens once.

Your First Project

A project in Afkode is a git repository on your machine. When you add a project, Afkode validates it's a proper git repo, detects the main branch, and uses it as the base for all feature branches. You can manage projects from Settings → Projects.

Connecting AI Providers

After onboarding, go to Settings → Accounts to connect your AI providers. You can connect multiple providers and assign different models to different tasks.

Supported Providers

Afkode works with your existing AI subscriptions or API keys. You pay your AI provider directly — Afkode charges no markup on AI usage.

• Anthropic Claude — Claude Opus, Sonnet, Haiku via Claude Code CLI
• OpenAI Codex — GPT models via Codex CLI
• Google Gemini — Gemini models via Gemini CLI or API key
• Moonshot Kimi — Kimi models via Kimi CLI
• OpenCode — Any model supported by the OpenCode CLI, including models from Anthropic, OpenAI, Google, and other providers accessible through their unified API

Model Assignments

Afkode has independently configurable activity slots across planning, execution, and review. Each slot can be assigned to any provider and model combination. This means you can use Claude Opus for architecture decisions, Codex for implementation, Gemini for fast tasks, and Kimi for elaboration — all within the same feature.

Planning Slots (10)

Execution Slots (3)

Review Slots (3)

Multi-Model Orchestration

When a task runs, Afkode looks up the model assignment for that specific activity, resolves the provider credentials, and routes the request to the right AI backend. This happens transparently — you configure assignments once in Settings, and every feature uses them automatically.

The benefit: use your most capable (and expensive) model for the tasks that need it most, and a faster, cheaper model for everything else.

Recommended Model Configuration

Based on extensive testing across hundreds of features, here's what we recommend for each activity. You're free to experiment, but this configuration gives the best balance of quality, speed, and cost.

The Verification Loop

QC tasks don't just "write some tests." They follow a structured verification loop that ensures every requirement is actually tested:

For Batch QC tasks, this loop covers the tasks in that specific batch. Feature QC runs comprehensive verification across the entire feature, checking for regressions and cross-task issues.

This is why model choice matters for QC. The verification loop demands a model that can hold the full picture — requirements, criteria, existing tests, infrastructure constraints — and systematically work through each step without skipping or simplifying. In our experience, Claude Opus 4.7 Max and GPT-5.4 XHigh are the two strongest options for carrying this loop end-to-end.

How Afkode Runs AI

Afkode is a first-party integration with the native CLI tools from each AI provider. It doesn't use wrapper APIs, proxy servers, or middleware. When a task runs, Afkode spawns the provider's official CLI directly on your machine, passes it a curated prompt, and streams the output back.

What "First-Party" Means

Each supported provider ships an official command-line tool (Claude Code, Codex CLI, Gemini CLI, Kimi CLI, OpenCode). Afkode launches these tools as local subprocesses — the same binaries you could run from your terminal. No traffic is proxied through our servers. The AI runs locally, reads your files locally, and writes code locally.

• Your code never leaves your machine through Afkode. It goes directly from your filesystem to the CLI tool, which communicates with its own provider's API.
• Your API keys and OAuth tokens stay local. Credentials are passed to the CLI via environment variables or the CLI's own auth mechanism — never transmitted to Afkode's servers.
• The working directory is your feature's worktree. The agent operates inside the isolated git worktree, not your main project directory.

The Execution Flow

For OpenCode, the integration works slightly differently — a local background process handles communication with the provider. It runs on your machine only and is never exposed to the network.

Agent Permissions by Provider

When Afkode spawns an AI agent, it grants the agent full autonomy to complete the task without interactive prompts. This is necessary because there's no human at the keyboard during execution — the whole point is AFK coding.

Here's what each provider's agent can do:

Safety Boundaries

Even with full permissions, several safety mechanisms are in place:

• Precise, scoped instructions: Each agent receives a tightly scoped prompt with only the context relevant to its specific task — the right PRD sections, the right blueprint decisions, the right file references. The agent isn't given a vague instruction and left to figure it out. It gets exact subtasks, target files, and verification criteria. This dramatically reduces the surface area for hallucination or off-track work.
• Fresh sessions eliminate drift: Every task starts a brand new AI session with a clean context window. No accumulated conversation history. No stale context from previous tasks. No gradual degradation. Combined with the recommended state-of-the-art models, this means the conditions that typically lead to hallucinations — bloated context, conflicting instructions, model fatigue — are structurally eliminated.
• Worktree isolation: The agent's working directory is a git worktree, not your main project. Mistakes are contained to the feature branch.
• Force push blocking: A dedicated security validator scans all git push commands for force push flags (-f, --force, --force-with-lease, --force-if-includes) and blocks them before execution. All blocked attempts are logged.
• Process isolation: Each agent runs in its own process group. If something goes wrong, the entire process tree can be cleanly terminated.
• Pause and cancel: You can freeze or kill the agent at any time from the app.
• No network exposure: OpenCode servers bind to 127.0.0.1 only — not accessible from other machines on your network.

Anatomy of a Great Request

The quality of your initial feature description is the single biggest factor in the quality of the output. A clear, detailed request produces a precise PRD, a focused blueprint, and well-scoped tasks. A vague request forces the system to guess — and guesses compound through every phase.

You don't need to write a formal spec. But the more clearly you communicate what you want, why you want it, and what "done" looks like, the better the results.

The Six Elements

Examples: Good vs. Mediocre

Adding a Notification Center

Adding Multiple AI Providers

State Transitions for a Kanban Board

Common Mistakes

• "Build X" without explaining why — the AI doesn't know what problem you're solving, so it can't make good trade-off decisions
• No acceptance criteria — if you don't define "done," the PRD will define it for you, and it might not match your expectations
• Infinite scope — "build a complete auth system" without constraints produces a 50+ task plan. Scope it: "add Google OAuth login to the existing email/password flow"
• Implementation instructions instead of outcomes — "use React Query with staleTime of 5 minutes" tells the AI how instead of what. Better: "data should be cached and refreshed periodically to avoid stale state." The analysis phase already reads your codebase patterns.
• No mention of what's out of scope — if you don't say "don't touch the auth system," a feature that's adjacent to auth might refactor it. Explicit exclusions prevent this.

Feature Lifecycle Overview

Every feature in Afkode goes through a clear lifecycle:

1. Define — You define what you want to build
2. Plan — The system analyzes your codebase, asks clarifying questions, and generates a PRD, Technical Blueprint, and Task Breakdown
3. Execute — Tasks are implemented one by one (or automatically in sequence), each in a fresh AI session with curated context
4. Review — You review the results, ask questions, report bugs, and check diffs
5. Ship — Merge to your main branch with one click

Each feature runs in its own git worktree with its own branch. Your main branch stays untouched until you explicitly merge.

Your Role vs. The Platform

Afkode is designed for AFK coding. You provide the intent; the platform handles the engineering. Here's exactly when you're needed and when you're not.

When You're Needed

What the Platform Does Autonomously

After your initial request and Q&A answers, the platform handles everything else without intervention:

• Analyzes your codebase — discovers patterns, frameworks, conventions, test setup
• Generates the full PRD — sections built in parallel, each with requirements, acceptance criteria, and scope
• Generates the Technical Blueprint — architecture decisions, component design, integration contracts
• Breaks down into tasks — with dependencies, coherence groups, verification criteria, and QC placement
• Verifies coverage — every requirement traced to at least one task
• Executes each task — fresh AI session, curated context, subtask-level progress tracking
• Commits code — each completed task produces a real git commit
• Auto-proceeds to next task — no manual intervention between tasks
• Runs QC verification — batch QC after task groups, feature QC at the end
• Updates runtime knowledge — each task writes learnings for the next
• Tracks tokens, cost, and time — metrics available in real-time
• Handles crashes — all state persisted, execution resumes on restart

Planning Phase

Planning takes your feature description and produces three structured documents: a Product Requirements Document (PRD), a Technical Blueprint, and a Task Breakdown with dependencies and verification criteria. See the Planning Engine section for the full breakdown of each step.

Execution Phase

Tasks from the plan are executed in dependency order. Each task starts a fresh AI session with only the context it needs — the relevant PRD sections, blueprint decisions, file references, and learnings from previous tasks. This prevents context window pollution and ensures task 50 runs with the same precision as task 1. See Execution Engine for details.

Review & Ship

After execution completes, you can ask questions about the implementation, report bugs for the AI to fix, and review diffs. When satisfied, say "merge" and Afkode handles the git operations. See Review & Ship for the full flow.

The Kanban Board

The Kanban board is your command center. Every feature in your project is represented as a card that moves through lanes as it progresses from idea to production. Cards transition automatically based on system events — you don't need to drag them manually (though you can).

Lanes & Cards

The board has 7 lanes, each representing a stage in the feature lifecycle:

Card Indicators

• Pulsing dot — The feature is actively running (planning or execution in progress). Disappears when paused or idle.
• Pause badge — You manually paused the feature, or an error paused it automatically. Orange for manual pause, red for errors.
• Inactive pill — The feature is "in progress" but not actively executing right now (e.g., waiting in the auto-proceed queue).
• Health pills — Show worktree state: "uncommitted changes" (warning) or "merge ready" (green check).
• Receipt stats (merged cards) — Shows total TIME (planning + execution), TOKENS used, and TASKS completed. Click "Full Stats" for per-task breakdown.

Drag & Drop

You can drag cards between lanes to manually change status. Two rules:

• Locked lanes (Planning in Progress, Execution in Progress) cannot be dragged FROM — you can't manually stop a running process by dragging.
• Dragging to Merged triggers the actual git merge operation. The card only moves if the merge succeeds.

Working on Multiple Features

Afkode supports true parallel development. You can plan and execute multiple features at the same time — even across different projects.

How Worktrees Create Isolation

When you start planning a feature, Afkode creates a dedicated git worktree — a full copy of your project branched from your main branch at that moment. This is important to understand:

• The worktree is a snapshot of your main branch at the time planning starts
• Whatever code is in your main branch at that moment becomes the base the feature is built upon
• Each feature gets its own worktree, its own branch, its own AI sessions, and its own progress tracking
• Features don't see each other's changes until they're merged back to main

What You Can Do Simultaneously

• Plan one feature while another is executing
• Execute multiple features in parallel (each in its own worktree with its own AI session)
• Work on features from different projects at the same time
• Switch between projects while executions continue in the background
• Review one feature while another is still building

When to Use Parallel Features vs. One Bigger Feature

Parallel features work best when the features touch different parts of the codebase. When features overlap — modifying the same files, the same components, or the same logic — you'll face merge conflicts because each worktree branched from the same point and evolved independently.

Parallel is ideal for:

• Feature A works on the auth system while Feature B builds a dashboard page
• Feature A adds API endpoints while Feature B redesigns the settings UI
• Features across different projects entirely

One bigger feature is better for:

• Multiple changes to the same component (e.g., adding filters + pagination + sorting to the same table)
• Changes that share database migrations (two features adding columns to the same table will conflict)
• Work that has sequential dependencies (Feature B needs code that Feature A creates)

Example: The Right Way

Example: What to Avoid

If Features Do Overlap

If you've already started parallel features that touch the same areas, it's not a disaster. During the review and merge phase, the merge operation pulls the latest main into the feature branch. If Feature A merged first, Feature B's merge will surface any conflicts. The AI can help resolve simple conflicts, and you can handle complex ones manually. But it's always easier to avoid this by scoping features to different areas of the codebase.

Model Assignment Timing

This is an important detail to understand: model assignments are resolved at the moment each activity runs, not when a feature is created.

When you configure "Planning → PRD Structure → Claude Opus" in Settings → Models, that assignment is a global app setting. It applies to whichever feature reaches the PRD Structure phase next — not to a specific feature.

How This Works in Practice

Example 1: Changing models mid-flight

• Feature A starts planning with Claude Opus assigned to PRD Structure
• While Feature A is executing, you change PRD Structure to Claude Sonnet in Settings
• Feature B starts planning → its PRD Structure phase uses Claude Sonnet
• Feature A's execution continues unaffected (it already passed the PRD phase)

Example 2: Multiple features, same settings

• You have Batch QC assigned to Claude Opus 4.7 Max
• Feature A reaches its QC-1 task → uses Claude Opus 4.7 Max
• Feature B reaches its QC-1 task 10 minutes later → also uses Claude Opus 4.7 Max
• Both resolve the same global assignment at their respective execution time

Example 3: What NOT to do

• Feature A is in execution, about to start its QC-1 task
• You change Batch QC from GPT-5.4 xhigh to Claude Haiku to save cost
• Feature A's QC-1 now runs with Haiku — lower quality verification
• If you wanted Opus for Feature A's QC, you should have waited until after it ran

AI Subscriptions & Token Costs

Afkode is designed to free your time. You describe what you want, answer a few questions, and leave while the system plans, implements, and verifies your feature end to end. To do this thoroughly — deep codebase analysis, structured documents, real tests, full verification — it uses significantly more tokens than a typical interactive AI session. Here's how to set yourself up for success.

The Simple Setup

One subscription is enough — either Claude Max (Anthropic) or Codex Pro (OpenAI). With the recommended model configuration, a single subscription can typically deliver 3–5 complex features per week.

If you can only get one subscription, either Claude Max or Codex Pro can work well. Claude gives you Claude Opus 4.7 for planning, architecture, and QC at Max effort. Codex gives you GPT-5.4 for implementation and verification depth. Pick the provider you already prefer operationally — both can cover the full pipeline well with the recommended model configuration.

With two subscriptions (Claude + Codex), you get the best of both worlds: Claude Opus for architecture and planning decisions, Codex for implementation and QC. The model assignment system lets you mix them freely.

What Affects Token Usage

API Keys

You can also connect providers via API key or through OpenCode. API access is pay-per-token, so costs scale directly with usage. For the volume Afkode generates, subscriptions are almost always more cost-effective for regular use. API keys make sense for occasional use or accessing specific models not available through subscriptions.

How Long Things Take

Afkode is built for thoroughness, not speed. The entire point is to describe what you want and come back to a fully implemented, tested, and committed feature. The system takes its time because it's doing the work properly — analyzing patterns, generating structured plans, writing real code, and running real tests.

Planning

End-to-end planning typically takes 60–90 minutes. But you're only needed for the first 5–10 minutes — to write your feature description and answer 3–8 clarifying questions. After that, the 8-phase planning engine runs autonomously: analyzing your codebase, generating the PRD with parallel sections, building the Technical Blueprint, and breaking everything down into tasks with dependencies and verification criteria.

Execution

Execution time depends on the number of tasks and their complexity. Based on our testing:

For a typical 10-task feature (8 implementation + 1 batch QC + 1 feature QC), expect roughly 3–4 hours of total execution time.

Total Feature Delivery

Combining planning and execution, a complex feature typically takes 5–8 hours from description to merge-ready code. Your active involvement: about 10 minutes at the start (description + Q&A) and 5–15 minutes at the end (review + merge). Everything in between runs autonomously.

This is the point of Afkode: you spend 15–25 minutes of your time, and the system does 5–8 hours of engineering work while you focus on something else. It's not fast — it's thorough.

Open Source Models

Afkode supports open source models through OpenCode and Kimi. If a model is accessible through these providers, you can use it in Afkode for any activity slot.

Open source models offer a significantly lower cost than commercial alternatives. If you're cost-conscious or working on simpler features, they can be a viable option for some activity slots — especially lightweight tasks like spec generation, categorization, or review Q&A.

That said, we want to be transparent: for complex planning, implementation, and especially QC work, current state-of-the-art commercial models still produce noticeably better results. Architecture decisions, deep codebase analysis, and thorough test verification require the strongest reasoning capabilities available today.

We believe in open source models and we actively support them because we believe they will reach parity with leading commercial models in the near future. We want our users to be ready when that happens — and to experiment freely in the meantime. The model assignment system makes it easy to try open source models on specific activities while keeping commercial models where they matter most.

When to Use Afkode

Afkode is not the right tool for everything. It's built for work where planning, context management, and verification matter. Here's how to think about it across the spectrum of day-to-day development tasks.

The Pattern

Afkode's value increases with:

• Number of files touched — more files = more context to manage = more value from curated context per task
• Cross-layer work — frontend + backend + database + tests = more value from structured planning
• Testing importance — the more critical the code, the more value from the verification loop
• Repetitiveness — boring, consistent work that humans rush through but Afkode handles patiently
• Dependency complexity — the more things that need to happen in the right order, the more value from the task graph

When Not to Use Afkode

• Exploratory R&D — if you don't know what you want yet, the system can't plan for it. Experiment first, then bring the clear spec to Afkode.
• Visual design tweaks — "make it look better" is subjective. Afkode works with concrete requirements, not aesthetic judgment.
• Quick one-off fixes — if it takes 30 seconds in your editor, opening Afkode is overkill.

Always Know What's Happening

Even though Afkode runs autonomously after your initial request, you are never in the dark. Every autonomous phase provides real-time visibility so you can verify what the system is doing at a glance — without interrupting it.

During Planning

Phase Progress Stepper

A vertical stepper on the right sidebar tracks all 8 planning phases. Each phase shows one of four states:

• Idle — gray circle, phase hasn't started yet
• Active — pulsing green dot with glow, currently running. Shows a live subtitle of what the AI is doing (e.g., "Reading: src/auth/login.ts" or "Writing requirements...")
• Complete — green checkmark, phase finished successfully
• Failed — red X, with retry option

Connecting lines between phases change color as work progresses — green for completed, gradient for the active transition, gray for what's ahead.

Live Content Streaming

During the early phases (analysis, spec, categorization, Q&A), the AI's output streams into the chat panel as real-time message bubbles. You can read the analysis, see the specification being formed, and watch questions being generated — all as it happens.

Parallel Section Generation (PRD & Blueprint)

When the PRD and Blueprint generate in phases 5 and 6, the view switches to a split-pane document viewer:

• Left panel: section list with status icons — spinning for in-progress, checkmark for complete, pending for queued. A counter shows progress (e.g., "4 / 10 sections").
• Right panel: click any completed section to read its content immediately, rendered as formatted markdown. Sections appear as they finish — you don't wait for all of them.
• Unread indicators: newly completed sections show an orange dot so you can spot fresh content.

Session Timer

An elapsed timer in the sidebar header shows how long planning has been running, updated every second.

During Execution

Task Sidebar (Always Visible)

The right sidebar shows every task in the feature with a clear status icon:

• Green checkmark — completed, with commit hash, file count, token usage, and duration shown below
• Half-filled green circle — currently executing
• Amber pause icon — paused
• Red warning — error
• Gray circle — pending, hasn't started yet

At a glance, you can see what's done, what's running, and what's left. The sidebar also shows a live elapsed timer and running token counts (input and output) for the current task.

Subtask Progress (Live)

Inside the executing task view, every subtask is listed with real-time status updates. As the AI works through subtasks, each one transitions from pending (empty checkbox) to in-progress (spinning indicator) to completed (green checkmark). The view auto-scrolls to follow the active subtask so you always see what's happening right now.

Streaming AI Output

The AI's response streams into the center panel as it works — you can read its reasoning, see the code it's writing, and watch commands being executed in real time. Each chunk appears as a finalized message bubble with full markdown rendering.

Navigate Freely Without Losing Context

While a task executes, you can:

• Click any completed task in the sidebar to review its diff, metrics, and execution log
• Switch to the documents view to re-read the PRD, Blueprint, or planning Q&A
• Switch back to the executing task at any time — the stream continues where you left it

The task sidebar with controls (pause, resume, stop) remains visible in all views, so you always have access to execution status and actions regardless of what panel you're looking at.

How Planning Works

The planning engine follows a structured 8-step process. Each step produces specific outputs that feed the next. All state is persisted to a local database, so planning survives app crashes and restarts.

Step 1: Initialization

Sets up the workspace for the feature. No AI interaction happens here.

• Creates a dedicated git worktree with its own branch, isolated from your main branch
• Prepares the planning workspace where all documents will be generated
• Validates that the system has the permissions and disk space to proceed

Step 2: Codebase Analysis

The AI explores your project to understand how it's built before writing any plans. This is what allows the system to generate plans that work with your codebase instead of against it.

• Discovers your languages, frameworks, and project structure
• Maps existing patterns: how you handle state, build UI, integrate APIs, manage auth, persist data, handle errors, write tests, and log
• Identifies anti-patterns — approaches that exist in the codebase but should not be replicated
• Generates a short feature title for the Kanban board

Produces: A pattern catalog that all subsequent phases reference — ensuring the PRD, Blueprint, and Tasks align with how your project actually works.

Step 3: Specification

Generates a structured specification that captures the technical scope of the feature based on the analysis.

• Defines what the feature touches: which parts of the system are affected, what dependencies exist, and where it integrates with existing code
• Uses structured output for consistency, ensuring the spec is machine-readable for downstream phases

Produces: A technical specification that becomes the foundation for both the PRD and the Blueprint.

Step 4: Categorization

Classifies the feature and generates targeted clarification questions based on what's missing or ambiguous in your request.

• Detects which areas of the system are affected: frontend, API, database, auth, etc.
• Generates context-aware questions with multiple-choice options tailored to your specific codebase — not generic templates

Produces: A set of focused questions designed to fill scope gaps before any documents are written.

Step 5: Q&A

An interactive conversation where you answer the system's clarifying questions. This is the only phase that requires your input.

• Questions are presented one at a time in the chat interface
• You can select from options or provide free-form answers
• You can attach files to provide additional context
• The AI maintains conversational context across all questions

Produces: Your answers, which directly shape the requirements, architecture decisions, and task scope in the next three phases.

Step 6: PRD Generation

Generates the Product Requirements Document — the "what to build" specification. This is where your feature description and Q&A answers become formal, traceable requirements.

• Sections are generated in parallel for speed
• Each section is generated with full awareness of your codebase and requirements
• Sections include functional requirements, non-functional requirements, acceptance criteria, user stories, and scope boundaries
• Every requirement gets a unique ID that traces all the way through to tasks and verification tests

Produces: A complete requirements document where every requirement is identifiable, traceable, and testable.

Step 7: Blueprint Generation

Generates the Technical Blueprint — the "how to build" architecture document. This translates the PRD's requirements into concrete implementation decisions.

• Sections are also generated in parallel
• References the PRD to ensure every requirement has a corresponding implementation approach
• Covers architecture decisions, component design, integration contracts, data models, and state management

Produces: An architecture document that tells the execution engine exactly how to implement each requirement — which patterns to follow, which components to create, and how they connect.

Step 8: Task Breakdown

Breaks the feature into executable tasks with subtasks, dependencies, and verification criteria. This is what the execution engine actually runs.

• Tasks are generated with dependencies, verification criteria, and detailed subtask breakdowns
• Each task includes specific subtasks and how to verify the work is correct
• QC verification tasks are automatically placed at the right points in the task sequence
• Coverage verification ensures every PRD requirement maps to at least one task
• Simple features produce ~5 tasks. Complex features can produce 50+.

Produces: A complete task graph with dependencies, coherence groups (related subtasks that must stay together), and verification criteria ready for execution.

How Context Works

This is the core of what makes Afkode different from simply prompting an AI. Instead of dumping your entire codebase into a chat window, Afkode assembles exactly the right context for each task.

Each task receives a curated briefing assembled from your planning documents — only the requirements, architecture decisions, and project context relevant to that specific task. The system knows exactly which pieces of the plan each task needs and filters out everything else.

No guesswork. No hoping the model remembers. No irrelevant context cluttering the window.

Fresh Session Per Task

Each task starts a brand new AI session with its curated context. No accumulated conversation. No context window pollution. No degradation.

Task 50 runs with the same precision as task 1 because the context engine knows exactly what each task needs. Previous task outputs don't bleed into subsequent tasks — only the explicit learnings captured in the runtime journal carry forward.

Acceptance Criteria → Tests

During planning, every requirement gets acceptance criteria. During task generation, these criteria are mapped to specific verification steps.

When QC tasks run, they systematically check each criterion against the implementation, write targeted tests (unit, integration, and e2e), and report coverage — which criteria passed, which have gaps.

Batch QC tasks (QC-1, QC-2) verify groups of related tasks. The final Feature QC runs comprehensive verification across the entire feature, checking for regressions and cross-task issues.

Runtime Journal

Two files capture learnings during execution and persist them for future tasks:

Operational Journal

Captures context from every previous task — decisions made, deferred work, issues encountered and how they were resolved, and integration notes. Each task reads this journal before starting and updates it before committing, so the next task knows what came before.

Testing Knowledge Base

Captures test infrastructure discoveries that save future tasks time — undocumented prerequisites, incorrect existing instructions, anti-patterns in existing tests, and environment setup steps. This knowledge accumulates over time, so later tasks and features don't hit the same walls.

Compounding Knowledge

The more you build, the smarter the system gets — but not through fine-tuning or hidden training. Knowledge compounds through persistent artifacts:

• Testing knowledge persists project-wide — infrastructure learnings from any feature benefit all future features
• Operational context guides subsequent tasks within a feature
• Codebase patterns captured during analysis inform all future planning
• Each QC task contributes test infrastructure knowledge

Feature 10 benefits from everything learned during features 1–9. The system gets smarter with every feature you build — not through training or fine-tuning, but through persistent, structured knowledge that each fresh AI session reads before starting work.

How Execution Works

Execution takes the task breakdown from planning and implements each task using your configured AI provider. Tasks auto-proceed through the entire queue — once you click "Execute All," you can leave.

1. Tasks load from the database in dependency order
2. The context seed is assembled with the relevant PRD sections, blueprint decisions, and task details
3. A fresh AI session is started with the curated context
4. The AI implements subtasks sequentially, reporting progress as it goes
5. On completion, changes are committed to the feature branch
6. The next task starts automatically — no manual intervention needed

While a task is executing, you can watch in real time: the subtask checklist updates as each step completes, and the AI's tool activity (file reads, writes, shell commands) streams live. Or you can close the app entirely — execution state is persisted and resumes on restart.

Task Ordering & Dependencies

Tasks run in execution order, determined during planning based on dependencies. A task won't start until its dependencies are complete.

Coherence groups are sets of subtasks that must be implemented together because they're tightly coupled. For example, a database migration and the code that uses the new schema should be in the same coherence group to avoid broken intermediate states.

Completed Task View

When a task finishes, the completed view gives you full transparency into what was built. You can review any completed task at any time by clicking it in the tasks sidebar.

Metrics

A summary grid at the top shows key stats for the task:

• Duration — how long the task took to execute
• Input / Output Tokens — how much context was sent and how much the AI produced
• Cost — the AI provider cost for this task
• Subtasks completed — count of subtasks that finished

Subtask Checklist

Every subtask defined during planning is shown with a green checkmark when completed. This lets you verify that the AI actually addressed every step in the plan, not just the easy ones.

Commit Details

Each completed task produces a git commit. The view shows:

• Commit hash — the short SHA linking to the exact code change
• Commit message — a descriptive message summarizing the work
• Date — when the commit was created
• Stats — files changed, lines added, lines deleted

Full Code Diff

Below the commit info, a full unified diff shows every line of code that was added, modified, or removed — per file, with syntax-highlighted line-by-line changes. Green lines are additions, red lines are deletions. This is the same diff format you'd see in a pull request.

Execution Log (3 Tabs)

The execution log provides deep visibility into how the AI worked:

• Response — the AI's formatted text output with explanations and reasoning, rendered as readable prose with syntax-highlighted code blocks
• Tool Use — every tool call the AI made (file reads, file writes, shell commands), listed with expandable details showing the full input for each call. Useful for understanding exactly what the AI did and in what order.
• Thinking — the AI's extended thinking process (when available), showing internal reasoning before it took action

QC & Verification Tasks

The planning engine automatically inserts verification tasks at integration boundaries:

QC tasks use the same verification YAML files that trace back to PRD requirements. Every acceptance criterion (AC-*) has specific testing notes and edge cases that guide the QC agent through the verification loop. We strongly recommend Claude Opus 4.7 Max or GPT-5.4 XHigh for the QC slots — see recommended models for details.

Pause, Resume & Cancel

• Pause: Freezes the AI process. For CLI-based providers, the process is suspended with a signal and resumes exactly where it left off. No work is lost.
• Resume: Unfreezes the process and continues execution.
• Cancel: Stops the current task. The task can be restarted later from a fresh session.

All execution state is persisted to the database. If the app crashes mid-execution, you can resume when it restarts.

Git Worktrees

Every feature runs in its own git worktree — an isolated copy of your repository with its own branch. This means:

• Your main branch is never modified by AI-generated code
• Multiple features can be developed in parallel without conflicts
• Each completed task produces a real git commit on the feature branch
• If something goes wrong, your main branch is untouched

Worktrees are created inside a .worktrees/ directory in your project root. Configuration files (like .env) are automatically symlinked from your main repo so the worktree can run without re-installing dependencies.

Branch Management

Feature branches follow the pattern feat/<feature-slug>. If a branch name already exists, a numeric suffix is added automatically (e.g., feat/auth-2).

During execution, each task produces at least one commit with a descriptive message. You can see all commits in the review panel.

Worktree Cleanup

Worktrees are cleaned up automatically by a background health check that runs every hour:

• If a feature branch is fully merged into main, the worktree and branch are deleted
• If a feature is archived, its worktree is cleaned up
• Cleanup is idempotent — it succeeds even if the worktree was already removed
• Worktrees are never deleted during a crash — they persist on disk until explicitly cleaned up

Review Flow

After execution completes, the review panel opens with a summary of what was built — duration, tokens used, files modified, cost, and a visual diff breakdown. From here, you interact with the AI through a single unified chat. Just type naturally.

Behind the scenes, Afkode classifies every message you send into one of three intents and routes it to the right session with the right context:

You don't need to think about which mode you're in. The classification happens automatically based on what you say, and the conversation flows naturally as a single thread. If you ask a question, then report a bug, then merge — it all appears in one continuous timeline.

Intent Detection

The system uses a multi-tier classification approach:

1. AI classification — Your message is analyzed to determine intent with a confidence score. If confidence is high, the result is used immediately.
2. Pattern matching — If AI classification is slow or uncertain, keyword patterns are used as a fast fallback (e.g., "fix", "bug", "error" → bugfix; "what", "why", "how" → Q&A; "merge", "ship", "push" → merge).
3. Context continuation — For very short messages ("yes", "ok", "do it"), the system looks at the recent conversation to inherit the intent from what you were just discussing.

Context Awareness Across Intents

Each intent session builds on the ones before it:

• Q&A receives the full planning documents (PRD, Blueprint) and execution results
• Bug Fix receives everything Q&A has, plus a summary of your Q&A conversation so it knows what you've already discussed
• Merge receives everything above, plus summaries from both Q&A and Bug Fix sessions, plus the full git context (branch, recent commits, staging status)

This means by the time you say "merge," the AI has complete awareness of your questions, any bugs you reported and how they were fixed, and the current state of the branch.

Ask Questions

The Q&A session is read-only — the AI can read your code and planning documents to answer questions, but it cannot modify any files. This gives you a safe way to understand the implementation before deciding what to do next.

The AI has access to:

• The PRD and Technical Blueprint from planning
• Execution results and all files that were changed
• The project codebase (it can read any file to answer your question)

Ask things like: "Walk me through the auth flow", "Why didn't you use the existing UserService?", "What would break if I removed this component?"

Report Bugs

The Bug Fix session follows a structured protocol designed to prevent reckless changes:

If you had a Q&A conversation before reporting the bug, the bug fix session knows about it. Context from your questions carries forward so you don't need to repeat yourself.

Merge to Main

When you're satisfied with the implementation, say "merge", "ship it", or "let's push". The merge flow has built-in safety at every step:

Session Continuity

Review sessions persist across app restarts. If you close the app mid-conversation and reopen it later, the full conversation history is restored and the AI picks up where you left off — including all context from prior Q&A and bug fix discussions. Your review progress is never lost.

Testing Your Changes Locally

Before merging, you can test the feature manually by running your project from the worktree directory. The worktree is a full copy of your project with the feature's changes applied — you can cd into it and run it like you normally would.

• Find the worktree path — it's shown at the bottom of the docs view. Click to copy it.
• Ask the AI — in the review chat, ask "how do I run this locally?" and the AI will tell you the exact commands for your project (install dependencies, start dev server, run tests, etc.).
• Run from the worktree — open a terminal, navigate to the worktree path, and launch your project as you normally would. You're testing the feature in isolation from your main branch.

Merge & Deployment

When you say "merge" in the review chat, Afkode merges the feature branch into your main branch and pushes to your remote repository. That's where Afkode's job ends.

Deployment is not handled by Afkode. Every project deploys differently — Vercel, AWS, Docker, manual scripts, CI/CD pipelines — and Afkode doesn't make assumptions about yours. What you get is tested, committed, merged code on your main branch, ready for whatever deployment process you have.

How Afkode Compares

Most AI coding tools offer planning, context management, and testing — but the implementations are very different. The tables below break down each dimension so you can see exactly where the approaches diverge.

Based on publicly available documentation as of April 9, 2026. AI coding tools evolve fast — if you spot something outdated, let us know.

What happens after you describe a feature?

Who’s responsible for getting context right?

Does quality hold up as the feature grows?

How do you know it built what you asked for?

Does today’s feature make tomorrow’s smarter?

How much model configuration do you manage?

The System Loop

Individually, each capability above has value. Together, they form a reinforcing chain where each one feeds the next.

Planning produces structured documents. Context assembly derives per-task briefings from them. Fresh sessions load that curated context instead of degraded conversation history. QC tasks run with full precision at any position in the sequence because each one starts fresh. Testing discoveries persist in a knowledge base that the context engine includes in subsequent briefings.

This chain is what makes the individual capabilities interdependent. Without structured planning, there is nothing to assemble context from. Without context assembly, fresh sessions start blank. Without consistent QC, the knowledge base captures unreliable data. Without the knowledge base, every feature starts from zero. Each piece exists because the others need it.

Quick Reference

A simplified yes/no view across all features. The per-section tables above show more nuance. See the interactive table on the landing page for the visual version.

Based on publicly available documentation as of April 9, 2026.