Make plan handoffs copyable and claimable (#539)

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

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

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/<role>/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/<role>/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" <<ROLEPROMPTEOF
+# ${role} Prompt
+
+You are the \`${role}\` role for OpenSpec plan \`${PLAN_SLUG}\`.
+
+## Objective
+
+Complete only this role's assigned checklist and leave compact evidence for the coordinator.
+
+## Source of truth
+
+- \`openspec/plan/${PLAN_SLUG}/summary.md\`
+- \`openspec/plan/${PLAN_SLUG}/checkpoints.md\`
+- \`openspec/plan/${PLAN_SLUG}/open-questions.md\`
+- \`openspec/plan/${PLAN_SLUG}/${role}/tasks.md\`
+- \`openspec/plan/${PLAN_SLUG}/${role}/proposal.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 <agent-branch> <file...>\`.
+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 <agent-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" <<ROLEPROPOSALEOF
 # Proposal: ${role} (${PLAN_SLUG})

openspec/changes/agent-claude-submodule-aware-gx-2026-05-07-18-46/CHANGE.md

@@ -0,0 +1,70 @@
+---
+base_root_hash: missing-spec-root
+slug: agent-claude-submodule-aware-gx-2026-05-07-18-46
+---
+
+# CHANGE · agent-claude-submodule-aware-gx-2026-05-07-18-46
+
+## §P  proposal
+# 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.
+
+## Sub-tasks
+
+### Sub-task 0: Planner: freeze submodule-aware gx plan
+
+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
+
+### Sub-task 1: Architect: review lifecycle boundaries
+
+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
+
+### Sub-task 2: Executor: implement submodule-aware gx (depends on: 0, 1)
+
+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
+
+### Sub-task 3: Quality review: stress-test executor diff (depends on: 2)
+
+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
+
+### Sub-task 4: Writer: sync operator docs/context (depends on: 2, 3)
+
+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
+
+### Sub-task 5: Verifier: prove submodule-aware lifecycle (depends on: 3, 4)
+
+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
+
+
+## §S  delta
+op|target|row
+-|-|-
+
+## §T  tasks
+id|status|task|cites
+-|-|-|-
+
+## §B  bugs
+id|status|task|cites
+-|-|-|-

openspec/plan/agent-claude-submodule-aware-gx-2026-05-07-18-46/README.md

@@ -8,7 +8,7 @@ Use this command to update checkpoints:
 /opsx:checkpoint agent-claude-submodule-aware-gx-2026-05-07-18-46 <role> <checkpoint-id> <state> <note...>
 ```
 
-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

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 <agent-branch> <file...>`.
+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 <agent-branch> --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence.

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 <agent-branch> <file...>`.
+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 <agent-branch> --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence.

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 <agent-branch> <file...>`.
+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 <agent-branch> --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence.

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 <agent-branch> <file...>`.
+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 <agent-branch> --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence.

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 <agent-branch> <file...>`.
+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 <agent-branch> --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence.

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 <agent-branch> <file...>`.
+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 <agent-branch> --base dev --via-pr --wait-for-merge --cleanup`. If blocked, append `BLOCKED:` with branch, task, blocker, next, evidence.

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.