Make AI coding work survive the next thread

dot-agents adds a small .agents/ workspace to any repo: durable work items, research notes, plans, and handoff prompts your agents can reuse.

Run from your repo root. Fresh installs create AGENTS.md and .agents/; syncs later preserve your work items, research, and customized project instructions.

$ curl -fsSL https://raw.githubusercontent.com/colmarius/dot-agents/main/install.sh | bash

Review first: curl -fsSL https://raw.githubusercontent.com/colmarius/dot-agents/main/install.sh | less

What it adds

your-project/
├── AGENTS.md        # project instructions for agents
└── .agents/
    ├── work/        # durable work items
    ├── research/    # reusable findings
    ├── references/  # local reference repos
    ├── skills/      # adapt, work items, planning, research
    └── scripts/     # sync updates safely

Use work items for multi-session or context-heavy work. Tiny one-shot edits may not need one.

Example work item

After asking Create a new work item for user authentication, future threads have a durable starting point.

.agents/work/feature/user-authentication/
├── index.md      # status, summary, next action
└── plan.md       # implementation tasks, when useful

# User authentication

Status: planned
Category: feature
Updated: 2026-06-22

## Summary
Add auth flows and session persistence.

## Next Action
Implement Task 1 from plan.md.

A new thread starts by reading index.md, then loads only the plan, research, or progress it needs.

How it works

Use natural-language prompts to create only the context each task needs.

Run adapt Adapt once by filling AGENTS.md with project commands, structure, and conventions.

Create a new work item for ... Start durable context under .agents/work/<category>/<slug>/.

Add only needed context Ask for research, a short requirements brief, or an implementation plan only when it helps.

Write a handoff prompt for ... Generate a scoped prompt for a fresh implementation thread that records progress as it works.

Quickstart Full Docs GitHub