Agentic Development Framework
Agentic Development Framework (ADF) is a local-first foundation for persistent, human-controlled software development workflows driven through IDE coding agents.
The project is being delivered incrementally. The current implementation provides the installable package, strict configuration validation, structured logging, safe project initialization, immutable requirements versioning, SQLite workflow state, recovery checkpoints, lifecycle commands, structured stage execution contracts, artifact validation, approval history, and Codex/Antigravity project configuration.
Requirements
- Python 3.11 or newer
Installation
Install the latest released version from PyPI:
python -m pip install agentic-development-framework
adt --help
Development setup
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
pytest
CLI
Both entry points expose the same application:
adt --help
python -m agentic_framework --help
adt --version
adt init
adt config validate path/to/config.yaml
adt requirements ingest
adt start
adt status
adt pause
adt resume
adt continue
adt stage show
adt stage task "custom stage-scoped task"
adt artifact register docs/discovery/project-overview.md
adt artifact list
adt stage complete
adt stage fail --blocked "Clarification required"
adt stop
adt review
adt approve requirements_review
adt revise requirements_review "Clarify the acceptance criteria"
adt tasks
adt command create verify-api "Run the current-stage API checks"
adt command list
The validation command prints the normalized configuration as YAML and exits with code 2 for missing, malformed, or invalid configuration.
Project initialization
Run adt init or python -m agentic_framework init from the project directory. Initialization:
- detects new and existing projects, common technologies, package managers, and parent Git roots;
- creates the ADF runtime, requirements, documentation, and IDE discovery directories;
- installs initial configuration and project guidance without replacing existing files;
- writes proposed content under
.agentic/proposals/when a generated file conflicts; and - initializes Git only when no repository is already present.
Use --path DIRECTORY to target another directory or --no-git to suppress Git initialization.
The operation is idempotent. Its latest report is written to
.agentic/reports/initialization.md.
Requirements management
Add one or more source files below requirements/inbox/, including files in nested folders,
then run:
adt requirements ingest
Each changed submission creates the next directory under requirements/versions/. The version
contains byte-for-byte source copies, SHA-256 hashes, a manifest, consolidated extracted text, a
requirement index, and initial traceability records. Existing versions are hash-validated before
use and are never updated. An unchanged inbox is reported as a duplicate without creating a new
version.
Starting with the second version, ADF compares source files and REQ-NNN requirement blocks and
writes an impact report under requirements/reports/. Added, modified, removed, and unchanged
items are reported separately, along with documentation, architecture, implementation, testing,
and approval review prompts.
Markdown, text, CSV, TSV, JSON, YAML, and reStructuredText are extracted as UTF-8 text. Other formats—including PDF, DOCX, XLSX, and images—are still preserved exactly and recorded with a clear unsupported-extraction status. Optional binary-format extractors are future work.
See docs/REQUIREMENTS_MANAGEMENT.md for the file contract and safety behavior.
Runtime state and recovery
Initialization creates .agentic/database/agentic.db as the transactional source of truth,
inspection snapshots under .agentic/state/, a JSONL event history, and checkpoint storage.
Pause and stop persist checkpoints. Resume verifies checkpoint integrity and restores the
checkpoint stage instead of trusting potentially inconsistent conversational context or snapshot
files. Execution status, current task, attempts, errors, blockers, registered artifact hashes,
approvals, and revisions survive IDE and computer restarts. Mandatory workflow approval stages
cannot advance until approval is recorded.
adt start and adt continue prepare the current stage; they do not pretend that an AI task was
completed and never silently skip deliverables. The IDE agent performs reasoning and file changes
using .agentic/execution-contracts.yaml. It registers each output with adt artifact register,
then uses adt stage complete to validate and advance. Review stages stop at
awaiting_approval until an explicit adt approve or adt revise operation. See
docs/WORKFLOW_ARCHITECTURE.md,
docs/COMMAND_REFERENCE.md, and
docs/STAGE_EXECUTION.md.
IDE configuration
ADF generates root AGENTS.md, command-named Antigravity skills under .agents/skills/, a shared
execution protocol under .agents/skills/agentic-commands/, and rules under .agents/rules/.
Antigravity indexes each skill as /<skill-name>, so /continue invokes the generated continue
skill and causes the IDE agent—not the terminal process—to execute the current stage. The Codex adapter
uses the documented root instructions and repository-local skill surfaces. The .codex/agents/
directory contains an informational compatibility note; ADF does not claim an undocumented
custom-agent file format is automatically discovered.
After adt init and adt requirements ingest, open the project root in Antigravity and type
/continue. Generated rules instruct the agent to load the current contract, perform project
discovery, create and register its four discovery documents, and persist a blocker instead of
fabricating missing answers. See docs/ANTIGRAVITY_SETUP.md and
docs/APPROVALS_AND_REVISIONS.md.
Use /adf <request> for an ad hoc request that must remain bound to the current stage and status.
To register a reusable project-specific slash command, run adt command create NAME "INSTRUCTIONS"; /NAME then performs the same persisted-state and contract preflight. Because
Antigravity reserves /resume for its conversation feature, ADF checkpoint recovery is exposed as
/adf-resume.
For projects initialized by an earlier ADF version, upgrade the package and rerun adt init.
SQLite schema migration is automatic and additive. New managed files are created, while conflicts
with customized guidance are preserved as .agentic/proposals/**/*.proposed for manual review.
Configuration
ADF configuration uses YAML and rejects unknown keys to catch mistakes early:
schema_version: 1
project:
name: example-project
mode: auto
runtime:
directory: .agentic
log_level: INFO
ide:
enabled:
- codex
policies:
allow_network: false
allow_destructive_operations: false
Runtime directories must be project-relative and cannot contain parent-directory traversal.
Logging
configure_logging() sets up readable console output and can additionally write a JSONL
event stream. Reconfiguration is idempotent and only replaces handlers managed by ADF.
See docs/IMPLEMENTATION_PLAN.md and docs/IMPLEMENTATION_PROGRESS.md for scope and status. The
maintainer release procedure is documented in docs/PYPI_RELEASE.md.
Metadata
Release files for agentic-development-framework 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentic_development_framework-0.2.0.tar.gz | 59.0 kB | With provenance | Details for agentic_development_framework-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentic_development_framework-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for agentic_development_framework-0.2.0-py3-none-any.whl |
Total release size: 104.8 kB
Release files / agentic_development_framework-0.2.0.tar.gz
| Download URL | agentic_development_framework-0.2.0.tar.gz |
|---|---|
| Size | 59.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
97a91597b9f90cfef4393f153311da4ea680c407a882fb086f2ccfddb0722cd9
|
|
BLAKE2b-256 checksum How to use checksums |
265ba089a474e7061fe49e9196fe82a3dfd0aaa7394e44ec151783ef046ddfcf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logRelease files / agentic_development_framework-0.2.0-py3-none-any.whl
| Download URL | agentic_development_framework-0.2.0-py3-none-any.whl |
|---|---|
| Size | 45.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8169cd72875d73d5a1e5dab71e398458146660fc3d87daf0acd4a86c2349d1f5
|
|
BLAKE2b-256 checksum How to use checksums |
06bb3be941e5ea3a19f6550f566e0177be50d53958298190f72c3ec08da2720e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logSecurity for agentic-development-framework 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agentic_development_framework-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.