From 5f3b8b7294a3cda6f3d94f6f7c246c33bd5cf3f7 Mon Sep 17 00:00:00 2001 From: NagyVikt Date: Thu, 7 May 2026 23:09:41 +0200 Subject: [PATCH] Make plan handoffs copyable and claimable Plan-backed work was blocked because role packets existed only as tasks and the existing submodule-aware plan was not registered in Colony. The scaffold now emits per-role prompt.md files in runtime, template, and frontend copies, and the existing plan is backfilled plus published as Colony subtasks. Constraint: Existing submodule-aware plan is already the SSOT; avoid regenerating role proposals/specs into the slim plan. Rejected: Re-run init-plan-workspace against existing plan | would create broad default role artifacts outside the requested prompt backfill. Confidence: high Scope-risk: narrow Directive: Keep runtime/template/frontend scaffold copies aligned when role artifact shape changes. Tested: bash -n scripts/openspec/init-plan-workspace.sh Tested: bash -n templates/scripts/openspec/init-plan-workspace.sh Tested: bash -n frontend/scripts/openspec/init-plan-workspace.sh Tested: node --test --test-name-pattern "OpenSpec plan workspace scaffold creates expected role/task structure" test/branch.test.js Tested: node --test --test-name-pattern=critical.*sync test/metadata.test.js Tested: openspec validate --specs Tested: openspec validate agent-claude-submodule-aware-gx-2026-05-07-18-46 --strict Related: Colony plan agent-claude-submodule-aware-gx-2026-05-07-18-46 task ids 47-52 Not-tested: full npm test --- .../scripts/openspec/init-plan-workspace.sh | 43 +++++ .../CHANGE.md | 70 +++++++++ .../README.md | 2 +- .../architect/prompt.md | 33 ++++ .../critic/prompt.md | 33 ++++ .../executor/prompt.md | 33 ++++ .../planner/prompt.md | 33 ++++ .../verifier/prompt.md | 33 ++++ .../writer/prompt.md | 33 ++++ .../architect.md | 13 ++ .../checkpoints.md | 23 +++ .../critic.md | 13 ++ .../executor.md | 13 ++ .../plan.json | 148 ++++++++++++++++++ .../plan.md | 29 ++++ .../planner.md | 13 ++ .../tasks.md | 10 ++ .../verifier.md | 13 ++ .../writer.md | 13 ++ scripts/openspec/init-plan-workspace.sh | 43 +++++ .../scripts/openspec/init-plan-workspace.sh | 43 +++++ test/branch.test.js | 6 + 22 files changed, 692 insertions(+), 1 deletion(-) create mode 100644 openspec/changes/agent-claude-submodule-aware-gx-2026-05-07-18-46/CHANGE.md create mode 100644 openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect/prompt.md create mode 100644 openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic/prompt.md create mode 100644 openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor/prompt.md create mode 100644 openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner/prompt.md create mode 100644 openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier/prompt.md create mode 100644 openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer/prompt.md create mode 100644 openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect.md create mode 100644 openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/checkpoints.md create mode 100644 openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic.md create mode 100644 openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor.md create mode 100644 openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/plan.json create mode 100644 openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/plan.md create mode 100644 openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner.md create mode 100644 openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/tasks.md create mode 100644 openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier.md create mode 100644 openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer.md diff --git a/frontend/scripts/openspec/init-plan-workspace.sh b/frontend/scripts/openspec/init-plan-workspace.sh index c96dba36..f633e5a5 100755 --- a/frontend/scripts/openspec/init-plan-workspace.sh +++ b/frontend/scripts/openspec/init-plan-workspace.sh @@ -63,6 +63,7 @@ if [[ ! -f "$PLAN_DIR/README.md" ]]; then echo echo "Each role folder contains OpenSpec-style artifacts:" echo "- \`.openspec.yaml\`" + echo "- \`prompt.md\` (copy/paste role prompt)" echo "- \`proposal.md\`" echo "- \`tasks.md\` (Spec / Tests / Implementation / Checkpoints checklists)" echo "- \`specs//spec.md\`" @@ -86,6 +87,7 @@ Drive this plan from draft to execution-ready status with strict checkpoint disc - \`openspec/plan/${PLAN_SLUG}/summary.md\` - \`openspec/plan/${PLAN_SLUG}/checkpoints.md\` - \`openspec/plan/${PLAN_SLUG}/planner/plan.md\` +- role \`prompt.md\` files for copy/paste helper startup - role \`tasks.md\` files for planner/architect/critic/executor/writer/verifier ## Coordinator responsibilities @@ -258,6 +260,7 @@ Role workspace for \`${role}\`. Default artifacts: - \`.openspec.yaml\` +- \`prompt.md\` - \`proposal.md\` - \`tasks.md\` - \`specs//spec.md\` @@ -278,12 +281,52 @@ plan: ${PLAN_SLUG} role: ${role} status: draft artifacts: + prompt: prompt.md proposal: proposal.md tasks: tasks.md spec: specs/${ROLE_SPEC_SLUG}/spec.md ROLEYAMLEOF fi + if [[ ! -f "$ROLE_DIR/prompt.md" ]]; then + cat > "$ROLE_DIR/prompt.md" < \`. +3. Stay inside assigned files/modules; coordinate before touching shared paths. + +## Working rules + +- Update \`${role}/tasks.md\` as each item completes. +- Record durable unresolved questions in \`open-questions.md\`. +- Keep handoffs short: files changed, behavior touched, verification, risks. +- Do not revert another agent's edits. + +## Cleanup + +Only the owner/finalizer lane runs \`gx branch finish --branch --base dev --via-pr --wait-for-merge --cleanup\`. If blocked, append \`BLOCKED:\` with branch, task, blocker, next, evidence. +ROLEPROMPTEOF + fi + if [[ ! -f "$ROLE_DIR/proposal.md" ]]; then cat > "$ROLE_DIR/proposal.md" < ``` -Roles (each has its own `tasks.md`): +Roles (each has its own `tasks.md` and copyable `prompt.md`): - `planner/` — owns spec + open-questions - `architect/` — owns manifest schema + failure catalog diff --git a/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect/prompt.md b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect/prompt.md new file mode 100644 index 00000000..d7761a7f --- /dev/null +++ b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect/prompt.md @@ -0,0 +1,33 @@ +# architect Prompt + +You are the `architect` role for OpenSpec plan `agent-claude-submodule-aware-gx-2026-05-07-18-46`. + +## Objective + +Complete only this role's assigned checklist and leave compact evidence for the coordinator. + +## Source of truth + +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/summary.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/checkpoints.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/open-questions.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect/tasks.md` + +## Before edits + +1. Confirm branch/worktree with `git status --short --branch`. +2. Claim every touched file before editing: + - Prefer Colony `task_claim_file` when an active task exists. + - Otherwise run `gx locks claim --branch `. +3. Stay inside assigned files/modules; coordinate before touching shared paths. + +## Working rules + +- Update `architect/tasks.md` as each item completes. +- Record durable unresolved questions in `open-questions.md`. +- Keep handoffs short: files changed, behavior touched, verification, risks. +- Do not revert another agent's edits. + +## Cleanup + +Only the owner/finalizer lane runs `gx branch finish --branch --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence. diff --git a/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic/prompt.md b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic/prompt.md new file mode 100644 index 00000000..0283a18c --- /dev/null +++ b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic/prompt.md @@ -0,0 +1,33 @@ +# critic Prompt + +You are the `critic` role for OpenSpec plan `agent-claude-submodule-aware-gx-2026-05-07-18-46`. + +## Objective + +Complete only this role's assigned checklist and leave compact evidence for the coordinator. + +## Source of truth + +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/summary.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/checkpoints.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/open-questions.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic/tasks.md` + +## Before edits + +1. Confirm branch/worktree with `git status --short --branch`. +2. Claim every touched file before editing: + - Prefer Colony `task_claim_file` when an active task exists. + - Otherwise run `gx locks claim --branch `. +3. Stay inside assigned files/modules; coordinate before touching shared paths. + +## Working rules + +- Update `critic/tasks.md` as each item completes. +- Record durable unresolved questions in `open-questions.md`. +- Keep handoffs short: files changed, behavior touched, verification, risks. +- Do not revert another agent's edits. + +## Cleanup + +Only the owner/finalizer lane runs `gx branch finish --branch --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence. diff --git a/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor/prompt.md b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor/prompt.md new file mode 100644 index 00000000..3f09a4c9 --- /dev/null +++ b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor/prompt.md @@ -0,0 +1,33 @@ +# executor Prompt + +You are the `executor` role for OpenSpec plan `agent-claude-submodule-aware-gx-2026-05-07-18-46`. + +## Objective + +Complete only this role's assigned checklist and leave compact evidence for the coordinator. + +## Source of truth + +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/summary.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/checkpoints.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/open-questions.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor/tasks.md` + +## Before edits + +1. Confirm branch/worktree with `git status --short --branch`. +2. Claim every touched file before editing: + - Prefer Colony `task_claim_file` when an active task exists. + - Otherwise run `gx locks claim --branch `. +3. Stay inside assigned files/modules; coordinate before touching shared paths. + +## Working rules + +- Update `executor/tasks.md` as each item completes. +- Record durable unresolved questions in `open-questions.md`. +- Keep handoffs short: files changed, behavior touched, verification, risks. +- Do not revert another agent's edits. + +## Cleanup + +Only the owner/finalizer lane runs `gx branch finish --branch --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence. diff --git a/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner/prompt.md b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner/prompt.md new file mode 100644 index 00000000..13f57a58 --- /dev/null +++ b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner/prompt.md @@ -0,0 +1,33 @@ +# planner Prompt + +You are the `planner` role for OpenSpec plan `agent-claude-submodule-aware-gx-2026-05-07-18-46`. + +## Objective + +Complete only this role's assigned checklist and leave compact evidence for the coordinator. + +## Source of truth + +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/summary.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/checkpoints.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/open-questions.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner/tasks.md` + +## Before edits + +1. Confirm branch/worktree with `git status --short --branch`. +2. Claim every touched file before editing: + - Prefer Colony `task_claim_file` when an active task exists. + - Otherwise run `gx locks claim --branch `. +3. Stay inside assigned files/modules; coordinate before touching shared paths. + +## Working rules + +- Update `planner/tasks.md` as each item completes. +- Record durable unresolved questions in `open-questions.md`. +- Keep handoffs short: files changed, behavior touched, verification, risks. +- Do not revert another agent's edits. + +## Cleanup + +Only the owner/finalizer lane runs `gx branch finish --branch --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence. diff --git a/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier/prompt.md b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier/prompt.md new file mode 100644 index 00000000..a3fcc462 --- /dev/null +++ b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier/prompt.md @@ -0,0 +1,33 @@ +# verifier Prompt + +You are the `verifier` role for OpenSpec plan `agent-claude-submodule-aware-gx-2026-05-07-18-46`. + +## Objective + +Complete only this role's assigned checklist and leave compact evidence for the coordinator. + +## Source of truth + +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/summary.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/checkpoints.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/open-questions.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier/tasks.md` + +## Before edits + +1. Confirm branch/worktree with `git status --short --branch`. +2. Claim every touched file before editing: + - Prefer Colony `task_claim_file` when an active task exists. + - Otherwise run `gx locks claim --branch `. +3. Stay inside assigned files/modules; coordinate before touching shared paths. + +## Working rules + +- Update `verifier/tasks.md` as each item completes. +- Record durable unresolved questions in `open-questions.md`. +- Keep handoffs short: files changed, behavior touched, verification, risks. +- Do not revert another agent's edits. + +## Cleanup + +Only the owner/finalizer lane runs `gx branch finish --branch --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence. diff --git a/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer/prompt.md b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer/prompt.md new file mode 100644 index 00000000..efca822a --- /dev/null +++ b/openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer/prompt.md @@ -0,0 +1,33 @@ +# writer Prompt + +You are the `writer` role for OpenSpec plan `agent-claude-submodule-aware-gx-2026-05-07-18-46`. + +## Objective + +Complete only this role's assigned checklist and leave compact evidence for the coordinator. + +## Source of truth + +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/summary.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/checkpoints.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/open-questions.md` +- `openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer/tasks.md` + +## Before edits + +1. Confirm branch/worktree with `git status --short --branch`. +2. Claim every touched file before editing: + - Prefer Colony `task_claim_file` when an active task exists. + - Otherwise run `gx locks claim --branch `. +3. Stay inside assigned files/modules; coordinate before touching shared paths. + +## Working rules + +- Update `writer/tasks.md` as each item completes. +- Record durable unresolved questions in `open-questions.md`. +- Keep handoffs short: files changed, behavior touched, verification, risks. +- Do not revert another agent's edits. + +## Cleanup + +Only the owner/finalizer lane runs `gx branch finish --branch --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence. diff --git a/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect.md b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect.md new file mode 100644 index 00000000..6074e232 --- /dev/null +++ b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect.md @@ -0,0 +1,13 @@ +# Architect + +Plan: `agent-claude-submodule-aware-gx-2026-05-07-18-46` + +## Responsibility + +Check boundaries, data flow, interfaces, and rollback shape. + +## Checkpoints + +- [ ] Read `plan.md`, `tasks.md`, and `checkpoints.md`. +- [ ] Record decisions or blockers in the plan workspace before handoff. +- [ ] Keep task-thread status aligned with local files. diff --git a/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/checkpoints.md b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/checkpoints.md new file mode 100644 index 00000000..3187611c --- /dev/null +++ b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/checkpoints.md @@ -0,0 +1,23 @@ +# Checkpoints + +## Rollup + +- available: 6 +- claimed: 0 +- completed: 0 +- blocked: 0 + +## Subtasks + +- [ ] sub-0 Planner: freeze submodule-aware gx plan [available] +- [ ] sub-1 Architect: review lifecycle boundaries [available] +- [ ] sub-2 Executor: implement submodule-aware gx [available] +- [ ] sub-3 Quality review: stress-test executor diff [available] +- [ ] sub-4 Writer: sync operator docs/context [available] +- [ ] sub-5 Verifier: prove submodule-aware lifecycle [available] + +## Completion Gate + +- [ ] All subtasks complete. +- [ ] Spec change archived or explicitly marked not applicable. +- [ ] Verification evidence recorded. diff --git a/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic.md b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic.md new file mode 100644 index 00000000..7f7da03f --- /dev/null +++ b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic.md @@ -0,0 +1,13 @@ +# Critic + +Plan: `agent-claude-submodule-aware-gx-2026-05-07-18-46` + +## Responsibility + +Challenge weak assumptions, hidden risks, and missing tests. + +## Checkpoints + +- [ ] Read `plan.md`, `tasks.md`, and `checkpoints.md`. +- [ ] Record decisions or blockers in the plan workspace before handoff. +- [ ] Keep task-thread status aligned with local files. diff --git a/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor.md b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor.md new file mode 100644 index 00000000..c839f33e --- /dev/null +++ b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor.md @@ -0,0 +1,13 @@ +# Executor + +Plan: `agent-claude-submodule-aware-gx-2026-05-07-18-46` + +## Responsibility + +Implement claimed subtasks inside declared file scope. + +## Checkpoints + +- [ ] Read `plan.md`, `tasks.md`, and `checkpoints.md`. +- [ ] Record decisions or blockers in the plan workspace before handoff. +- [ ] Keep task-thread status aligned with local files. diff --git a/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/plan.json b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/plan.json new file mode 100644 index 00000000..522d2666 --- /dev/null +++ b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/plan.json @@ -0,0 +1,148 @@ +{ + "schema_version": 1, + "plan_slug": "agent-claude-submodule-aware-gx-2026-05-07-18-46", + "title": "Submodule-aware gx role plan", + "problem": "The existing OpenSpec plan workspace for submodule-aware gx has role tasks and prompt packets in-repo, but Colony had no published claimable plan, so helper agents could not claim planner, architect, executor, critic, writer, and verifier lanes from the coordination surface.", + "acceptance_criteria": [ + "Colony exposes claimable role subtasks for the existing submodule-aware gx plan.", + "Each role subtask points to its plan prompt.md and tasks.md packet plus owned implementation files where applicable.", + "Downstream agents claim files before edits and record verification or blockers in the role task handoff fields." + ], + "roles": [ + "planner", + "architect", + "critic", + "executor", + "writer", + "verifier" + ], + "tasks": [ + { + "subtask_index": 0, + "title": "Planner: freeze submodule-aware gx plan", + "description": "Use planner/prompt.md and planner/tasks.md to finish spec/open-question planning for the existing submodule-aware gx plan. Keep durable questions in the plan workspace and hand off execution boundaries.", + "file_scope": [ + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner/tasks.md", + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner/prompt.md" + ], + "depends_on": [], + "spec_row_id": null, + "capability_hint": "doc_work", + "status": "available", + "claimed_by_session_id": null, + "claimed_by_agent": null, + "completed_summary": null + }, + { + "subtask_index": 1, + "title": "Architect: review lifecycle boundaries", + "description": "Use architect/prompt.md and architect/tasks.md to validate submodule lifecycle boundaries, manifests, token preflight, and failure modes before implementation.", + "file_scope": [ + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect/tasks.md", + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect/prompt.md" + ], + "depends_on": [], + "spec_row_id": null, + "capability_hint": "infra_work", + "status": "available", + "claimed_by_session_id": null, + "claimed_by_agent": null, + "completed_summary": null + }, + { + "subtask_index": 2, + "title": "Executor: implement submodule-aware gx", + "description": "Use executor/prompt.md and executor/tasks.md to add tests first, then implement submodule detection, lock tuple keying, start/finish wiring, and gx subcommands inside the approved scope.", + "file_scope": [ + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor/tasks.md", + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor/prompt.md", + "scripts/agent-submodules.py", + "scripts/agent-branch-start.sh", + "scripts/agent-branch-finish.sh", + "scripts/agent-file-locks.py", + "scripts/codex-agent.sh", + "bin/gx", + "test/agent-submodules-detect.test.js", + "test/agent-submodules-locks.test.py", + "test/agent-submodules-finish.test.js", + "test/agent-submodules-preflight.test.js" + ], + "depends_on": [ + 0, + 1 + ], + "spec_row_id": null, + "capability_hint": "infra_work", + "status": "available", + "claimed_by_session_id": null, + "claimed_by_agent": null, + "completed_summary": null + }, + { + "subtask_index": 3, + "title": "Quality review: stress-test executor diff", + "description": "Use critic/prompt.md and critic/tasks.md to review executor output for unclaimed edits, stranded submodule writes, atomic gitlink bump correctness, and missing negative scenarios.", + "file_scope": [ + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic/tasks.md", + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic/prompt.md" + ], + "depends_on": [ + 2 + ], + "spec_row_id": null, + "capability_hint": "infra_work", + "status": "available", + "claimed_by_session_id": null, + "claimed_by_agent": null, + "completed_summary": null + }, + { + "subtask_index": 4, + "title": "Writer: sync operator docs/context", + "description": "Use writer/prompt.md and writer/tasks.md to update only approved user-facing workflow docs/context after implementation behavior is final.", + "file_scope": [ + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer/tasks.md", + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer/prompt.md", + "AGENTS.md", + "README.md", + "openspec/specs/gitguardex-submodules/context.md" + ], + "depends_on": [ + 2, + 3 + ], + "spec_row_id": null, + "capability_hint": "doc_work", + "status": "available", + "claimed_by_session_id": null, + "claimed_by_agent": null, + "completed_summary": null + }, + { + "subtask_index": 5, + "title": "Verifier: prove submodule-aware lifecycle", + "description": "Use verifier/prompt.md and verifier/tasks.md to run OpenSpec, focused node/python tests, and the approved walkthrough proof or record exact blockers.", + "file_scope": [ + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier/tasks.md", + "openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier/prompt.md" + ], + "depends_on": [ + 3, + 4 + ], + "spec_row_id": null, + "capability_hint": "test_work", + "status": "available", + "claimed_by_session_id": null, + "claimed_by_agent": null, + "completed_summary": null + } + ], + "published": { + "spec_task_id": 46, + "spec_change_path": "/home/deadpool/Documents/recodee/gitguardex/.omx/agent-worktrees/gitguardex__codex__codex-task-2026-05-07-22-43/openspec/changes/agent-claude-submodule-aware-gx-2026-05-07-18-46/CHANGE.md", + "auto_archive": false + }, + "created_at": "2026-05-07T21:04:27.771Z", + "updated_at": "2026-05-07T21:04:27.771Z" +} diff --git a/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/plan.md b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/plan.md new file mode 100644 index 00000000..2b9bdce4 --- /dev/null +++ b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/plan.md @@ -0,0 +1,29 @@ +# Submodule-aware gx role plan + +Plan slug: `agent-claude-submodule-aware-gx-2026-05-07-18-46` + +## Problem + +The existing OpenSpec plan workspace for submodule-aware gx has role tasks and prompt packets in-repo, but Colony had no published claimable plan, so helper agents could not claim planner, architect, executor, critic, writer, and verifier lanes from the coordination surface. + +## Acceptance Criteria + +- Colony exposes claimable role subtasks for the existing submodule-aware gx plan. +- Each role subtask points to its plan prompt.md and tasks.md packet plus owned implementation files where applicable. +- Downstream agents claim files before edits and record verification or blockers in the role task handoff fields. + +## Roles + +- [planner](./planner.md) +- [architect](./architect.md) +- [critic](./critic.md) +- [executor](./executor.md) +- [writer](./writer.md) +- [verifier](./verifier.md) + +## Operator Flow + +1. Refine this workspace until scope, risks, and tasks are explicit. +2. Publish the plan with `colony plan publish agent-claude-submodule-aware-gx-2026-05-07-18-46` or the `task_plan_publish` MCP tool. +3. Claim subtasks through Colony plan tools before editing files. +4. Close only when all subtasks are complete and `checkpoints.md` records final evidence. diff --git a/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner.md b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner.md new file mode 100644 index 00000000..ee8b2247 --- /dev/null +++ b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner.md @@ -0,0 +1,13 @@ +# Planner + +Plan: `agent-claude-submodule-aware-gx-2026-05-07-18-46` + +## Responsibility + +Clarify scope, sequencing, dependencies, and acceptance criteria. + +## Checkpoints + +- [ ] Read `plan.md`, `tasks.md`, and `checkpoints.md`. +- [ ] Record decisions or blockers in the plan workspace before handoff. +- [ ] Keep task-thread status aligned with local files. diff --git a/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/tasks.md b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/tasks.md new file mode 100644 index 00000000..a1fd090b --- /dev/null +++ b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/tasks.md @@ -0,0 +1,10 @@ +# Tasks + +| # | Status | Title | Files | Depends on | Capability | Spec row | Owner | +| - | - | - | - | - | - | - | - | +0|available|Planner: freeze submodule-aware gx plan|`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner/tasks.md`
`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/planner/prompt.md`|-|doc_work|-|- +1|available|Architect: review lifecycle boundaries|`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect/tasks.md`
`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/architect/prompt.md`|-|infra_work|-|- +2|available|Executor: implement submodule-aware gx|`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor/tasks.md`
`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/executor/prompt.md`
`scripts/agent-submodules.py`
`scripts/agent-branch-start.sh`
`scripts/agent-branch-finish.sh`
`scripts/agent-file-locks.py`
`scripts/codex-agent.sh`
`bin/gx`
`test/agent-submodules-detect.test.js`
`test/agent-submodules-locks.test.py`
`test/agent-submodules-finish.test.js`
`test/agent-submodules-preflight.test.js`|0, 1|infra_work|-|- +3|available|Quality review: stress-test executor diff|`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic/tasks.md`
`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/critic/prompt.md`|2|infra_work|-|- +4|available|Writer: sync operator docs/context|`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer/tasks.md`
`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer/prompt.md`
`AGENTS.md`
`README.md`
`openspec/specs/gitguardex-submodules/context.md`|2, 3|doc_work|-|- +5|available|Verifier: prove submodule-aware lifecycle|`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier/tasks.md`
`openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier/prompt.md`|3, 4|test_work|-|- diff --git a/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier.md b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier.md new file mode 100644 index 00000000..9a937757 --- /dev/null +++ b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/verifier.md @@ -0,0 +1,13 @@ +# Verifier + +Plan: `agent-claude-submodule-aware-gx-2026-05-07-18-46` + +## Responsibility + +Prove completion with focused tests and explicit evidence. + +## Checkpoints + +- [ ] Read `plan.md`, `tasks.md`, and `checkpoints.md`. +- [ ] Record decisions or blockers in the plan workspace before handoff. +- [ ] Keep task-thread status aligned with local files. diff --git a/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer.md b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer.md new file mode 100644 index 00000000..167c69fd --- /dev/null +++ b/openspec/plans/agent-claude-submodule-aware-gx-2026-05-07-18-46/writer.md @@ -0,0 +1,13 @@ +# Writer + +Plan: `agent-claude-submodule-aware-gx-2026-05-07-18-46` + +## Responsibility + +Keep docs, operator notes, and final handoff language accurate. + +## Checkpoints + +- [ ] Read `plan.md`, `tasks.md`, and `checkpoints.md`. +- [ ] Record decisions or blockers in the plan workspace before handoff. +- [ ] Keep task-thread status aligned with local files. diff --git a/scripts/openspec/init-plan-workspace.sh b/scripts/openspec/init-plan-workspace.sh index 12d10d43..095f00b6 100755 --- a/scripts/openspec/init-plan-workspace.sh +++ b/scripts/openspec/init-plan-workspace.sh @@ -84,6 +84,7 @@ if [[ ! -f "$PLAN_DIR/README.md" ]]; then echo echo "Each role folder contains OpenSpec-style artifacts:" echo "- \`.openspec.yaml\`" + echo "- \`prompt.md\` (copy/paste role prompt)" echo "- \`proposal.md\`" echo "- \`tasks.md\` (Spec / Tests / Implementation / Checkpoints checklists)" echo "- \`specs//spec.md\`" @@ -108,6 +109,7 @@ Drive this plan from draft to execution-ready status with strict checkpoint disc - \`openspec/plan/${PLAN_SLUG}/checkpoints.md\` - \`openspec/plan/${PLAN_SLUG}/open-questions.md\` - \`openspec/plan/${PLAN_SLUG}/planner/plan.md\` +- role \`prompt.md\` files for copy/paste helper startup - role \`tasks.md\` files for planner/architect/critic/executor/writer/verifier ## Coordinator responsibilities @@ -282,6 +284,7 @@ Role workspace for \`${role}\`. Default artifacts: - \`.openspec.yaml\` +- \`prompt.md\` - \`proposal.md\` - \`tasks.md\` - \`specs//spec.md\` @@ -302,12 +305,52 @@ plan: ${PLAN_SLUG} role: ${role} status: draft artifacts: + prompt: prompt.md proposal: proposal.md tasks: tasks.md spec: specs/${ROLE_SPEC_SLUG}/spec.md ROLEYAMLEOF fi + if [[ ! -f "$ROLE_DIR/prompt.md" ]]; then + cat > "$ROLE_DIR/prompt.md" < \`. +3. Stay inside assigned files/modules; coordinate before touching shared paths. + +## Working rules + +- Update \`${role}/tasks.md\` as each item completes. +- Record durable unresolved questions in \`open-questions.md\`. +- Keep handoffs short: files changed, behavior touched, verification, risks. +- Do not revert another agent's edits. + +## Cleanup + +Only the owner/finalizer lane runs \`gx branch finish --branch --base dev --via-pr --wait-for-merge --cleanup\`. If blocked, append \`BLOCKED:\` with branch, task, blocker, next, evidence. +ROLEPROMPTEOF + fi + if [[ ! -f "$ROLE_DIR/proposal.md" ]]; then cat > "$ROLE_DIR/proposal.md" </spec.md\`" @@ -108,6 +109,7 @@ Drive this plan from draft to execution-ready status with strict checkpoint disc - \`openspec/plan/${PLAN_SLUG}/checkpoints.md\` - \`openspec/plan/${PLAN_SLUG}/open-questions.md\` - \`openspec/plan/${PLAN_SLUG}/planner/plan.md\` +- role \`prompt.md\` files for copy/paste helper startup - role \`tasks.md\` files for planner/architect/critic/executor/writer/verifier ## Coordinator responsibilities @@ -282,6 +284,7 @@ Role workspace for \`${role}\`. Default artifacts: - \`.openspec.yaml\` +- \`prompt.md\` - \`proposal.md\` - \`tasks.md\` - \`specs//spec.md\` @@ -302,12 +305,52 @@ plan: ${PLAN_SLUG} role: ${role} status: draft artifacts: + prompt: prompt.md proposal: proposal.md tasks: tasks.md spec: specs/${ROLE_SPEC_SLUG}/spec.md ROLEYAMLEOF fi + if [[ ! -f "$ROLE_DIR/prompt.md" ]]; then + cat > "$ROLE_DIR/prompt.md" < \`. +3. Stay inside assigned files/modules; coordinate before touching shared paths. + +## Working rules + +- Update \`${role}/tasks.md\` as each item completes. +- Record durable unresolved questions in \`open-questions.md\`. +- Keep handoffs short: files changed, behavior touched, verification, risks. +- Do not revert another agent's edits. + +## Cleanup + +Only the owner/finalizer lane runs \`gx branch finish --branch --base dev --via-pr --wait-for-merge --cleanup\`. If blocked, append \`BLOCKED:\` with branch, task, blocker, next, evidence. +ROLEPROMPTEOF + fi + if [[ ! -f "$ROLE_DIR/proposal.md" ]]; then cat > "$ROLE_DIR/proposal.md" < /); + assert.match(executorPrompt, /gx branch finish --branch --base dev --via-pr --wait-for-merge --cleanup/); + const phasesContent = fs.readFileSync(path.join(planDir, 'phases.md'), 'utf8'); assert.match(phasesContent, /\[PH01\]/); assert.match(phasesContent, /session: codex/);