AI Agent Skills & Workflow Tools
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Forze incorporates a robust system of AI Agent Skills designed to assist engineers building applications that depend on the Forze framework. These skills provide Large Language Models (LLMs) and AI assistants with the necessary context, patterns, and anti-patterns to correctly implement Domain-Driven Design (DDD) and Hexagonal Architecture using Forze primitives. Instead of focusing on framework internals, these tools target the application layer, ensuring that agents follow correct wiring, specification authoring, and integration patterns.
The project also provides a clear Agent Workflow through architectural routing guides like AGENTS.md. This ensures that any AI agent operating within the repository or an application using Forze can identify the "source of truth" for various tasks—ranging from code changes and testing to documentation and release management.
Sources: skills/AUTHORING.md:6-12, AGENTS.md:6-14, skills/README.md:3-5
Agent Skills Architecture
The Agent Skills system follows the AgentSkills.io format. Each skill is defined in a SKILL.md file within the skills/ directory. These are not published as installable Python packages but are instead picked up by specialized tools (like npx skills add) to be injected into an AI assistant's context.
Sources: skills/AUTHORING.md:3-4, skills/README.md:8-12
Skill Structure
A standard Forze Agent Skill consists of the following components:
- YAML Frontmatter: Contains the skill
nameand adescriptionindicating when the agent should activate it. - Patterns & Examples: Minimal code examples demonstrating the correct way to use specific Forze features.
- Anti-patterns: Critical warnings about mistakes an application team might make (e.g., importing adapters into handlers).
- References: Links to published documentation and related sibling skills.
Sources: skills/AUTHORING.md:21-34
Core Skill Categories
The project categorizes skills based on functional domains of the framework:
| Skill Name | Focus Area |
|---|---|
forze-framework-usage | ExecutionContext, ports, transactions, and identity context. |
forze-domain-aggregates | Document aggregates, mixins, validators, and logical specs. |
forze-wiring | Runtime, DepsRegistry, lifecycle, and operation pipelines. |
forze-specs-infrastructure | Mapping logical names to Postgres/Mongo/Redis/S3/Queue configs. |
forze-fastapi-interface | FastAPI context, generated routes, and middleware. |
forze-temporal-workflows | Durable workflow specs and Temporal ports. |
| Sources: skills/README.md:18-40 |
Workflow Routing & Source of Truth
The repository utilizes AGENTS.md (and a mirrored CLAUDE.md) as a routing guide for AI agents. This prevents agents from inventing policies or using outdated context by directing them to canonical files for specific task types.
Sources: AGENTS.md:3-5, CLAUDE.md:3-5
Source of Truth Map
This diagram shows how an AI agent should navigate the repository to find authoritative rules before performing modifications.
Sources: AGENTS.md:16-56, CLAUDE.md:16-56
Development Workflow Tools
Forze leverages several external and internal tools to maintain code quality and facilitate agent automation.
Repository Map (High-Signal Paths)
Agents are instructed to look at specific paths for framework layers:
src/forze/: Core framework layers (application, domain, base).src/forze_kits/: Pre-built wiring above contracts (aggregates, handlers).src/forze_identity/: Identity plane (authn, authz, OIDC).src/forze_mock/: In-memory adapters for testing.src/forze_<integration>/: Optional integration packages (Postgres, Redis, etc.).
Sources: AGENTS.md:63-80, CLAUDE.md:63-80
Quality Control Commands
The justfile serves as the primary interface for quality gates. Agents MUST use these commands to validate changes:
| Command | Purpose |
|---|---|
just test | Runs unit and integration tests (excluding performance). |
just quality | Runs linting, import-linter, dead-code checks, and security scanning. |
just quality -s | Strict mode: fails on any warning or issue. |
just perf | Runs performance benchmarks (requires Docker for some). |
just build-docs | Builds the Zensical/Material documentation site. |
| Sources: CONTRIBUTING.md:31-50, AGENTS.md:112-120 |
Implementation Patterns for AI Agents
When authoring skills or performing automated refactors, agents must adhere to the project's architectural constraints defined in pyproject.toml and CONTRIBUTING.md.
Dependency Injection Pattern
AI agents must follow the "Dependencies flow inward" rule:
- Domain: Pure logic, no external dependencies.
- Application: Handlers and contracts; imports domain only.
- Infrastructure: Adapters implementing contracts; never imported by handlers.
Sources: skills/AUTHORING.md:9-15, pyproject.toml:169-175
Import Linter Contracts
The project enforces architectural boundaries via import-linter. AI agents must respect these layers:
[[tool.importlinter.contracts]]
name = "Layered `forze` package architecture"
type = "layers"
layers = ["forze.application", "forze.domain", "forze.base"]
[[tool.importlinter.contracts]]
name = "Core forze must not import forze_kits"
type = "forbidden"
source_modules = ["forze"]
forbidden_modules = ["forze_kits"]
Sources: pyproject.toml:169-182
Summary
The "AI Agent Skills & Workflow Tools" system in Forze represents a proactive approach to developer experience (DX). By providing structured skills, explicit routing guides, and automated quality gates, the framework ensures that both human developers and AI assistants can maintain the integrity of Hexagonal Architecture. Key to this system is the separation between the Logical Specification (provided in skills) and the Infrastructure Configuration (defined in the main codebase), allowing for a highly composable and testable ecosystem.
Sources: README.md:11-20, skills/README.md:3-6