Agentic Project Template

AI coding assistants work best when they understand your project. But each session often starts from scratch—you repeat context, paste snippets, and hope the agent remembers. This template fixes that.

It gives you a shared, structured context that both humans and AI agents read from—so everyone works from the same understanding.

---

In 30 Seconds

A project template that gives AI coding assistants (and humans) a shared context so they can work effectively without re-explaining the project every time. Use it as a starting point for any new project where you want Cursor, GitHub Copilot, Claude, or similar tools to "get" your structure, conventions, and workflow from day one.

---

The Idea in Practice

Imagine: You clone a repo. You open Cursor. The AI already knows your folder structure, your conventions, and what you're actively working on. No copy-pasting. No re-explaining. It's like onboarding a new teammate who's already read the docs.

Without this template:

• New session → paste context → agent forgets → repeat

With this template:

• New session → agent reads AGENTS.md and .agents/ → picks up where you left off

---

Key Benefits

One source of truth, many agents. You might use Cursor today, Claude tomorrow, and Copilot in another project. Instead of maintaining separate instructions for each, you keep a single context—AGENTS.md and .agents/—that every tool reads from. Same structure, same conventions, no drift.

Collaboration without chaos. Shared context means everyone on the project—humans and AI—works from the same understanding. At the same time, each person gets a private .agents/local/ space for plans, personal context, experimental skills, and workflow state. Its optional nested repository keeps local history without cluttering the main project or stepping on teammates' work.

Complex work across many sessions. Some initiatives take days or weeks and span dozens of agent sessions. Agents forget between sessions; plans and progress notes don't. You document what you're doing, where you left off, and what's next. When you resume, you (or any agent) run whats-next and pick up exactly where you were.

---

What You Get

• Shared context — AGENTS.md as the single source of truth; .agents/ for modular, detailed guidance
• Plans & tasks — Structured way to track initiatives and executable units with status and progress notes
• Platform support — Works with Cursor, GitHub Copilot, Claude; each platform references the same context
• Local developer space — Keep plans, personal context, experimental skills, and workflow state outside the main project history
• Optional nested repo — Version-control the entire local developer space independently

---

Project Structure

project-root/
├── AGENTS.md                    # Single source of truth (customize for your project)
├── CLAUDE.md                    # Claude integration (references AGENTS.md)
├── .agents/
│   ├── context/                 # Setup and reference docs
│   │   └── agentic-infra-setup.md   # Detailed setup guide
│   ├── skills/                  # Skill definitions and skill-owned templates
│   │   ├── create-plan/
│   │   │   ├── SKILL.md
│   │   │   └── templates/plan.md
│   │   ├── create-task/
│   │   │   ├── SKILL.md
│   │   │   └── templates/task.md
│   │   ├── update-plan/SKILL.md
│   │   ├── whats-next/SKILL.md
│   │   ├── create-learning/SKILL.md
│   │   ├── setup-local-repo/SKILL.md
│   │   └── ...                  # Additional infra skills
│   └── local/                   # Developer-owned, ignored by the main repo
│       ├── README.md            # Purpose, privacy, and ownership guidance
│       ├── context/             # Personal or machine-specific context
│       ├── skills/              # Personal or experimental skills
│       └── plans/               # Tracked plans, tasks, and learnings
├── .claude/
│   └── skills/                  # Symlink → ../.agents/skills
├── .cursor/
│   └── skills/                  # Symlink → ../.agents/skills
└── .github/
    └── copilot-instructions.md  # GitHub Copilot (optional, references AGENTS.md)

---

Quick Start

1. Use This Template

Clone or use this repo as a template for your new project:

git clone <this-repo-url> my-project
cd my-project

2. Customize

• Edit AGENTS.md — Replace the stub content with your project's overview, structure, conventions, and workflow. This is the main file agents read.
• Add platform files — For Cursor or Claude, create symlinks from .cursor/skills/ and .claude/skills/ to .agents/skills/. For Copilot, add .github/copilot-instructions.md referencing AGENTS.md.

3. Optional: Set Up Local Version Control

If you want to track your local plans, context, experimental skills, and workflow state with Git without committing them to the main repository, run:

bash .agents/skills/setup-local-repo/scripts/setup_local_repo.sh

This creates a nested Git repository in .agents/local/. The directory also works without nested version control.

4. Full Setup Guide

For detailed setup, platform-specific options, and best practices, see .agents/context/agentic-infra-setup.md.

---

How to Use It

Resuming Work

Run the whats-next skill to see the next actionable steps across all active tracked plans. It scans your plans, finds active tasks, and tells you what to do next.

Creating Work

• Create a plan — Use the create-plan skill to scaffold a new plan directory and plan.md with objectives, requirements, and initial tasks.
• Create tasks — Use the create-task skill to add executable units under a plan (with numeric prefix naming for execution order).

Tracking Progress

• Update plans — Use the update-plan skill to change statuses, create new tasks, revise existing tasks, or complete plans.
• Capture learnings — Use the create-learning skill to record non-obvious insights during or after plan execution.
• Progress notes — Keep them reverse-chronological so the latest updates appear first.

Skills Reference

Skill	Purpose
whats-next	Find next actionable steps across active tracked plans
create-plan	Scaffold a new plan directory with initial tasks
create-task	Add a task file under an existing plan
update-plan	Change statuses, add tasks, revise tasks, or complete plans
create-learning	Capture non-obvious insights as structured learnings
setup-local-repo	Initialize or migrate the nested repository for developer-owned local content
setup-agentic-context	Bootstrap agentic infrastructure in a new repo
review-agentic-infra	Audit agent infrastructure

Skill definitions live in .agents/skills/. Platform-specific skill directories (.claude/skills/, .cursor/skills/) are symlinked to .agents/skills/ for a single source of truth.

---

Platform Support

Platform	File(s)	Notes
Cursor	.cursor/skills/ (symlink)	Skills symlinked from .agents/skills/; optional .cursor/rules/ for IDE-specific rules
GitHub Copilot	.github/copilot-instructions.md	Reference AGENTS.md; add Copilot-specific instructions only
Claude	CLAUDE.md, .claude/skills/ (symlink)	CLAUDE.md references AGENTS.md; skills symlinked from .agents/skills/

---

Best Practices

• Keep AGENTS.md concise — Put detailed information in .agents/ files.
• Run whats-next when resuming work — It surfaces the next actionable steps so you can pick up where you left off.
• Use .agents/local/ for developer-owned content — Plans, personal context, experimental skills, scratch work, and private workflow state belong here rather than in shared infrastructure.
• Use the optional local repository — Run setup-local-repo when you want independent history for the entire developer space.
• Do not treat local as a secrets vault — Keep credentials and production secrets in an appropriate secret manager.
• Avoid duplication — Platform-specific files should reference AGENTS.md and .agents/, not repeat their content.

---

Further Reading

• .agents/context/agentic-infra-setup.md — Full setup guide and best practices
• AGENTS.md — Master reference for plans, tasks, skills, and workflow
• AGENTS.md pattern — Official documentation for the AGENTS.md pattern
• Cursor Project Rules — Cursor project rules documentation