https://github.com/ellmos-ai/project-docs-template
Agent-ready project documentation template with START/STATE/TODO/DONE, workflows, lightweight tooling, and LLM-friendly project memory.
https://github.com/ellmos-ai/project-docs-template
agent-ready agent-workflow claude-code codex documentation-template documentation-tools ellmos llm-agents llm-documentation project-docs project-template
Last synced: 4 days ago
JSON representation
Agent-ready project documentation template with START/STATE/TODO/DONE, workflows, lightweight tooling, and LLM-friendly project memory.
- Host: GitHub
- URL: https://github.com/ellmos-ai/project-docs-template
- Owner: ellmos-ai
- License: mit
- Created: 2026-06-19T00:16:35.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-07-17T03:52:00.000Z (11 days ago)
- Last Synced: 2026-07-17T05:28:42.930Z (11 days ago)
- Topics: agent-ready, agent-workflow, claude-code, codex, documentation-template, documentation-tools, ellmos, llm-agents, llm-documentation, project-docs, project-template
- Language: Python
- Homepage: https://github.com/ellmos-ai/project-docs-template#readme
- Size: 75.2 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Project Docs Template
[](https://github.com/ellmos-ai/project-docs-template)
[](https://github.com/ellmos-ai/project-docs-template/actions/workflows/ci.yml)
[](./LICENSE)
Agent-ready project documentation template with START/STATE/TODO/DONE,
workflows, lightweight tooling, and LLM-friendly project memory.
This repository contains a compact documentation scaffold for projects that are
maintained with LLM agents. The template focuses on clear project state,
session handoff, task history, decision records, workflows, and small local
utilities without turning the project into a heavy operating system.
## Use This Template When
| Situation | Why it helps |
|---|---|
| A new project will be maintained by Claude Code, Codex, Gemini CLI, or another coding agent | Gives the agent a predictable bootstrap path and current-state file. |
| An existing repo has scattered notes, stale task files, or no handoff trail | Separates active work, completed work, decisions, patterns, and session state. |
| Multiple agents or humans need to resume work safely | Keeps instructions, current state, workflows, and tools in distinct files. |
This is a documentation and coordination template, not a runtime framework. It
is meant to sit inside ordinary software, research, or operations repositories.
## What Is Included
- `CLAUDE.md` and `AGENTS.md` for agent instructions
- `START.md` and `STATE.md` for session bootstrap and current state
- `TODO.md` and `DONE.md` with optional archival tooling
- `DECISIONS.md`, `PATTERNS.md`, `CHANGELOG.md`, and `HEADER-RULES.md`
- Optional FULL-profile routers: `WORKFLOWS.md`, `TOOLS.md`, `GLOSSARY.md`
- Local helpers in `_tools/`, including `init-project`, `doc-lint`,
`todo-archive`, and `workflows-sync`
The actual template files live in [`template/`](./template/).
## Quick Start
Clone this repository and instantiate a project profile:
```bash
git clone https://github.com/ellmos-ai/project-docs-template.git
cd project-docs-template
python template/_tools/init-project --target ../my-project --name MyProject --profile STANDARD
```
Add `--author "Your Name"` to set explicit frontmatter ownership or `--git` to
create a `main` repository and initial commit. Without `--author`, the tool uses
`git config user.name` and then the local OS account as a safe fallback.
Generation is staged beside the target. The result is promoted only after its
profile markers, generator-owned placeholders, and relative Markdown links
have been validated. Existing non-empty targets are never overwritten.
Available profiles:
- `MINIMAL`: 7 root files plus essential tools
- `STANDARD`: 12 root files plus essential tools
- `FULL`: 16 root files plus workflow, tool, GitHub, and glossary scaffolding
You can also copy files manually from [`template/`](./template/) if you only
need selected pieces.
Requires Python 3.10 or newer. Git is required only for `--git`.
## Profile Comparison
| Profile | Best for | Files copied |
|---|---|---|
| `MINIMAL` | Small repos, experiments, short-lived tools | Core agent instructions, start/state, TODO/DONE, essential tools |
| `STANDARD` | Serious projects with decisions and recurring maintenance | Minimal set plus changelog, decisions, patterns, header and cut-and-clue rules |
| `FULL` | Multi-agent or long-running projects with routers and workflows | Standard set plus architecture, workflow/tool routers, glossary, `.github/` |
## Design Principles
- Every file has a distinct job.
- Session handoff is explicit and short.
- Maintenance burden matters more than having every possible document.
- Routers such as `WORKFLOWS.md` and `TOOLS.md` point to details elsewhere.
- Completed tasks can be archived automatically instead of bloating `TODO.md`.
See [`template/TEMPLATE.md`](./template/TEMPLATE.md) for the full rationale and
file-by-file explanation.
## Verification
```bash
python -m unittest discover -s tests -v
```
The suite exercises every profile, real Git initialization, frontmatter
repair, workflow metadata escaping, and TODO/DONE rollback behavior. The same
suite runs on Linux, Windows, and macOS; see [`RELEASE_GATE.md`](./RELEASE_GATE.md).
Security reports belong in the private channel described in
[`SECURITY.md`](./SECURITY.md), not in public issues.
## Discoverability
Canonical search phrases:
```text
agent-ready project documentation template
LLM project docs template START STATE TODO DONE
Claude Code Codex project documentation scaffold
multi-agent repo handoff documentation template
```
For LLM and crawler-oriented metadata, see [`llms.txt`](./llms.txt).
## License
MIT License. See [LICENSE](./LICENSE).
This project is an unpaid open-source donation. Liability is limited to intent
and gross negligence under Section 521 of the German Civil Code. Use at your
own risk. No warranty, maintenance guarantee, availability guarantee, or
fitness-for-purpose guarantee is provided.