Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,8 @@ For the full workflow narrative, conventions, and registry schemas, read
prompts + dev notes). The old `z_features/`, `z_vault/` and `autoprompt/`
top-level folders were retired here on 2026-07-13.
- **Registry** — root-level markdown files, each with one job: `active.md`
(in-flight tasks), `planned.md` (scoped, not started), `complete.md`
(shipped), `parked.md` (started but not in flight), `queue.md` (ordered
(in-flight tasks), `planned.md` (scoped, not started), `parked.md` (started
but not in flight), `queue.md` (ordered
input for `register_and_iterate --queue`), `ideas.md` (raw inbox swept by
`$intake`, `/intake` in Claude). Mutate these only via the skills in `skills/` so commit
messages stay consistent.
Expand Down
13 changes: 7 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,21 @@ What lives here:
| `ideas.md` | raw incubating ideas, no structure required |
| `draft/<work-type>/<target>/*.md` | scoped prompts, **not started** (`feature/`, `bug/`, `docs/`, …) |
| `active/<name>.md` | **issued** prompts — an open issue, in flight |
| `complete/<YYYY>/<MM>/<slug>.md` | **shipped** — the rich completion record (`complete/AGENTS.md`) |
| `active.md`, `planned.md`, `complete.md` | the task ledger: in flight, queued, done |
| `complete/<YYYY>/<MM>/<slug>.md` | **shipped** — the rich completion record IS the ledger (`complete/AGENTS.md`) |
| `active.md`, `planned.md` | the live task ledger: in flight, queued |
| `repos.yaml` | the body map — the single source of repo identity |
| `scripts/` | registry sync + drift checks (`repos_sync.py`, `lifecycle.py`) |

A prompt flows through three file states that mirror the ledger: idea →
`draft/…` → `/start_dev` → GitHub issue + `active/` + `active.md` entry →
worktree development → PR → merge → `complete/<YYYY>/<MM>/` +
`complete.md`. `scripts/lifecycle.py` advances the file and drift-checks the
invariant. The registry is shared state, so any machine or session can pick up
worktree development → PR → merge → the dated record
`complete/<YYYY>/<MM>/<slug>.md` (the sole completion ledger; the monolithic
`complete.md` was retired 2026-07-16, issue #81). `scripts/lifecycle.py`
advances the file and drift-checks the invariant. The registry is shared state, so any machine or session can pick up
an in-flight task.

The schemas and conventions — prompt taxonomy, prompt file format, the
`active.md` / `complete.md` schemas, epic trackers, bootstrap on a new
`active.md` / completion-record schemas, epic trackers, bootstrap on a new
machine — are in [REFERENCE.md](REFERENCE.md). How agents should operate
this repo is in [AGENTS.md](AGENTS.md).

Expand Down
27 changes: 17 additions & 10 deletions REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
The registry schemas, prompt conventions, and workflow detail for this repo.
Moved verbatim from `README.md` on 2026-07-10 — agent docs that point at
README sections ("Prompt taxonomy", "Prompt file format", the `active.md` /
`complete.md` schemas) resolve here, one link from the README.
completion-record schemas) resolve here, one link from the README.

---

Expand Down Expand Up @@ -111,9 +111,9 @@ fine — write naturally, the AI fills in the rest.
/ship_workspace
PR merged ── post-merge cleanup deletes the worktree, moves the
│ active.md entry to complete.md, and advances the prompt
file active/ → complete/<YYYY>/<MM>/ (lifecycle.py move)
PR merged ── post-merge cleanup deletes the worktree, drops the
│ active.md entry, and writes the dated completion record
│ complete/<YYYY>/<MM>/<slug>.md (lifecycle.py record)
done
```
Expand All @@ -122,7 +122,7 @@ The slash commands above are skills hosted across the organism (Brain, Heart) bu
all read/write Mind's registry via workspace-root-anchored paths. One operates
over the registry without starting work:

- `/health status` — dashboard of `active.md`, `planned.md`, `complete.md`
- `/health status` — dashboard of `active.md`, `planned.md`, `complete/`
(a PyAutoHeart status view, reached through the single `/health` door).
Continuity across execution environments needs no special step — any
environment reads `active.md` and resumes an in-flight task.
Expand All @@ -138,7 +138,6 @@ PyAutoMind/
├── .gitignore
├── active.md ← tasks currently in progress (one ## section per task)
├── complete.md ← finished tasks (most recent first)
├── ideas.md ← raw incubating ideas, no structure required
├── parked.md ← started/scoped but not in flight (stashes, orphan worktrees, deferred)
├── planned.md ← issued tasks blocked from starting (created on demand)
Expand Down Expand Up @@ -192,7 +191,7 @@ environments — see `OWNERSHIP.md`). General PyAuto tooling (release prep,
dependency audits, smoke tests, lint sweeps) lives in `admin_jammy/skills/`.

`scripts/prompt_sync.sh` is sourced by skills that mutate registry files
(`active.md`, `complete.md`, etc.) to commit and push back to origin. It
(`active.md`, `planned.md`, etc.) to commit and push back to origin. It
replaces a now-removed `admin_sync.sh` helper that formerly operated on
`admin_jammy/prompt/`.

Expand Down Expand Up @@ -343,16 +342,24 @@ Each task is an H2 section:
Free-form summary of progress and next steps.
```

### `complete.md` schema
### Completion record (`complete/<YYYY>/<MM>/<slug>.md`) schema

The dated records are the completion ledger (`complete/AGENTS.md`; the
monolithic `complete.md` was retired 2026-07-16, issue #81). Each record opens
with the same fields the old ledger entries carried, then the rich narrative
and, appended by `lifecycle.py record`, the original prompt:

```markdown
## <task-name>
- issue: https://github.com/<owner>/<repo>/issues/<n>
- completed: YYYY-MM-DD
- library-pr: <url> [, <url>]
- workspace-pr: <url> [, <url>]
- notes: |
Long-form description of what landed, gotchas, follow-ups.
- summary: <what landed, gotchas, follow-ups — free-form bullets>

## Original prompt

<the active/ prompt the task started from>
```

### Epic trackers (retired 2026-07-13)
Expand Down
Loading
Loading