From 9eee61d550115b894284773a6bc4f4ccfbf11080 Mon Sep 17 00:00:00 2001 From: David Poblador i Garcia Date: Fri, 13 Feb 2026 12:50:43 +0100 Subject: [PATCH 1/2] feat: add task management docs and SPECS.md skeleton Co-Authored-By: Claude Opus 4.6 --- template/AGENTS.md | 27 ++++++++++++++++++++++++++- template/SPECS.md | 3 +++ 2 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 template/SPECS.md diff --git a/template/AGENTS.md b/template/AGENTS.md index 74c4a61..fa85aa2 100644 --- a/template/AGENTS.md +++ b/template/AGENTS.md @@ -9,6 +9,9 @@ This project uses a **bare repo + worktree** structure. Read this before making ├── .git/ # Bare git repo (all git object data lives here) ├── main/ # Worktree for the main branch (keep pristine) ├── / # Worktree for a feature branch +├── SPECS.md # Project specifications (editable via web) +├── task_*.md # Pending task files (created by bot/web) +├── completed/ # Completed tasks (moved here by agents) ├── justfile # Worktree management recipes (run via just) ├── .claude/ # Agent configuration (outside version control) └── AGENTS.md # This file @@ -24,7 +27,7 @@ This project uses a **bare repo + worktree** structure. Read this before making repo itself. Running `git status` at the root will say "must be run in a work tree", which is correct. Always `cd` into a worktree to do git operations on that branch. 4. **Files at the project root** (outside worktrees) are not tracked by git. The `justfile`, - `AGENTS.md`, and config directories live here intentionally. + `AGENTS.md`, `SPECS.md`, `task_*.md`, `completed/`, and config directories live here intentionally. 5. **Before editing ANY file**, verify you are in a feature worktree directory, not `main/`. If no feature worktree exists for your current task, create one with `just wt-add ` before making any changes. @@ -120,6 +123,28 @@ work in bare repo roots), runs the update there, and syncs results back. - To compare branches from a worktree: `git diff main...`. - To fetch updates: `git fetch --all` from any worktree. +## Task management + +### SPECS.md + +`SPECS.md` at the project root describes what the project is about — its purpose, goals, and +key decisions. This file is created and maintained through the project manager (bot or web +interface). Agents should read it for context before starting work. + +### Task files + +Tasks are individual markdown files at the project root, named `task_N.md` where N is a +random 4-digit ID (e.g. `task_4821.md`). Each file contains a plain text description of +the task. + +Tasks are created by the project manager (bot or web interface). To complete a task: + +```bash +mkdir -p completed && mv task_N.md completed/ +``` + +Completed tasks live in `completed/` for reference. + ## PR title conventions This project uses **conventional commit format** for PR titles. PR titles become commit diff --git a/template/SPECS.md b/template/SPECS.md new file mode 100644 index 0000000..9e610ff --- /dev/null +++ b/template/SPECS.md @@ -0,0 +1,3 @@ +# Project Specifications + + From c2fa8386d3f640b06537bb8325ee8903ec3ba107 Mon Sep 17 00:00:00 2001 From: David Poblador i Garcia Date: Fri, 13 Feb 2026 12:55:49 +0100 Subject: [PATCH 2/2] chore: make SPECS.md empty by default Co-Authored-By: Claude Opus 4.6 --- template/SPECS.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/template/SPECS.md b/template/SPECS.md index 9e610ff..e69de29 100644 --- a/template/SPECS.md +++ b/template/SPECS.md @@ -1,3 +0,0 @@ -# Project Specifications - -