oliverchan2024
Joined 2 years ago
Joined 2 years ago
- Every time I switch tools/models, I have to re-explain the project. - Specs live in my head or in random chat history. - The AI happily writes code, but there’s no clear “this is the task, this is how we verify it, this is how we log the change”.
SPEC-AGENTS.md is a tiny attempt to fix that.
You drop an `AGENTS.md` file (this repo) plus a small `.phrase/` folder into your project. That file tells the AI to:
- treat docs as the source of truth (`spec_`, `plan_`, `task_`, `change_`, `issue_`, `adr_`) - only tackle one atomic `taskNNN` per session - always write back what happened (what changed, how it was verified)
There’s no server, no binary, no tooling – it’s just conventions the AI is expected to follow. Any tool that can read files (CLI, editor plugin, chat with “read files” feature) can play along.
Rough loop:
1. You and the AI update `spec_` / `plan_` in `.phrase/phases/...` to describe what you want. 2. You break that into small `taskNNN` items, each with a clear output + verification step. 3. The AI implements one task, runs tests/manual checks, and tells you what it did. 4. It writes back to `task_` and `change_`, and updates `spec_` / `issue_` / `adr_*` if needed.
The README has an ASCII diagram and a small “dark mode toggle” example conversation to show what this looks like in practice. There’s also a Chinese section because I originally wrote this for my own projects.
This is still an experiment. It adds a bit of ceremony, so it’s probably overkill for one-off scripts, but it feels good for small projects where you want more structure without bringing in a full PM tool.
I’d love to know:
- Does this doc-first, one-task-per-session style match how you work with AI, or is it too much? - If you already use specs (OpenSpec, your own templates, etc.), would you keep this as a separate “AI contract”, or just integrate the ideas? - What’s missing for this to be useful in your day-to-day?
Sometimes I miss it, and when I go back to look, I almost can't find it back.
How much time does it take for you to clear chat history every week?
Suppose you have a hundred conversations that can be retained, how would you manage them?
I develop this because I see my friend play video in Emacs with his package called video.el, and I do some research on it, the result is, it use emacs's dynamic module and the newest Canvas API.
So, I think maybe I can use this tech-stack to do something really cool. At that time, I was chat with my friend, he said, maybe it can run excalidraw inside emacs. I think the idea is worth to try.
I developed a small C module does drawing with Cairo and Pango, and I port rough.js to C, to make excali-mode can support most functions of excalidraw.