diff --git a/AGENTS.md b/AGENTS.md index b009532..21192bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -237,11 +237,13 @@ Use `openspec/plan/README.md` as the operational runbook and `openspec/plan/PLAN Default quick flow: 1. Create/maintain `openspec/plan//`. -2. Keep role `tasks.md` files current (`planner`, `architect`, `critic`, `executor`, `writer`, `verifier`). -3. Keep checklist headings visible: `## 1. Spec`, `## 2. Tests`, `## 3. Implementation`, `## 4. Checkpoints`, plus a final cleanup section (`## 5. Cleanup` or `## 6. Cleanup`). -4. Update checkboxes continuously while work progresses. -5. Execute from approved `planner/plan.md` with role ownership. -6. Verify with evidence before archive/finish. +2. Create/maintain `openspec/plan//open-questions.md`. +3. Keep `open-questions.md` current; when Codex/Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it there as an unchecked `- [ ]` item. +4. Keep role `tasks.md` files current (`planner`, `architect`, `critic`, `executor`, `writer`, `verifier`). +5. Keep checklist headings visible: `## 1. Spec`, `## 2. Tests`, `## 3. Implementation`, `## 4. Checkpoints`, plus a final cleanup section (`## 5. Cleanup` or `## 6. Cleanup`). +6. Update checkboxes continuously while work progresses. +7. Execute from approved `planner/plan.md` with role ownership. +8. Verify with evidence before archive/finish. Helper sub-branch exception: - When a helper branch targets another `agent/*` owner branch, implementation is allowed in helper lanes, but OpenSpec change/spec/tasks artifacts stay owned by the owner branch. @@ -279,6 +281,8 @@ OMX completion policy: when a task is done, the agent must commit the task chang **Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups. +**Open questions.** If Codex/Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it in `openspec/plan//open-questions.md` as an unchecked `- [ ]` item. Resolve it in-place when answered instead of burying it in chat-only notes. + **OpenSpec (when change-driven).** Keep `openspec/changes//tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `gx branch finish ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified. **Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog. diff --git a/openspec/changes/agent-codex-record-codex-open-questions-in-plan-work-2026-04-22-18-25/proposal.md b/openspec/changes/agent-codex-record-codex-open-questions-in-plan-work-2026-04-22-18-25/proposal.md new file mode 100644 index 0000000..f39177e --- /dev/null +++ b/openspec/changes/agent-codex-record-codex-open-questions-in-plan-work-2026-04-22-18-25/proposal.md @@ -0,0 +1,20 @@ +# Proposal: record codex open questions in plan workspace + +## Why + +- The repo contract keeps planning artifacts in-repo, but unresolved questions can still disappear into chat-only notes. +- The user wants a durable `plans/open-questions` rule that behaves the same way across repos. +- The current plan scaffold does not create an `open-questions.md` file, so the contract has no concrete landing zone. + +## What Changes + +- [ ] Add an `open-questions.md` requirement to the live repo contract and reusable multiagent template. +- [ ] Add committed `openspec/plan` guidance describing how open questions should be recorded. +- [ ] Update the plan-workspace scaffold to create `open-questions.md` and point roles/coordinators at it. +- [ ] Seed this task's plan workspace with the exact three joined-session questions from the user. + +## Impact + +- Scope: AGENTS contract, reusable template, OpenSpec plan docs, plan scaffold. +- Risks: Low; wording drift between live and templated docs if one surface is missed. +- Dependencies: `scripts/openspec/init-plan-workspace.sh` and `templates/scripts/openspec/init-plan-workspace.sh` must stay in sync. diff --git a/openspec/changes/agent-codex-record-codex-open-questions-in-plan-work-2026-04-22-18-25/specs/plan-open-questions/spec.md b/openspec/changes/agent-codex-record-codex-open-questions-in-plan-work-2026-04-22-18-25/specs/plan-open-questions/spec.md new file mode 100644 index 0000000..4c9d6fe --- /dev/null +++ b/openspec/changes/agent-codex-record-codex-open-questions-in-plan-work-2026-04-22-18-25/specs/plan-open-questions/spec.md @@ -0,0 +1,23 @@ +# Capability Spec: plan-open-questions + +## ADDED Requirements + +### Requirement: Plan workspaces capture unresolved questions + +Plan workspaces SHALL provide `open-questions.md` for unresolved questions that must survive chat history. + +#### Scenario: Agent hits a branching question during planning + +- **WHEN** Codex or Claude reaches an unresolved question, branching decision, or blocker during plan-driven work +- **THEN** it records that question in `openspec/plan//open-questions.md` +- **AND** the question appears as an unchecked checklist item until resolved + +### Requirement: Guardex contract points to the same question log + +The repo contract SHALL route unresolved questions into the active plan workspace instead of chat-only notes. + +#### Scenario: Multi-agent or plan-driven work needs durable questions + +- **WHEN** the repo contract describes collaboration, planning, or handoff rules +- **THEN** it points agents to `openspec/plan//open-questions.md` +- **AND** the plan scaffold creates that file by default diff --git a/openspec/changes/agent-codex-record-codex-open-questions-in-plan-work-2026-04-22-18-25/tasks.md b/openspec/changes/agent-codex-record-codex-open-questions-in-plan-work-2026-04-22-18-25/tasks.md new file mode 100644 index 0000000..dbfc7f9 --- /dev/null +++ b/openspec/changes/agent-codex-record-codex-open-questions-in-plan-work-2026-04-22-18-25/tasks.md @@ -0,0 +1,29 @@ +# Tasks + +## 1. Contract + +- [x] 1.1 Update `AGENTS.md` to require `openspec/plan//open-questions.md` for unresolved questions. +- [x] 1.2 Update `templates/AGENTS.multiagent-safety.md` with the same open-questions rule. + +## 2. OpenSpec Plan Docs + +- [x] 2.1 Add `openspec/plan/README.md` with the shared open-questions workflow. +- [x] 2.2 Add `openspec/plan/PLANS.md` with planner-specific question discipline. + +## 3. Scaffold + +- [x] 3.1 Update `scripts/openspec/init-plan-workspace.sh` to create and reference `open-questions.md`. +- [x] 3.2 Update `templates/scripts/openspec/init-plan-workspace.sh` to stay in template parity. +- [x] 3.3 Regenerate this task's plan workspace and seed the user-provided questions. + +## 4. Verification + +- [x] 4.1 Read the final diff to confirm the live contract, template contract, and scaffold all mention `open-questions.md`. +- [x] 4.2 Run the plan-workspace scaffold for this task and confirm `open-questions.md` is created. +- [x] 4.3 Run focused shell verification for modified docs/scripts and record results. + +## 5. Cleanup + +- [ ] 5.1 Finish the branch with `gx branch finish --branch agent/codex/record-codex-open-questions-in-plan-work-2026-04-22-18-25 --base main --via-pr --wait-for-merge --cleanup`. +- [ ] 5.2 Record PR URL + final `MERGED` state in the handoff. +- [ ] 5.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or append `BLOCKED:` and stop. diff --git a/openspec/plan/PLANS.md b/openspec/plan/PLANS.md new file mode 100644 index 0000000..a9c8df5 --- /dev/null +++ b/openspec/plan/PLANS.md @@ -0,0 +1,23 @@ +# Planner Contract + +`planner/plan.md` is the durable narrative for the active `openspec/plan//` workspace. + +## Keep these in sync + +- `summary.md` for scope and current status +- `phases.md` for session-sized execution slices +- `checkpoints.md` for timestamped planning handoffs +- `open-questions.md` for unresolved decisions that must survive chat + +## Question discipline + +Do not bury unresolved planning questions in chat transcripts or one-off handoff notes. +When a question affects scope, sequencing, safety, or implementation shape, add it to `open-questions.md` as an unchecked `- [ ]` item. + +Questions should be: + +- concrete +- decision-shaped +- easy to verify once answered + +When a question is resolved, either check it off with the answer inline or move the final decision into `planner/plan.md` and leave a short resolution note in `open-questions.md`. diff --git a/openspec/plan/README.md b/openspec/plan/README.md new file mode 100644 index 0000000..68efa6f --- /dev/null +++ b/openspec/plan/README.md @@ -0,0 +1,32 @@ +# OpenSpec Plan Workspaces + +Use `openspec/plan//` for durable planning artifacts that must survive chat history. + +## Required shared files + +- `summary.md` +- `checkpoints.md` +- `phases.md` +- `open-questions.md` +- `coordinator-prompt.md` +- `kickoff-prompts.md` when wave splitting is needed + +## Open questions rule + +When Codex or Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it in `openspec/plan//open-questions.md` as an unchecked `- [ ]` item. + +Example checklist: + +- [ ] Should finish override be allowed when joined sessions are active, and if yes what exact flag/guard text should be used? +- [ ] Do we want join-mode sessions to be persisted only by PID or by a stable explicit session id generated at join time? +- [ ] Should lock registry entries carry joined session identity in this first iteration, or deferred to a follow-up change? + +Avoid vague notes like `- [ ] Figure out join mode somehow`. + +Close questions in place with the answer, linked evidence, or a checked item once the decision is made. + +## Minimum role hygiene + +- Keep role `tasks.md` checklists current. +- Record joined-agent handoffs in the relevant role workspace. +- Push unresolved plan questions into `open-questions.md` instead of chat-only notes. diff --git a/scripts/openspec/init-plan-workspace.sh b/scripts/openspec/init-plan-workspace.sh index b664569..12d10d4 100755 --- a/scripts/openspec/init-plan-workspace.sh +++ b/scripts/openspec/init-plan-workspace.sh @@ -50,17 +50,38 @@ Chronological checkpoint log for all roles. CPTEOF fi +if [[ ! -f "$PLAN_DIR/open-questions.md" ]]; then + cat > "$PLAN_DIR/open-questions.md" </open-questions.md` as an unchecked `- [ ]` item. Resolve it in-place when answered instead of burying it in chat-only notes. + **OpenSpec (when change-driven).** Keep `openspec/changes//tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `gx branch finish ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified. **Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog. diff --git a/templates/scripts/openspec/init-plan-workspace.sh b/templates/scripts/openspec/init-plan-workspace.sh index b664569..12d10d4 100755 --- a/templates/scripts/openspec/init-plan-workspace.sh +++ b/templates/scripts/openspec/init-plan-workspace.sh @@ -50,17 +50,38 @@ Chronological checkpoint log for all roles. CPTEOF fi +if [[ ! -f "$PLAN_DIR/open-questions.md" ]]; then + cat > "$PLAN_DIR/open-questions.md" <