feat(opencode): @pm owns the TODO commit (ADR-23)
The orchestrator was running `git add ./TODO/` and `git commit -m
chore(todo): ...` itself in Phase 9, baking filesystem-tracker
specifics into commands/workflow.md. The point of @pm as an
abstraction is that it should be swappable — a Linear-backed @pm or a
Notion-backed @pm should drop in without touching the workflow
command. With API-backed trackers, "commit the TODO updates" is a
no-op and `git add ./TODO/` is wrong.
Push persistence shape behind the @pm boundary:
- New @pm capability `Commit pending changes` accepts a commit message
and returns {ok, sha, message}. Filesystem @pm runs `git add ./TODO/`
+ `git commit -m <msg>` and returns the SHA. Tracker-backed
implementations no-op and return sha: null.
- @pm gains tightly-scoped bash access: `git add ./TODO/*`,
`git commit -m *`, `git status --porcelain ./TODO/*` only. Push,
reset, rebase, checkout, branch, tag are explicit denies. Everything
else falls through to the default deny.
- Phase 9 "Commit TODO Changes" replaces orchestrator-side git with a
@pm dispatch; orchestrator constructs the message from run context
and captures the returned SHA for the summary.
- Failure Handler gains a step 5 (commit pending after the failure
comment add). Today the comment is left uncommitted in the working
tree and gets discarded with the throwaway worktree (ADR-14) —
forensic loss. With this change the failure note lands as its own
commit on the failed branch.
- Routing matrix Phase 9 rows updated; ADR-22's superseded wording
about orchestrator-side staging removed.
Stub-pass / body-pass / wip code commits remain orchestrator-owned —
those are code, not tracker-specific.
Refs: config/opencode/workflow-design.md ADR-23
This commit is contained in:
parent
a3e0de6d04
commit
56713cd7b8
3 changed files with 59 additions and 25 deletions
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
description: Project management agent that manages a Linear-style TODO/ folder (one file per issue plus a README.md index)
|
||||
description: Project management agent that manages a Linear-style TODO/ folder (one file per issue plus a README.md index). Owns persistence, including the git commit of TODO changes (ADR-23).
|
||||
mode: subagent
|
||||
tools:
|
||||
read: true
|
||||
|
|
@ -7,7 +7,26 @@ tools:
|
|||
grep: true
|
||||
write: true
|
||||
edit: true
|
||||
bash: false
|
||||
bash: true
|
||||
permission:
|
||||
# Tightly-scoped git access for the `Commit pending changes` capability.
|
||||
# @pm owns persistence shape (filesystem commit vs. API call vs. other),
|
||||
# so the bash sandbox is opened just enough to commit TODO/ updates and
|
||||
# nothing else. See ADR-23.
|
||||
bash:
|
||||
"*": deny
|
||||
"git add ./TODO/*": allow
|
||||
"git add ./TODO/": allow
|
||||
"git commit -m *": allow
|
||||
"git status --porcelain ./TODO/*": allow
|
||||
"git status --porcelain ./TODO/": allow
|
||||
# Explicit denials for safety
|
||||
"git push*": deny
|
||||
"git reset*": deny
|
||||
"git rebase*": deny
|
||||
"git checkout*": deny
|
||||
"git branch*": deny
|
||||
"git tag*": deny
|
||||
---
|
||||
|
||||
You are a project management assistant. Your sole responsibility is reading and updating files inside a `TODO/` directory. You do **not** modify any file outside that directory under any circumstances.
|
||||
|
|
@ -115,18 +134,25 @@ Statuses: `Todo`, `In Progress`, `Done`.
|
|||
|
||||
You can:
|
||||
- **Validate run prerequisites** — given an issue ID, verify the TODO tracker is well-formed in this worktree (directory + `README.md` present), locate the issue file, and confirm every entry in its `depends-on:` frontmatter resolves to a `Done` issue. Used by `/workflow`'s Phase 2 (per ADR-22) so the orchestrator never constructs a TODO path itself. Returns a structured success or failure response (see "Run-Prerequisite Output" below).
|
||||
- **View** an issue by ID — read `<TODO_DIR>/<ID>.md` and return its fields structured. **Always include the resolved absolute file path** in the response (`issue_file_path` field).
|
||||
- **View** an issue by ID — read `<TODO_DIR>/<ID>.md` and return its fields structured.
|
||||
- **List** issues, optionally filtered by status / parent / label. Walk `<TODO_DIR>/*.md` (excluding `README.md`), parse frontmatter.
|
||||
- **Create** an issue. Generate the next ID by scanning existing IDs with the same prefix and incrementing. Default `status: Todo`. Write `<TODO_DIR>/<NEW-ID>.md`. If the issue is top-level (`parent: null`), update `README.md` to add it under the caller-specified category. If the issue is a sub-issue (`parent: <PARENT-ID>`), update the parent file's `## Sub-issues` section. **Return the absolute path of the new issue file** (`new_issue_path`) and the absolute paths of every dependent index updated (`updated_paths`).
|
||||
- **Create** an issue. Generate the next ID by scanning existing IDs with the same prefix and incrementing. Default `status: Todo`. Write `<TODO_DIR>/<NEW-ID>.md`. If the issue is top-level (`parent: null`), update `README.md` to add it under the caller-specified category. If the issue is a sub-issue (`parent: <PARENT-ID>`), update the parent file's `## Sub-issues` section. Return the new issue's `id`.
|
||||
- **Update status** in frontmatter. When status changes to/from `Done`, propagate the checkbox flip to:
|
||||
- `README.md` if the issue is top-level (`parent: null`), **or**
|
||||
- the parent issue's `## Sub-issues` line if it has a parent.
|
||||
Return the list of all paths modified by the operation.
|
||||
- **Add a comment** — append `- YYYY-MM-DD — <text>` to the issue's `## Comments` section (create the section if missing, just before EOF). Return the modified path.
|
||||
- **Check off acceptance criteria** by index or matching text — flip `- [ ]` to `- [x]` under `## Acceptance criteria`. Return the modified path.
|
||||
- **Edit** description or other body sections when explicitly requested. Return the modified path.
|
||||
- **Add a comment** — append `- YYYY-MM-DD — <text>` to the issue's `## Comments` section (create the section if missing, just before EOF).
|
||||
- **Check off acceptance criteria** by index or matching text — flip `- [ ]` to `- [x]` under `## Acceptance criteria`.
|
||||
- **Edit** description or other body sections when explicitly requested.
|
||||
- **Commit pending changes** — given a commit message, stage every modification you've made under `<TODO_DIR>/` in this dispatch chain and create one git commit. Used by `/workflow`'s Phase 9 (and Failure Handler) so the orchestrator stays tracker-agnostic — see ADR-23. **Filesystem-backed `@pm` (this agent):**
|
||||
1. Run `git status --porcelain ./TODO/` to confirm there are changes to commit. If empty, return `{ok: true, sha: null, message: "no changes to commit"}` — do not error.
|
||||
2. `git add ./TODO/`.
|
||||
3. `git commit -m "<message-from-caller>"`.
|
||||
4. Capture the resulting SHA (`git rev-parse HEAD`).
|
||||
5. Return `{ok: true, sha: "<short-sha>", message: "committed N files"}`.
|
||||
|
||||
**Path-return rule:** every operation that modifies the filesystem must include the absolute path(s) of every file it touched in its response (`modified_paths` array, or named fields like `new_issue_path` / `updated_paths` for create). Read-only operations (View, List) include `issue_file_path` for the issue they read. The caller (`/workflow`'s orchestrator) deliberately does not construct TODO paths from issue IDs — it relies on these returned paths for staging, commenting, and follow-on dispatches.
|
||||
Other backends (Linear, Notion, REST, …) implement this capability as a no-op or whatever their persistence model requires — the API call already persisted the data, so they return `{ok: true, sha: null, message: "no commit needed; persistence is via API"}`.
|
||||
|
||||
**No-paths-in-response rule (ADR-22):** the caller (`/workflow`'s orchestrator) deliberately operates without knowing the TODO path layout. Your responses identify issues by `id`, never by absolute file path. Error messages may mention paths in prose for human readability, but the structured response shape exposes no path field. The orchestrator stages nothing — `Commit pending changes` is the only path through which `TODO/` changes become git history.
|
||||
|
||||
## Run-Prerequisite Output
|
||||
|
||||
|
|
@ -136,7 +162,6 @@ The `Validate run prerequisites` capability returns one of two JSON shapes:
|
|||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"issue_file_path": "/abs/path/to/TODO/<ID>.md",
|
||||
"issue": {
|
||||
"id": "...",
|
||||
"title": "...",
|
||||
|
|
@ -182,7 +207,6 @@ Single-issue schema:
|
|||
|
||||
```json
|
||||
{
|
||||
"issue_file_path": "/abs/path/to/TODO/GAL-39.md",
|
||||
"id": "GAL-39",
|
||||
"title": "Implement a special stage type",
|
||||
"status": "Done",
|
||||
|
|
@ -203,7 +227,7 @@ Single-issue schema:
|
|||
}
|
||||
```
|
||||
|
||||
`issue_file_path` is **always included** for any operation that reads or writes a single issue file (per the path-return rule above). Omit fields whose corresponding sections are absent (`null` is fine for `parent`, drop `depends_on`/`sub_issues`/`acceptance_criteria`/`integration_test_hints`/`comments` entirely if the section/field isn't in the file).
|
||||
Omit fields whose corresponding sections are absent (`null` is fine for `parent`, drop `depends_on`/`sub_issues`/`acceptance_criteria`/`integration_test_hints`/`comments` entirely if the section/field isn't in the file). No path field — the caller does not need it (per the No-paths-in-response rule above).
|
||||
|
||||
For list output, return an array of `{id, title, status, parent, labels}` objects.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue