You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 933744b
Browse filesBrowse the repository at this point in the historyBrowse files
Add plan schema, import format, and plan-author prompt
- schema/plan.schema.json: plan format v1, strict-mode compatible, used by
claude --json-schema and codex exec --output-schema and for imports.
- schema/plan-edit.schema.json: typed plan-assistant suggestions.
- schema/examples/: #412 r3 plan (YAML) and a suggestion reply.
- docs/plan-format.md: plain-language guide, checks after import, versions.
- prompts/plan-author.md: one prompt for both agents.
- Design doc: rewrite "The plan format", add decision P1 and task T18,
list the four new approved mockups.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: docs/designs/codeboost-plan-indexed-review.md
+56-6Lines changed: 56 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,6 +34,7 @@ Writing standard: plain language, ISO 24495-1:2023
34
34
|---|---|
35
35
| Plan | A list of plan items for one GitHub issue. Each plan has a revision number (r1, r2, …). |
36
36
| Plan item | One change in the plan, with an ID such as P1. It lists the files it will change and how to check it. |
37
+
| Plan schema | The file that defines the structure every plan must have (`schema/plan.schema.json`). Agents answer in it, and imported plans are checked against it. |
37
38
| Declared files | The files a plan item says it will change. |
38
39
| Invocation | One run of an AI agent (Claude or Codex) on one task. |
39
40
| Trailer | A line at the end of a git commit message, such as `Plan-Item: P1`. |
@@ -124,21 +125,37 @@ These are proposals. The engineering review will confirm them.
124
125
125
126
### The plan format
126
127
127
-
Each plan looks like this:
128
+
Changed by decision P1 (below, in the Decision ledger). The full rules are in [`docs/plan-format.md`](../plan-format.md).
129
+
130
+
-**One schema is the contract.**[`schema/plan.schema.json`](../../schema/plan.schema.json) defines every plan, version 1. codeboost passes it to Claude (`claude -p --json-schema`) or Codex (`codex exec --output-schema`) when they draft a plan, and checks every imported plan against it.
131
+
-**YAML and JSON have the same structure.** People read and write YAML; agents return JSON. Every field is always present, with `null` or `[]` when it has nothing to say.
132
+
-**Each declared file carries its own change.** A file entry has a path, a kind (`edit`, `add`, `delete`, or `rename`), the old path for a rename, and what changes in it. This keeps the plan file by file (step 3).
133
+
-**Acceptance entries are typed.**`cmd` is a command codeboost runs. `check` is a statement the review agent judges.
134
+
-**After the schema, codeboost checks meaning.** For example: unique IDs, `depends_on` only to earlier items, no `..` in paths, and declared files that exist. A failure blocks approval; a warning, such as "No test command", does not.
135
+
136
+
Each plan looks like this (shortened; the full example is [`schema/examples/plan-412-r3.yaml`](../../schema/examples/plan-412-r3.yaml)):
128
137
129
138
```yaml
139
+
schema_version: 1
130
140
issue: 412
131
141
revision: 3
142
+
summary: Keep the Idempotency-Key header on every retry.
intent: Every retry must send the same key as the first attempt.
147
+
files: # declared files (signal 2), each with its change
148
+
- path: src/retry/client.go
149
+
kind: edit
150
+
renamed_from: null
151
+
change: Read the key once before the loop and set it on every attempt.
138
152
acceptance:
139
-
- cmd: pnpm test -- retry.test.ts # a command codeboost runs
140
-
- check: key is set on every attempt, not only the first # the review agent judges this
153
+
- type: cmd # a command codeboost runs
154
+
text: go test ./src/retry/... -run TestRetryKeepsKey
155
+
- type: check # the review agent judges this
156
+
text: The key is set on every attempt, not only the first.
141
157
depends_on: []
158
+
questions: [] # open choices the agent wants you to decide
142
159
```
143
160
144
161
**Where the plan lives.** The plan is not committed to the PR branch. Instead, codeboost writes it into the PR description, between two markers: `<!-- codeboost:plan:start -->` and `<!-- codeboost:plan:end -->`.
@@ -1716,6 +1733,30 @@ Actual answer: A) Track and flag (answer to D24, 2026-09-22)
1716
1733
Accepted scope: per repo, codeboost tracks rejections per task, review rounds per task, and repeated feedback (new feedback the distilling agent matches to an approved lesson); a Learning screen shows these over time; a lesson whose feedback keeps repeating is flagged for rewording or removal. Test cases: repeated feedback matching an approved lesson increments its repeat count and flags it after a set number of repeats.
1717
1734
History: none
1718
1735
1736
+
### P1: One plan schema for drafting, importing, and suggestions
1737
+
Finding: request from you (2026-09-22): "Codex or Claude should be able to generate plans. Should we create a template for them to follow and that we can directly import from", reviewer: Claude (after the design review)
1738
+
Plan baseline: "The plan format" showed a YAML example with free-text `changes` for all files of an item and untyped `cmd:` / `check:` lines. Nothing defined which fields are required, how an agent's answer is parsed, or how a hand-written plan is imported.
- Both CLIs returned a plan for a test issue that passed `schema/plan.schema.json`, and a suggested edit that passed `schema/plan-edit.schema.json`.
1742
+
- Claude Code rejected the schema while it had a `$schema` line for draft 2020-12 ("no schema with key or ref"), and accepted it without that line.
1743
+
- `codex exec` waits on stdin when stdin is not a terminal; it must run with stdin closed.
1744
+
Comparison grid:
1745
+
1746
+
| Choice | Current | A | B | C |
1747
+
|---|---|---|---|---|
1748
+
| How agents answer | not defined | JSON that must match one schema, enforced by the CLI flag | Markdown or YAML text that codeboost parses | free text that a second agent converts |
1749
+
| Importing a plan file | not possible | YAML or JSON, checked by the same schema | YAML only, with a hand-written parser | not possible |
1750
+
| Plan assistant suggestions | not defined | typed edit operations (second schema); Apply is exact | free text; the person edits by hand | free text; an agent applies it |
1751
+
| Checks after the schema | none | unique IDs, earlier-only dependencies, safe paths, files exist; failures block approval | same | same |
1752
+
| Versioning | none | `schema_version` in every plan | none | none |
1753
+
1754
+
Question: asked in conversation, not as a numbered question. Claude recommended A.
1755
+
State: approved
1756
+
Actual answer: yes, add it to the design doc and create them (2026-09-22)
1757
+
Accepted scope: one versioned plan schema (`schema/plan.schema.json`) and one edit schema (`schema/plan-edit.schema.json`), both strict-mode compatible and without a `$schema` line; YAML and JSON with the same structure; a plain-language guide (`docs/plan-format.md`); one prompt template for both agents (`prompts/plan-author.md`); worked examples in `schema/examples/`; import on the Plans screen as the next draft revision; checks after import as listed in the guide. Test cases: both examples pass; broken plans (no acceptance, extra field, bad ID, absolute path, unknown kind, no files, wrong version, missing field) fail; the edit schema's copied definitions match the plan schema's; a recorded Claude answer and a recorded Codex answer both pass.
1758
+
History: none
1759
+
1719
1760
Approval readiness: PASS (re-checked after the learning requirement). Checked L1 (D21: A), L2 (D22: A), L3 (D23: A), L4 (D24: A), D1 (scope, structure B), R1 (D2: B), R2 (D3: A), R3 (D4: A), R4 (D5: A), R5 (D6: B), R6 (D7: A), R7 (D8: A), R8 (D9: A), T1 (D10: A), O1 (D11: A), O2 (D12: A), O3 (D13: A), O4 (D14: A), O5 (D15: A), O6 (D16: A), O7 (D17: A), O8 (D18: A), O9 (D19: A). Every accepted change cites its own answer. No TODO proposals were raised by this review; the design's existing Open questions stay as written.
1720
1761
1721
1762
### Outside voice
@@ -1736,6 +1777,7 @@ Codex (outside voice, completed, 2026-09-22) raised 8 findings. Claude checked e
1736
1777
- **Claude CLI** already provides `--disallowedTools`, `--strict-mcp-config`, and `setup-token`. Used for the network and sign-in rules.
1737
1778
- **Codex CLI** already provides `--sandbox` and `CODEX_HOME`. Used for the sign-in mount.
1738
1779
- **Node 26** has `node:sqlite` built in. Used as the only storage engine.
1780
+
- **Claude CLI and Codex CLI** both take a JSON Schema for their final answer: `claude -p --json-schema` and `codex exec --output-schema`. Used for plan drafting and plan suggestions (P1). Tested on 2026-09-22 with Claude Code 2.1.278 and Codex CLI 0.153.4.
1739
1781
1740
1782
Nothing in the repo is rebuilt.
1741
1783
@@ -1886,6 +1928,10 @@ Built from this review's findings. Each task comes from a specific decision abov
1886
1928
- Surfaced by: L4 (D24: A)
1887
1929
- Files: web/learning, runner/metrics
1888
1930
- Verify: repeated feedback matching an approved lesson raises its count and flags it
1931
+
- [ ] **T18 (P2, human: ~2 days / CC: ~45 min)** — core, agents, web — Plan schema: draft plans with either agent, import YAML or JSON, apply typed suggestions
1932
+
- Surfaced by: P1 (approved 2026-09-22)
1933
+
- Files: schema/, docs/plan-format.md, prompts/plan-author.md, core/plan (schema and meaning checks), agents/claude, agents/codex, web/plans (Import plan, suggestion cards)
1934
+
- Verify: both examples pass and 8 broken plans fail; recorded Claude and Codex answers pass; a plan with a `..` path or a dependency loop cannot be approved; the edit schema's copied definitions match; `codex exec` runs with stdin closed
1889
1935
1890
1936
### Unresolved decisions
1891
1937
@@ -1976,6 +2022,10 @@ None proposed. Every fix is in the plan and in the tasks below.
1976
2022
| Review screen | /Users/maxhwang/.gstack/projects/codeboost/designs/updated-after-design-review-20260922/review-screen.png | Three panes: compact plan-item list, code with Approve button, and Ask / Request change conversation | Highlight the current page, not Settings (D13). Earlier reference: mockup-20260922/variant-B.png |
1977
2023
| Lessons inbox | /Users/maxhwang/.gstack/projects/codeboost/designs/updated-after-design-review-20260922/lessons-inbox.png | Compact sortable, filterable table; rows expand in place; bulk Discard only | Earlier pick: lessons-inbox-20260922/r5/variant-B.png. Menu highlight follows D13 |
1978
2024
| Learning screen | /Users/maxhwang/.gstack/projects/codeboost/designs/updated-after-design-review-20260922/learning-screen.png | Three tiles, task-number chart, flagged-lessons table | Key strip must follow D24 (there is no "Dashboard"). Menu highlight follows D13 |
2025
+
| Issues | /Users/maxhwang/.gstack/projects/codeboost/designs/issues-screen-20260922/variant-A.png | Triage table: score and word, rows expand to "Why it ranks", untrusted issue text, trust step for outside authors | Approved 2026-09-22 (/design-shotgun). HTML: issues-screen-20260922/finalized.html |
2026
+
| Plans (plan editor) | /Users/maxhwang/.gstack/projects/codeboost/designs/plans-screen-20260922/variant-C.png | Plan table with rows that expand to edit; plan assistant in a bottom drawer | Approved 2026-09-22. Fields follow P1's schema. HTML: plans-screen-20260922/finalized.html |
2027
+
| Queue | /Users/maxhwang/.gstack/projects/codeboost/designs/queue-screen-20260922/variant-A.png | Run-state bar, "Waiting for you" rows with one action each, reorderable "Up next" table | Approved 2026-09-22, without the mockup's duplicate left list. HTML: queue-screen-20260922/finalized.html |
2028
+
| Settings | /Users/maxhwang/.gstack/projects/codeboost/designs/settings-screen-20260922/variant-C.png | Health checklist first, then grouped settings | Approved 2026-09-22. Values come from this document, not the mockup. HTML: settings-screen-20260922/finalized.html |
0 commit comments