agent-workflow-template

A structured AI agent workflow template for software teams — reduces hallucination, controls token usage, and keeps output consistent across sessions and models.

The problem

AI agents start each session with no memory of previous work. Without shared context, the same agent asked the same question on two different days can produce contradictory answers — or silently invent business rules, skip conventions, or repeat decisions the team already made.

The three failure modes teams hit most:

| Failure mode | How it happens | How this template helps | |-----------------|-------------------------------------------------------------|---------------------------------------------------| | Hallucination | Agent invents a rule, convention, or decision | Locked decisions in context/decisions.json | | Token waste | Agent loads rules irrelevant to the current task | Role profiles and flags for selective loading | | Inconsistency | Different sessions or models produce incompatible output | Single committed source of truth in .agent/ |

What this template gives you

.agent/
├── AGENT.md                  ← Agent entrypoint: project facts, sprint state, rules
├── agent.config.json         ← Structured project metadata (machine-readable)
│
├── catalog/                  ← Modular rule files loaded per task
│   ├── general.md            ← Always loaded
│   ├── backend.md
│   ├── frontend.md
│   ├── database.md
│   ├── devops.md
│   ├── mobile.md
│   ├── domain.md
│   ├── stakeholders.md
│   ├── observability.md
│   └── cross-cutting.md
│
├── context/                  ← Shared state committed to git
│   ├── stack.json
│   ├── modules.json
│   ├── decisions.json        ← Locked architectural decisions
│   ├── boundaries.json       ← Protected paths agents must not touch
│   ├── team.json
│   └── active-tasks.json     ← Current in-flight work
│
├── prompts/                  ← Reusable task prompts
│   ├── new-feature.md
│   ├── bug-fix.md
│   ├── db-migration.md
│   ├── api-endpoint.md
│   ├── component.md
│   ├── review.md
│   ├── sprint-planning.md
│   └── propose-rule.md
│
├── templates/
│   └── sprint-update.md      ← Sprint boundary checklist
│
└── profile.templates/        ← Role defaults
    ├── backend-dev.md
    ├── frontend-dev.md
    ├── devops.md
    └── fullstack.md

profile.md — personal local configuration, gitignored per developer.

Quick start

Option A — npx (recommended)

Run this inside your project directory:

npx create-agent-workflow-template

The CLI asks a few questions, copies only the catalog files your project needs, creates a profile.md for your role, and updates .gitignore automatically. Node.js 18+ required.

Option B — GitHub Template

1. Click Use this template at the top of this page
2. Name your repo and create it
3. Copy the template/ directory into your project as .agent/:

   cp -r template/ /path/to/your/project/.agent

4. Follow template/setup.md to configure the template

Option C — Clone directly

git clone https://github.com/dexterhere/agent-workflow-template.git
cp -r agent-workflow-template/template/ /path/to/your/project/.agent

Then follow template/setup.md.

How it works

Each session, point your agent at AGENT.md as its entry point. The agent reads:

1. AGENT.md — project name, sprint, repo structure, tech stack, absolute rules
2. agent.config.json — structured machine-readable version of the same facts
3. context/ files — locked decisions, protected paths, active tasks, team
4. catalog/ files — rule modules loaded based on the task type

Catalog files are loaded selectively using flags or role profiles, so the agent only loads rules relevant to the current task:

| Flag | Loads | Use when | |-------------------|-------------------------------|-----------------------------------| | --backend | catalog/backend.md | Backend / API work | | --database | catalog/database.md | Schema, migrations, queries | | --devops | catalog/devops.md | CI/CD, deployment, infra | | --frontend | catalog/frontend.md | Web UI work | | --mobile | catalog/mobile.md | Mobile app work | | --domain | catalog/domain.md | Project-specific domain rules | | --stakeholders | catalog/stakeholders.md | User roles and business flows | | --observability | catalog/observability.md | Logging, metrics, error tracking | | --all | all catalogs | Architecture reviews, broad work |

Each developer also sets up a local profile.md (gitignored) that defines their default catalog set for their role.

Setup time

| Phase | Time | |-------------------------|------------------| | Initial setup | 30–60 minutes | | Per-sprint maintenance | 10–15 minutes | | New developer onboarding| 5 minutes |

Compatible with

• Claude Code
• Cursor
• GitHub Copilot Workspace
• Any agent tool that accepts a context file at session start

Security

The npx create-agent-workflow CLI is designed to be safe to run without hesitation:

| Guarantee | Detail | |-----------|--------| | Zero npm dependencies | Only Node.js built-in modules (fs, path, readline). No supply chain attack surface. | | No network requests | Template files are bundled inside the package. Nothing is downloaded at run time. | | No shell execution | All file operations use fs APIs directly. No exec, spawn, or shell interpolation. | | Path traversal protection | Every file write is verified to stay inside your project's .agent/ directory. | | Safe file permissions | All written files get 0o644 (owner read/write, group/other read-only). No executable bits set. | | Input sanitization | All user input is stripped of null bytes and control characters before use. | | No postinstall scripts | The package has no scripts field. Nothing runs on npm install. | | Auditable source | The entire CLI is a single readable file: bin/index.js. | | NO_COLOR respected | Set NO_COLOR=1 to disable ANSI output (follows no-color.org). |

Contributing

Issues and pull requests are welcome. See CHANGELOG.md for version history.

License

MIT — see LICENSE.