> ## Documentation Index
> Fetch the complete documentation index at: https://afk.arpan.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer Guide

> Maintainer workflow for changing AFK itself.

This page is for contributors changing the AFK framework. If you are building an application with AFK, start with [Quickstart](/library/quickstart) or [Building with AI](/library/building-with-ai).

## Local setup

AFK targets Python 3.13+.

```bash theme={null}
python -m pip install --upgrade pip
python -m pip install -e . pytest
```

Common commands:

```bash theme={null}
PYTHONPATH=src pytest -q
PYTHONPATH=src pytest -q tests/agents/test_agent_runtime.py
PYTHONPATH=src pytest -q tests/llms/test_llm_settings.py
PYTHONPATH=src pytest -q tests/queues/test_queue_factory.py
ruff check src tests
ruff format src tests
```

Preview docs:

```bash theme={null}
./scripts/docs_dev.sh
```

Regenerate agent-facing docs and skill indexes:

```bash theme={null}
./scripts/build_agentic_ai_assets.sh
```

Install the repository skills with Vercel's Skills CLI:

```bash theme={null}
npx skills add https://github.com/arpan404/afk --skill afk-coder
npx skills add https://github.com/arpan404/afk --skill afk-maintainer
```

Use `afk-coder` when building with AFK. Use `afk-maintainer` when reviewing or changing AFK itself.

## Repository boundaries

| Package                                                 | Responsibility                                                                |
| ------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `afk.agents`                                            | Agent definitions, policy, prompts, skills, lifecycle, workflow, A2A          |
| `afk.core`                                              | Runner, interaction providers, streaming handles, telemetry contracts         |
| `afk.llms`                                              | Provider-portable LLM runtime, adapters, retry/timeout/cache/routing policies |
| `afk.tools`                                             | Typed tools, decorators, registry, sandboxing, output limiting                |
| `afk.memory`                                            | Memory stores, checkpoints, retention, compaction, vector helpers             |
| `afk.queues`                                            | Async task queues, execution contracts, workers, retry/DLQ behavior           |
| `afk.observability`                                     | Telemetry collectors, projectors, exporters                                   |
| `afk.mcp`, `afk.messaging`, `afk.debugger`, `afk.evals` | Optional integration and quality layers                                       |

Keep the Agent/Runner/Runtime boundary intact:

* agents are configuration;
* runners execute;
* tools, memory, queues, LLM adapters, and telemetry provide runtime capabilities.

## Change workflow

1. Identify the public contract affected by the change.
2. Inspect the existing module and tests before editing.
3. Make the smallest behavior change that preserves package boundaries.
4. Add or update focused tests for success and failure paths.
5. Update docs when behavior, public imports, configuration, env vars, or examples change.
6. Regenerate agent-facing docs when docs navigation, snippets, or skill metadata change.

## Documentation workflow

User-facing docs must:

* import from public package surfaces such as `afk.agents` and `afk.core`;
* explain behavior before internals;
* use Python 3.13+ guidance;
* distinguish `afk-py` distribution install from `afk` imports;
* include new pages in `docs/docs.json`;
* keep examples aligned with current `AgentResult`, `RunnerConfig`, and `FailSafeConfig` fields.

Maintainer docs may reference internal files, but should state which public contract or invariant is being protected.

## High-risk areas

Use targeted tests when touching:

| Area                                                      | Risk                                                        |
| --------------------------------------------------------- | ----------------------------------------------------------- |
| `src/afk/core/runner/`                                    | execution loop, checkpoints, resume, policy/failure routing |
| `src/afk/core/streaming.py`                               | stream events and handle lifecycle                          |
| `src/afk/tools/core/base.py`, `src/afk/tools/registry.py` | tool invocation semantics                                   |
| `src/afk/tools/security.py`                               | sandbox, secret scope, output limiting                      |
| `src/afk/llms/runtime/`                                   | retries, circuit breakers, rate limits, caching, routing    |
| `src/afk/memory/`                                         | persistence, checkpoint keys, compaction, vector search     |
| `src/afk/queues/`                                         | execution contracts, retry/DLQ, worker lifecycle            |
| `src/afk/agents/a2a/`                                     | auth, delivery guarantees, protocol compatibility           |

## Public API checklist

Before changing exports or constructor fields:

* update package-level `__all__`;
* update [API Reference](/library/api-reference);
* update [Configuration Reference](/library/configuration-reference) if defaults changed;
* update snippets that use the changed field;
* add public-import tests where useful.

## Next steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="layer-group" href="/library/architecture">
    Package boundaries and runtime flow.
  </Card>

  <Card title="Public API Rules" icon="book" href="/library/public-imports-and-function-improvement">
    Maintainer rules for stable imports and docs examples.
  </Card>

  <Card title="Tested Behaviors" icon="check-circle" href="/library/tested-behaviors">
    Behaviors that tests protect.
  </Card>

  <Card title="Full Module Reference" icon="map" href="/library/full-module-reference">
    Generated source-level symbol map.
  </Card>
</CardGroup>