# Ghostex Manage Beads

> Ghostex 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.

- Skill name: `ghostex-manage-beads`
- Category: [Productivity](https://www.openparable.com/skill/productivity/1)
- Source: https://github.com/maddada/Ghostex/blob/HEAD/skills/ghostex-manage-beads/SKILL.md
- Repository: maddada/Ghostex (629 GitHub stars when collected)

## SKILL.md

# 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 `.beads` JSONL export.
- Use `gx bd`, not raw `bd`, so commands run through Ghostex's bundled Beads
  binary instead of a shell-installed version.
- Prefer `gx bd --help` and `gx bd <command> --help` as 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

1. Inspect current work:

   ```bash
   gx bd list --json
   gx bd show <id> --json
   gx bd comments <id> --json
   ```

2. Move the bead through project swimlanes:

   ```bash
   gx bd update <id> --status in_progress
   gx bd update <id> --status test
   gx bd update <id> --status review
   gx bd close <id>
   ```

3. After each meaningful turn, add a short human-readable comment:

   ```bash
   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:

```bash
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:

```bash
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 as
  `S90:P3lv0:G5jjo`.
- `GHOSTEX_NATIVE_SESSION_ID`: native project/session id, such as
  `P3lv0:G5jjo`.
- `GHOSTEX_SESSION_ID`: provider session id, such as `G5jjo`.
- `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

```bash
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.

---

Source: https://www.openparable.com/skill/productivity/ghostex-manage-beads (OpenParable). Cite the canonical URL above.
