Issues-FS-lite: the agent mode

You are an agent. You have a filesystem, a shell and a git repository. You have no Python, no issues-fs binary, no service and no database. Here is how to track work. Three folders, markdown files with YAML front-matter, and four mv operations. That is the entire protocol.

1 · The layout

Three folders under your own workspace. In an Email-FS-lite vault this sits at mail/{your-agent-name}/issues/; standalone, it is {your-workspace}/issues/ and nothing else changes.

{your-workspace}/issues/
├── open/                       ← active tasks
│   ├── 001-incorporate-v07-feedback.md
│   ├── 002-write-comparison-doc.md
│   └── 008-incorporate-v07-feedback.md
├── blocked/                    ← waiting on something external
│   └── 005-pkce-token-rotation-q.md
└── done/                       ← completed tasks
    ├── 003-route-prefix-decision.md
    └── 007-handoff-pkce-implementation.md

The lifecycle is open → done, with blocked/ alongside it “because tasks have a richer flow than messages.” Filenames are NNN-kebab-slug.md. The sequence is per-agent — your own counter, independent of every other agent's. Two agents both having an 001 is normal and correct.

2 · The task file

A markdown file with YAML front-matter. The front-matter is for machines; the body is for whoever reads it next, which is usually you in a different session.

---
created: 2026-05-06T18:00:00Z
source: mail/architect.spec/inbox/003-feedback-on-spec.eml
priority: high
estimated_effort: medium
---

# Incorporate v0.7 feedback into the draft

## What needs doing

@Code's feedback on spec §4 had three concrete points:
- Replace implicit grant with PKCE (line 47)
- Add code_challenge_method: S256 requirement (line 51)
- Add 5-min auth-code TTL note (line 58)

## How I'll approach it

1. Open the v0.7 draft
2. Apply each edit
3. Update the changelog
4. Send the updated draft back to @Code for verification

## Acceptance criteria

- All three lines updated
- Changelog reflects the changes
- @Code confirms via reply

Required front-matter

Recommended front-matter

“The body of the task file is your own action plan. Be honest — if you don't know how to approach it yet, write that. Future you (or a different runtime) will read this.”

That instruction is the whole design philosophy in one line. A task file is not a status report for somebody else; it is a note from one session of an agent to the next, and a note that pretends to a plan it does not have is worse than one that says so.

3 · The four operations

“That's the entire issues protocol. Four mv operations.”

Nothing is deleted and nothing is edited in place except by appending. The file's path is its status, which is why find and ls are sufficient query tools and why a git diff of a commit shows the state change as a rename.

4 · The check-in cycle

Lite was specified beside a messaging protocol, and the coupling is the useful part: the issue updates land in the same commit as the message. The commit becomes a coherent record — this arrived → here is what I planned to do about it → here is what I sent in reply. Generalised away from email: issues live beside whatever generated them, and the commit is the record of what the agent understood.

DELIVER incoming message
  → if it generates tasks:          OPEN one or more issues
  → if it answers a blocker:        UNBLOCK the corresponding issue
  → if it acknowledges work:        CLOSE the corresponding issue

SEND outgoing message
  → if it asks a blocking question: BLOCK the relevant issue
  → if it hands off work:           CLOSE the corresponding issue
  → if it creates a task for us:    OPEN a follow-up

DONE incoming message
  → only if all related issues are closed too

“Every email cycle leaves the inbox cleaner and the issues folder updated. A future reader of the commit can reconstruct what the agent understood and planned without reading the email itself, by looking at the issues that opened or closed.”

5 · The writer rule

“You CAN read another agent's issues/ folder. You should NOT write into it.”

This is a design position on multi-agent coordination, not an implementation detail:

“The protocol doesn't permit one agent to add tasks to another's queue directly — only by request via mail. This is intentional: each agent owns their own work plan.”

The read half of that rule buys a full team-status view for free, out of the layout alone — two find commands and no tooling.

6 · Status, stated plainly

The upgrade path, honestly

What happens when a lite graph outgrows lite? There is no converter today. Nothing reads issues/open/*.md and writes .issues/…/issue.json, and nothing goes the other way. Moving up means re-creating the nodes through the CLI and letting the labels be reassigned, because the identity schemes do not correspond: lite identifies a task by a per-agent filename sequence, full identifies it by a 10-character GUID with a human label derived from a per-type counter. The comparison in full.

The phrase the source material uses is worth keeping, because it sets the expectation correctly: “lite is a usage profile, not a fork.” It is not a cut-down implementation that will one day be completed. It is a way of working that happens to need no implementation at all.