Ghostex Manage Beads
Productivityghostex-manage-beadsGhostex Manage Beads is an Agent Skill for productivity published in the maddada/Ghostex repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use this skill when managing Ghostex project board beads with Ghostex's bundled `gx bd` Beads CLI wrapper: creating, updating, commenting on, reviewing, closing, or associating beads with the current Ghostex or Codex session. It covers the project swimlane workflow, session-link comments, external refs, and safe examples for making review beads like the current session association workflow.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/maddada/Ghostex/blob/HEAD/skills/ghostex-manage-beads/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ghostex-manage-beads, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
ghostex-manage-beads
Use this skill when a user asks to manage project board beads, create or update review tasks, move work through bead statuses, add bead comments, or associate a bead with the current Ghostex or Codex session.
Requirements
- Run bead commands from the repository root so Beads finds the project database
and
.beadsJSONL export. - Use
gx bd, not rawbd, so commands run through Ghostex's bundled Beads binary instead of a shell-installed version. - Prefer
gx bd --helpandgx bd <command> --helpas the source of truth for the bundled Beads version. - Inspect nearby beads before creating a new one so title, labels, status, and external-ref style match the project.
Core Workflow
-
Inspect current work:
gx bd list --json gx bd show <id> --json gx bd comments <id> --json -
Move the bead through project swimlanes:
gx bd update <id> --status in_progress gx bd update <id> --status test gx bd update <id> --status review gx bd close <id> -
After each meaningful turn, add a short human-readable comment:
gx bd comment <id> "<summary>"
Keep comments focused on user-facing requirements delivered and high-level technical approach. Do not require humans to read the agent transcript to know what changed.
Create A Review Bead
Use a review bead when the implementation is ready for another pass:
gx bd create "Review <specific change>" \
--type task \
--priority P2 \
--labels review,<area> \
--external-ref "codex-thread:$CODEX_THREAD_ID" \
--description "<review focus, files or areas, verification, known blockers>" \
--json
gx bd update <id> --status review
If CODEX_THREAD_ID is missing, omit the external ref rather than inventing
one.
Associate A Bead With The Current Session
Prefer a bead comment for full session association because external-ref holds
one stable reference and comments can include both Ghostex and Codex ids:
gx bd comment <id> "Associated session: Ghostex ${GHOSTEX_GLOBAL_SESSION_REF:-unknown} / ${GHOSTEX_NATIVE_SESSION_ID:-unknown}, Codex thread ${CODEX_THREAD_ID:-unknown}. <brief work summary and verification status>."
Useful environment variables when present:
GHOSTEX_GLOBAL_SESSION_REF: full Ghostex session reference, such asS90:P3lv0:G5jjo.GHOSTEX_NATIVE_SESSION_ID: native project/session id, such asP3lv0:G5jjo.GHOSTEX_SESSION_ID: provider session id, such asG5jjo.CODEX_THREAD_ID: current Codex thread id.
When creating a new bead for the current agent session, set
--external-ref "codex-thread:$CODEX_THREAD_ID" and add the Ghostex session ids
in a comment.
Example: Session-Associated Review Bead
gx bd create "Review companion CEF flicker layout-key fix" \
--type task \
--priority P2 \
--labels cef,native-sidebar,review \
--external-ref "codex-thread:$CODEX_THREAD_ID" \
--description "Review the geometry-only native layout-key extraction for companion terminal focus changes. Verify focused tests, typecheck, and any known unrelated blockers." \
--json
gx bd update <new-id> --status review
gx bd comment <new-id> "Associated session: Ghostex ${GHOSTEX_GLOBAL_SESSION_REF:-unknown} / ${GHOSTEX_NATIVE_SESSION_ID:-unknown}, Codex thread ${CODEX_THREAD_ID:-unknown}. Implemented geometry-only native layout-key extraction so companion session clicks no longer classify active-tab focus changes as AppKit layout changes; focused tests and typecheck passed."
Safety
- Do not delete or close beads unless the user explicitly asks or the work is genuinely done.
- Do not overwrite unrelated bead descriptions or labels when a comment is enough.
- Keep bead comments free of secrets, command output, private file contents, and unnecessary paths.