dotagent

dotagent is a framework for running AI-assisted software development with explicit gates, durable project memory, and human ownership of the codebase.

It is opinionated on purpose. The goal is not unrestricted autonomous coding. The goal is to keep serious codebases understandable, resumable, and reviewable while using agents aggressively.

Disclaimer Regarding Dotagent's Status

dotagent is stable and in maintenance mode.

I came to this project to build disciplined agent-assisted development tools before many of these workflows and capabilities were available natively in coding runtimes such as Codex, Claude Code, and others.

Since then, runtime support for parallel agents, deep review, session management, and agent workspaces has caught up with the curve.

I will keep this framework available and maintained for existing users who like its opinionated namespace model, workflow gates, and runtime-portable project memory.

New users should first evaluate the native capabilities of their preferred runtime before adopting the dotagent framework.

Future development will focus on compatibility, documentation, and small fixes rather than major new features.

I truly enjoyed developing and using this framework. If you were here with me on this journey, I hope it helped shape your own work during these exciting, chaotic times for us coders.

My

Quickstart

Install:

npm install -g @koryto/dotagent

Initialize:

Choose only the runtimes you actually use.

Supported runtimes: codex, claude, opencode, copilot

dotagent init --runtimes codex,claude
dotagent doctor

Start a session:

Fetch the session_id from your runtime status command.

In Codex:

/status
$dotagent-init session_id=<id_from_status>

In Claude Code:

/status
/dotagent:init session_id=<id_from_status>

First Setup

The first runtime session will usually point out that .agent/project/PROJECT.md still needs project-specific context.

Fill it before expecting deep project-aware work. It should capture:

• what the project is
• important commands and workflows
• coding and review conventions
• project-specific constraints the agent should respect

Keep it concise. The goal is stable project context, not a full wiki.

Why This Exists

Most agent wrappers optimize for speed and autonomy.

This framework optimizes for:

• controlled execution
• durable project memory
• resumable multi-session work
• architecture awareness
• harness structure for serious agent execution
• production-grade review discipline

Agents can write code quickly, but humans still need to own the system. If the structure around the agent is weak, the codebase degrades faster than it did under normal human-paced development.

Core Model

The framework standardizes project work into namespaced markdown contracts:

• project/ - project constitution and standing rules
• specs/ - intended design and architecture
• systems/ - implemented reality
• tasks/ - task-local working memory
• state/ - current session state and session history
• workflows/ - gated execution workflows
• skills/ - on-demand procedural guidance
• playbooks/ - optional multi-file operational packages

Philosophy

• keep hot-loaded files small and stable
• separate intended design from implemented reality
• treat task artifacts as local working memory, not durable truth
• require review before calling work done
• keep the human in control of architectural decisions and risky execution

Workflows

standard

Default implementation workflow:

1. Planning
2. Implementation
3. Review
4. Verification
5. Summary

patch

Lightweight workflow for small, low-risk fixes:

1. Scope
2. Patch
3. Sanity
4. Summary

Use standard by default when the workflow is unspecified.

For implementation work, standard also requires an approved branch/worktree and approved writable boundary before code changes begin.

Multi-Agent

dotagent now supports parallel top-level agent work against the same project.

The multi-agent model stays human-governed:

• each runtime session claims its own session state file under state/sessions/
• dotagent claim-state provides deterministic session claim/create behavior
• implementation work must use an approved branch/worktree and an approved writable boundary
• the default implementation worktree location is .worktrees/<repo_name>_<session_id> unless the user explicitly approves a different path
• stale session files can be archived or cleaned up with dedicated CLI commands

Playbooks

playbooks/ is an optional namespace for operational packages that are too large, stateful, or role-dependent to fit cleanly into a single skill.

Use a playbook when the work needs multiple roles, rounds, durable packet files, or more structure than a normal workflow can provide.