OpenAgents

Commit

Add a markdown work plan for issues and projects.

e91c1e285574 · AtlantisPleb · · parent acb94ccd5f1a 

Add a markdown work plan for issues and projects.

`docs/issues-projects-work-plan.md` chunks the API buildout into six
eipcs, each with TDD-ready tasks, dependencies, acceptance criteria, and
parallelization waves. The assessment doc now links to it.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By
Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Deploy story

What this commit did to the running system — joined from the forge receipt chain, the part a commit page elsewhere cannot show.

Not deployed through the forge lane

No push, promotion, build, or deploy receipt references this commit (receipts are scanned over a bounded recent window). Changes shipped by full node replacement carry their proof in the release gate receipt instead.

Changed files

  • modified docs/github-api-issues-projects-assessment.md
  • added docs/issues-projects-work-plan.md

Diff

2 files changed, +284 -0

docs/github-api-issues-projects-assessment.md modified +2

@@ -3,6 +3,8 @@

3 3 
Date: 2026-08-19
4 4 
Source: `rest-api-description/descriptions/api.github.com/api.github.com.2026-03-10.yaml`
5 5
6 
For the concrete work breakdown, parallelization map, and subagent dispatch notes, see `docs/issues-projects-work-plan.md`.
7
6 8 
## Goal
7 9
8 10 
Dogfood OpenAgents by using it to track this repo's own issues and projects. We want enough GitHub REST API parity that `gh`, Octokit, and the GitHub CLI can talk to OpenAgents without changes, but we will only build the subset we actually use.
docs/issues-projects-work-plan.md added +282

@@ -0,0 +1,282 @@

1 
# Issues and Projects API — work plan
2
3 
Date: 2026-08-19
4 
Source: `docs/github-api-issues-projects-assessment.md`
5
6 
This document is a markdown-only tracker. Each `Epic` and `Task` will later become an issue or sub-issue in the OpenAgents forge. It organizes the buildout, lists dependencies, and flags work that can be parallelized or dispatched to subagents.
7
8 
## Approach
9
10 
- Drive every endpoint through tests first. Follow the TDD workflow in `AGENTS.md`.
11 
- Build the API in the order shown below. Start each epic with the shared schema and context module.
12 
- Run `mix test test/openagents_web/controllers/<...>` for a single file, or `mix precommit` before a final commit.
13 
- Each task includes acceptance criteria and a `subagent ready` flag. Use `subagent_general` for self-contained implementation tasks and `subagent_explore` for spec research.
14
15 
## Epic 1: Issue CRUD
16
17 
Goal: implement the core repository issue endpoints.
18
19 
### E1-T1: Define the `OpenAgents.Issues` context and `Issue` schema
20 
- Create the Ecto schema and migration for repository issues.
21 
- Fields must match the GitHub `issue` object shape where OpenAgents stores the data.
22 
- Acceptance:
23 
  - `mix ecto.migrate` succeeds.
24 
  - `OpenAgents.Issues.list_issues/1` and `OpenAgents.Issues.get_issue!/1` exist.
25 
- Dependencies: none.
26 
- Subagent ready: no.
27
28 
### E1-T2: GET /api/v3/repos/{owner}/{repo}/issues
29 
- Return a list of issues for a repo. Support query filters (`state`, `labels`, `assignee`, `milestone`, `sort`, `direction`).
30 
- Acceptance:
31 
  - `GET /api/v3/repos/OpenAgents/openagents/issues` returns 200 and a JSON array.
32 
  - Tests cover open issues, closed issues, and empty repositories.
33 
- Dependencies: E1-T1.
34 
- Subagent ready: yes.
35
36 
### E1-T3: GET /api/v3/repos/{owner}/{repo}/issues/{issue_number}
37 
- Return a single issue.
38 
- Acceptance:
39 
  - Existing issue returns 200 and the issue JSON.
40 
  - Missing issue returns 404.
41 
- Dependencies: E1-T1.
42 
- Subagent ready: yes.
43
44 
### E1-T4: POST /api/v3/repos/{owner}/{repo}/issues
45 
- Create an issue with `title`, `body`, `labels`, `assignees`, and `milestone`.
46 
- Acceptance:
47 
  - Valid request returns 201 and the created issue.
48 
  - Invalid request returns 422 with error details.
49 
- Dependencies: E1-T1.
50 
- Subagent ready: yes.
51
52 
### E1-T5: PATCH /api/v3/repos/{owner}/{repo}/issues/{issue_number}
53 
- Update title, body, state, labels, assignees, and milestone.
54 
- Acceptance:
55 
  - Closing an issue returns the issue with `state: "closed"`.
56 
  - Reopening an issue returns `state: "open"`.
57 
- Dependencies: E1-T4.
58 
- Subagent ready: yes.
59
60 
## Epic 2: Issue comments
61
62 
Goal: implement issue comments.
63
64 
### E2-T1: Add `OpenAgents.Issues.Comment` schema and migration
65 
- Acceptance: `OpenAgents.Issues.create_comment/3` exists.
66 
- Dependencies: E1-T1.
67 
- Subagent ready: no.
68
69 
### E2-T2: GET /api/v3/repos/{owner}/{repo}/issues/{issue_number}/comments
70 
- Acceptance: returns a list of comments for an issue.
71 
- Dependencies: E2-T1.
72 
- Subagent ready: yes.
73
74 
### E2-T3: POST /api/v3/repos/{owner}/{repo}/issues/{issue_number}/comments
75 
- Acceptance: returns 201 and the created comment.
76 
- Dependencies: E2-T1.
77 
- Subagent ready: yes.
78
79 
### E2-T4: GET /api/v3/repos/{owner}/{repo}/issues/comments/{comment_id}
80 
- Acceptance: returns 200 for an existing comment and 404 for a missing one.
81 
- Dependencies: E2-T1.
82 
- Subagent ready: yes.
83
84 
### E2-T5: PATCH /api/v3/repos/{owner}/{repo}/issues/comments/{comment_id}
85 
- Acceptance: updates body text and returns 200.
86 
- Dependencies: E2-T3.
87 
- Subagent ready: yes.
88
89 
### E2-T6: DELETE /api/v3/repos/{owner}/{repo}/issues/comments/{comment_id}
90 
- Acceptance: returns 204 and removes the comment.
91 
- Dependencies: E2-T3.
92 
- Subagent ready: yes.
93
94 
## Epic 3: Labels
95
96 
Goal: implement repository and issue labels.
97
98 
### E3-T1: Add `OpenAgents.Issues.Label` schema and migration
99 
- Acceptance: `OpenAgents.Issues.create_label/2` and `OpenAgents.Issues.list_labels/1` exist.
100 
- Dependencies: none.
101 
- Subagent ready: no.
102
103 
### E3-T2: GET /api/v3/repos/{owner}/{repo}/labels
104 
- Acceptance: returns a list of labels.
105 
- Dependencies: E3-T1.
106 
- Subagent ready: yes.
107
108 
### E3-T3: POST /api/v3/repos/{owner}/{repo}/labels
109 
- Acceptance: returns 201 and the created label.
110 
- Dependencies: E3-T1.
111 
- Subagent ready: yes.
112
113 
### E3-T4: GET /api/v3/repos/{owner}/{repo}/labels/{name}
114 
- Acceptance: returns a single label or 404.
115 
- Dependencies: E3-T1.
116 
- Subagent ready: yes.
117
118 
### E3-T5: PATCH /api/v3/repos/{owner}/{repo}/labels/{name}
119 
- Acceptance: updates name, color, and description.
120 
- Dependencies: E3-T3.
121 
- Subagent ready: yes.
122
123 
### E3-T6: POST /api/v3/repos/{owner}/{repo}/issues/{issue_number}/labels
124 
- Acceptance: adds labels to an issue and returns the updated issue.
125 
- Dependencies: E1-T1, E3-T1.
126 
- Subagent ready: yes.
127
128 
### E3-T7: DELETE /api/v3/repos/{owner}/{repo}/issues/{issue_number}/labels/{name}
129 
- Acceptance: removes a label from an issue and returns 204.
130 
- Dependencies: E3-T6.
131 
- Subagent ready: yes.
132
133 
## Epic 4: Assignees
134
135 
Goal: implement issue assignment.
136
137 
### E4-T1: Add `OpenAgents.Issues.Assignee` and user participation model
138 
- Acceptance: `OpenAgents.Issues.list_possible_assignees/1` exists.
139 
- Dependencies: E1-T1.
140 
- Subagent ready: no.
141
142 
### E4-T2: GET /api/v3/repos/{owner}/{repo}/assignees
143 
- Acceptance: returns a list of users who can be assigned.
144 
- Dependencies: E4-T1.
145 
- Subagent ready: yes.
146
147 
### E4-T3: GET /api/v3/repos/{owner}/{repo}/assignees/{assignee}
148 
- Acceptance: returns 204 if the user can be assigned and 404 if not.
149 
- Dependencies: E4-T1.
150 
- Subagent ready: yes.
151
152 
### E4-T4: POST /api/v3/repos/{owner}/{repo}/issues/{issue_number}/assignees
153 
- Acceptance: adds assignees and returns the updated issue.
154 
- Dependencies: E1-T1, E4-T1.
155 
- Subagent ready: yes.
156
157 
### E4-T5: DELETE /api/v3/repos/{owner}/{repo}/issues/{issue_number}/assignees
158 
- Acceptance: removes assignees and returns the updated issue.
159 
- Dependencies: E4-T4.
160 
- Subagent ready: yes.
161
162 
## Epic 5: Milestones
163
164 
Goal: implement milestones.
165
166 
### E5-T1: Add `OpenAgents.Issues.Milestone` schema and migration
167 
- Acceptance: `OpenAgents.Issues.create_milestone/2` exists.
168 
- Dependencies: E1-T1.
169 
- Subagent ready: no.
170
171 
### E5-T2: GET /api/v3/repos/{owner}/{repo}/milestones
172 
- Acceptance: returns a list of milestones.
173 
- Dependencies: E5-T1.
174 
- Subagent ready: yes.
175
176 
### E5-T3: POST /api/v3/repos/{owner}/{repo}/milestones
177 
- Acceptance: returns 201 and the created milestone.
178 
- Dependencies: E5-T1.
179 
- Subagent ready: yes.
180
181 
### E5-T4: GET /api/v3/repos/{owner}/{repo}/milestones/{milestone_number}
182 
- Acceptance: returns a single milestone or 404.
183 
- Dependencies: E5-T1.
184 
- Subagent ready: yes.
185
186 
### E5-T5: PATCH /api/v3/repos/{owner}/{repo}/milestones/{milestone_number}
187 
- Acceptance: updates title, state, due date, and description.
188 
- Dependencies: E5-T3.
189 
- Subagent ready: yes.
190
191 
### E5-T6: DELETE /api/v3/repos/{owner}/{repo}/milestones/{milestone_number}
192 
- Acceptance: returns 204 and removes the milestone.
193 
- Dependencies: E5-T3.
194 
- Subagent ready: yes.
195
196 
## Epic 6: Projects V2
197
198 
Goal: implement the Projects V2 read and write surface.
199
200 
### E6-T1: Design the project and item schemas
201 
- Define `Project`, `ProjectField`, `ProjectView`, and `ProjectItem` schemas.
202 
- Acceptance: migrations run and `OpenAgents.Projects.create_project/2` exists.
203 
- Dependencies: none.
204 
- Subagent ready: no.
205
206 
### E6-T2: GET /api/v3/users/{username}/projectsV2
207 
- Acceptance: returns a list of user projects.
208 
- Dependencies: E6-T1.
209 
- Subagent ready: yes.
210
211 
### E6-T3: GET /api/v3/users/{username}/projectsV2/{project_number}
212 
- Acceptance: returns a single project.
213 
- Dependencies: E6-T1.
214 
- Subagent ready: yes.
215
216 
### E6-T4: POST /api/v3/{owner}/projectsV2
217 
- Non-standard endpoint to create a project because the GitHub REST spec does not include it.
218 
- Acceptance: returns 201 and the created project.
219 
- Dependencies: E6-T1.
220 
- Subagent ready: yes.
221
222 
### E6-T5: GET /api/v3/users/{username}/projectsV2/{project_number}/items
223 
- Acceptance: returns a list of project items.
224 
- Dependencies: E6-T1.
225 
- Subagent ready: yes.
226
227 
### E6-T6: POST /api/v3/users/{username}/projectsV2/{project_number}/items
228 
- Acceptance: adds an issue to a project and returns the item.
229 
- Dependencies: E1-T4, E6-T1.
230 
- Subagent ready: yes.
231
232 
### E6-T7: PATCH /api/v3/users/{username}/projectsV2/{project_number}/items/{item_id}
233 
- Acceptance: updates field values on a project item.
234 
- Dependencies: E6-T6.
235 
- Subagent ready: yes.
236
237 
### E6-T8: GET /api/v3/users/{username}/projectsV2/{project_number}/fields
238 
- Acceptance: returns a list of project fields.
239 
- Dependencies: E6-T1.
240 
- Subagent ready: yes.
241
242 
## Parallelization and subagent dispatch
243
244 
### Dependencies
245
246 
| Before | After |
247 
| --- | --- |
248 
| E1-T1 (issue schema) | E1-T2 to E1-T5, E2-T1, E3-T1, E4-T1, E5-T1, E6-T1 can start. |
249 
| E1-T4 (issue create) | E2-T3 to E2-T6, E3-T6, E3-T7, E4-T4, E4-T5, E6-T6. |
250 
| E2-T1 (comment schema) | E2-T2 to E2-T6. |
251 
| E3-T1 (label schema) | E3-T2 to E3-T7. |
252 
| E4-T1 (assignee model) | E4-T2 to E4-T5. |
253 
| E5-T1 (milestone schema) | E5-T2 to E5-T6. |
254 
| E6-T1 (project schema) | E6-T2 to E6-T8. |
255
256 
### Parallel waves
257
258 
**Wave 1 — foundation (serial)**
259 
- E1-T1
260
261 
**Wave 2 — independent contexts and read endpoints (parallel)**
262 
- E1-T2, E1-T3
263 
- E2-T1
264 
- E3-T1, E3-T2, E3-T4
265 
- E4-T1, E4-T2, E4-T3
266 
- E5-T1, E5-T2, E5-T4
267 
- E6-T1, E6-T2, E6-T3, E6-T5, E6-T8
268
269 
**Wave 3 — write endpoints (parallel after Wave 1 + Wave 2)**
270 
- E1-T4, E1-T5
271 
- E2-T3 to E2-T6
272 
- E3-T3, E3-T5, E3-T6, E3-T7
273 
- E4-T4, E4-T5
274 
- E5-T3, E5-T5, E5-T6
275 
- E6-T4, E6-T6, E6-T7
276
277 
### Subagent guidance
278
279 
- Dispatch one `subagent_general` per task marked `subagent ready: yes`.
280 
- Give each subagent the exact `AGENTS.md` rules, the endpoint path, and the expected JSON shape from `docs/github-api-issues-projects-assessment.md`.
281 
- Keep schema and migration work (subagent ready: no) in the main session. Schema is the contract that all other work depends on.
282 
- Before merging parallel work, run `mix precommit` to catch cross-module conflicts and compile warnings.

This page updates live while a promote is in flight · changelog