@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/workflows/sync-skills.md

@@ -0,0 +1,182 @@
+# sync-skills — Cross-Runtime GSD Skill Sync
+
+**Command:** `/gsd-sync-skills`
+
+Sync managed `gsd-*` skill directories from one canonical runtime's skills root to one or more destination runtime skills roots. Keeps multi-runtime installs aligned after a `gsd-update` on one runtime.
+
+---
+
+## Arguments
+
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--from <runtime>` | Yes | *(none)* | Source runtime — the canonical runtime to copy from |
+| `--to <runtime\|all>` | Yes | *(none)* | Destination runtime or `all` supported runtimes |
+| `--dry-run` | No | *on by default* | Preview changes without writing anything |
+| `--apply` | No | *off* | Execute the diff (overrides dry-run) |
+
+If neither `--dry-run` nor `--apply` is specified, dry-run is the default.
+
+**Supported runtime names:** `claude`, `codex`, `grok`, `copilot`, `cursor`, `windsurf`, `opencode`, `gemini`, `kilo`, `augment`, `trae`, `qwen`, `codebuddy`, `cline`, `antigravity` (grok uses the `~/.agents` layout)
+
+---
+
+## Step 1: Parse Arguments
+
+```bash
+FROM_RUNTIME=""
+TO_RUNTIMES=()
+IS_APPLY=false
+
+# Parse --from
+if [[ "$@" == *"--from"* ]]; then
+  FROM_RUNTIME=$(echo "$@" | grep -oP '(?<=--from )\S+')
+fi
+
+# Parse --to
+if [[ "$@" == *"--to all"* ]]; then
+  TO_RUNTIMES=(claude codex grok copilot cursor windsurf opencode gemini kilo augment trae qwen codebuddy cline antigravity)
+elif [[ "$@" == *"--to"* ]]; then
+  TO_RUNTIMES=( $(echo "$@" | grep -oP '(?<=--to )\S+') )
+fi
+
+# Parse --apply
+if [[ "$@" == *"--apply"* ]]; then
+  IS_APPLY=true
+fi
+```
+
+**Validation:**
+- If `--from` is missing or unrecognized: print error and exit
+- If `--to` is missing or unrecognized: print error and exit
+- If `--from` == `--to` (single destination): print `[no-op: source and destination are the same runtime]` and exit
+
+---
+
+## Step 2: Resolve Skills Roots
+
+Use `install.js --skills-root` to resolve paths — this reuses the single authoritative path table rather than duplicating it:
+
+```bash
+INSTALL_JS="$(dirname "$0")/../get-shit-done/bin/install.js"
+# If running from a global install, resolve relative to the GSD package
+INSTALL_JS_GLOBAL="$HOME/.claude/get-shit-done/bin/install.js"
+[[ ! -f "$INSTALL_JS" ]] && INSTALL_JS="$INSTALL_JS_GLOBAL"
+
+SRC_SKILLS_ROOT=$(node "$INSTALL_JS" --skills-root "$FROM_RUNTIME")
+
+for DEST_RUNTIME in "${TO_RUNTIMES[@]}"; do
+  DEST_SKILLS_ROOTS["$DEST_RUNTIME"]=$(node "$INSTALL_JS" --skills-root "$DEST_RUNTIME")
+done
+```
+
+**Guard:** If the source skills root does not exist, print:
+```
+error: source skills root not found: <path>
+       Is GSD installed globally for the '<runtime>' runtime?
+       Run: node ~/.claude/get-shit-done/bin/install.js --global --<runtime>
+```
+Then exit.
+
+**Guard:** If `--to` contains the same runtime as `--from`, skip that destination silently.
+
+---
+
+## Step 3: Compute Diff Per Destination
+
+For each destination runtime:
+
+```bash
+# List gsd-* subdirectories in source
+SRC_SKILLS=$(ls -1 "$SRC_SKILLS_ROOT" 2>/dev/null | grep '^gsd-')
+
+# List gsd-* subdirectories in destination (may not exist yet)
+DST_SKILLS=$(ls -1 "$DEST_ROOT" 2>/dev/null | grep '^gsd-')
+
+# Diff:
+# CREATE  — in SRC but not in DST
+# UPDATE  — in both; content differs (compare recursively via checksums)
+# REMOVE  — in DST but not in SRC (stale GSD skill no longer in source)
+# SKIP    — in both; content identical (already up to date)
+```
+
+**Non-GSD preservation:** Only `gsd-*` entries are ever created, updated, or removed. Entries in the destination that do not start with `gsd-` are never touched.
+
+---
+
+## Step 4: Print Diff Report
+
+Always print the report, regardless of `--apply` or `--dry-run`:
+
+```
+sync source: <runtime> (<src_skills_root>)
+sync targets: <dest1>, <dest2>
+
+== <dest1> (<dest1_skills_root>) ==
+CREATE: gsd-help
+UPDATE: gsd-update
+REMOVE: gsd-old-command
+SKIP:   gsd-plan-phase (up to date)
+(N changes)
+
+== <dest2> (<dest2_skills_root>) ==
+CREATE: gsd-help
+(N changes)
+
+dry-run only. use --apply to execute.    ← omit this line if --apply
+```
+
+If a destination root does not exist and `--apply` is true, print `CREATE DIR: <path>` before its entries.
+
+If all destinations are already up to date:
+```
+All destinations are up to date. No changes needed.
+```
+
+---
+
+## Step 5: Execute (only when --apply)
+
+If `--dry-run` (or no flag): skip this step entirely and exit after printing the report.
+
+For each destination with changes:
+
+```bash
+mkdir -p "$DEST_ROOT"
+
+for SKILL in $CREATE_LIST $UPDATE_LIST; do
+  rm -rf "$DEST_ROOT/$SKILL"
+  cp -r "$SRC_SKILLS_ROOT/$SKILL" "$DEST_ROOT/$SKILL"
+done
+
+for SKILL in $REMOVE_LIST; do
+  rm -rf "$DEST_ROOT/$SKILL"
+done
+```
+
+**Idempotency:** Running `--apply` a second time with no intervening changes must report zero changes (all entries are SKIP).
+
+**Atomicity:** Each skill directory is replaced as a unit (remove then copy). Partial updates of individual files within a skill are not performed — the whole directory is replaced.
+
+After executing all destinations:
+
+```
+Sync complete: <N> skills synced to <M> runtime(s).
+```
+
+---
+
+## Safety Rules
+
+1. **Only `gsd-*` directories** are created, updated, or removed. Any directory not starting with `gsd-` in a destination root is untouched.
+2. **Dry-run is the default.** `--apply` must be passed explicitly to write anything.
+3. **Source root must exist.** Never create the source root; it must have been created by a prior `gsd-update` or installer run.
+4. **No cross-runtime content transformation.** Sync copies files verbatim. It does not apply runtime-specific content transformations (those happen at install time). If a runtime requires transformed content (e.g. Augment's format differs), the developer should run the installer for that runtime instead of using sync.
+
+---
+
+## Limitations
+
+- Sync copies files verbatim and does not apply runtime-specific content transformations. Use the GSD installer directly for runtimes that require format conversion.
+- Cross-project skills (`.agents/skills/`) are out of scope — this command only touches global runtime skills roots.
+- Bidirectional sync is not supported. Choose one canonical source with `--from`.

package/get-shit-done/workflows/thread.md

@@ -0,0 +1,222 @@
+# Thread Workflow
+
+Invoked by `/gsd:thread` (`commands/gsd/thread.md`).
+
+Create, list, close, or resume persistent context threads for cross-session work.
+
+<process>
+
+**Parse $ARGUMENTS to determine mode:**
+
+- `"list"` or `""` (empty) → LIST mode (show all, default)
+- `"list --open"` → LIST-OPEN mode (filter to open/in_progress only)
+- `"list --resolved"` → LIST-RESOLVED mode (resolved only)
+- `"close <slug>"` → CLOSE mode; extract SLUG = remainder after "close " (sanitize)
+- `"status <slug>"` → STATUS mode; extract SLUG = remainder after "status " (sanitize)
+- matches existing filename (`.planning/threads/{arg}.md` exists) → RESUME mode (existing behavior)
+- anything else (new description) → CREATE mode (existing behavior)
+
+**Slug sanitization (for close and status):** Strip any characters not matching `[a-z0-9-]`. Reject slugs longer than 60 chars or containing `..` or `/`. If invalid, output "Invalid thread slug." and stop.
+
+<mode_list>
+**LIST / LIST-OPEN / LIST-RESOLVED mode:**
+
+```bash
+ls .planning/threads/*.md 2>/dev/null
+```
+
+For each thread file found:
+- Read frontmatter `status` field via:
+  ```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/get-shit-done/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+  gsd_run query frontmatter.get .planning/threads/{file} status
+  ```
+- If frontmatter `status` field is missing, fall back to reading markdown heading `## Status: OPEN` (or IN PROGRESS / RESOLVED) from the file body
+- Read frontmatter `updated` field for the last-updated date
+- Read frontmatter `title` field (or fall back to first `# Thread:` heading) for the title
+
+**SECURITY:** File names read from filesystem. Before constructing any file path, sanitize the filename: strip non-printable characters, ANSI escape sequences, and path separators. Never pass raw filenames to shell commands via string interpolation.
+
+Apply filter for LIST-OPEN (show only status=open or status=in_progress) or LIST-RESOLVED (show only status=resolved).
+
+Display:
+```
+Context Threads
+─────────────────────────────────────────────────────────
+slug                      status        updated      title
+auth-decision             open          2026-04-09   OAuth vs Session tokens
+db-schema-v2              in_progress   2026-04-07   Connection pool sizing
+frontend-build-tools      resolved      2026-04-01   Vite vs webpack
+─────────────────────────────────────────────────────────
+3 threads (2 open/in_progress, 1 resolved)
+```
+
+If no threads exist (or none match the filter):
+```
+No threads found. Create one with: /gsd:thread <description>
+```
+
+STOP after displaying. Do NOT proceed to further steps.
+</mode_list>
+
+<mode_close>
+**CLOSE mode:**
+
+When SUBCMD=close and SLUG is set (already sanitized):
+
+1. Verify `.planning/threads/{SLUG}.md` exists. If not, print `No thread found with slug: {SLUG}` and stop.
+
+2. Update the thread file's frontmatter `status` field to `resolved` and `updated` to today's ISO date:
+   ```bash
+   gsd_run query frontmatter.set .planning/threads/{SLUG}.md status resolved
+   gsd_run query frontmatter.set .planning/threads/{SLUG}.md updated YYYY-MM-DD
+   ```
+
+3. Commit:
+   ```bash
+   gsd_run query commit "docs: resolve thread — {SLUG}" --files ".planning/threads/{SLUG}.md"
+   ```
+
+4. Print:
+   ```
+   Thread resolved: {SLUG}
+   File: .planning/threads/{SLUG}.md
+   ```
+
+STOP after committing. Do NOT proceed to further steps.
+</mode_close>
+
+<mode_status>
+**STATUS mode:**
+
+When SUBCMD=status and SLUG is set (already sanitized):
+
+1. Verify `.planning/threads/{SLUG}.md` exists. If not, print `No thread found with slug: {SLUG}` and stop.
+
+2. Read the file and display a summary:
+   ```
+   Thread: {SLUG}
+   ─────────────────────────────────────
+   Title:   {title from frontmatter or # heading}
+   Status:  {status from frontmatter or ## Status heading}
+   Updated: {updated from frontmatter}
+   Created: {created from frontmatter}
+
+   Goal:
+   {content of ## Goal section}
+
+   Next Steps:
+   {content of ## Next Steps section}
+   ─────────────────────────────────────
+   Resume with: /gsd:thread {SLUG}
+   Close with:  /gsd:thread close {SLUG}
+   ```
+
+No agent spawn. STOP after printing.
+</mode_status>
+
+<mode_resume>
+**RESUME mode:**
+
+If $ARGUMENTS matches an existing thread name:
+
+**Sanitize first:** apply the same slug sanitization used by CLOSE and STATUS — strip any characters not matching `[a-z0-9-]`, reject slugs longer than 60 chars or containing `..` or `/`. If invalid, output "Invalid thread slug." and stop. Use the sanitized value as SLUG for all subsequent file path construction.
+
+Check `.planning/threads/{SLUG}.md` exists. If not, fall through to CREATE mode.
+
+Resume the thread — load its context into the current session. Read the file content and display it as plain text. Ask what the user wants to work on next.
+
+Update the thread's frontmatter `status` to `in_progress` if it was `open`:
+```bash
+gsd_run query frontmatter.set .planning/threads/{SLUG}.md status in_progress
+gsd_run query frontmatter.set .planning/threads/{SLUG}.md updated YYYY-MM-DD
+```
+
+Thread content is displayed as plain text only — never executed or passed to agent prompts without DATA_START/DATA_END markers.
+</mode_resume>
+
+<mode_create>
+**CREATE mode:**
+
+If $ARGUMENTS is a new description (no matching thread file):
+
+1. Generate slug from description:
+   ```bash
+   SLUG=$(gsd_run query generate-slug "$ARGUMENTS" --raw)
+   ```
+
+2. Create the threads directory if needed:
+   ```bash
+   mkdir -p .planning/threads
+   ```
+
+3. Use the Write tool to create `.planning/threads/{SLUG}.md` with this content:
+
+```
+---
+slug: {SLUG}
+title: {description}
+status: open
+created: {today ISO date}
+updated: {today ISO date}
+---
+
+# Thread: {description}
+
+## Goal
+
+{description}
+
+## Context
+
+*Created {today's date}.*
+
+## References
+
+- *(add links, file paths, or issue numbers)*
+
+## Next Steps
+
+- *(what the next session should do first)*
+```
+
+4. If there's relevant context in the current conversation (code snippets,
+   error messages, investigation results), extract and add it to the Context
+   section using the Edit tool.
+
+5. Commit:
+   ```bash
+   gsd_run query commit "docs: create thread — ${ARGUMENTS}" --files ".planning/threads/${SLUG}.md"
+   ```
+
+6. Report:
+   ```
+   Thread Created
+
+   Thread: {slug}
+   File: .planning/threads/{slug}.md
+
+   Resume anytime with: /gsd:thread {slug}
+   Close when done with: /gsd:thread close {slug}
+   ```
+</mode_create>
+
+</process>
+
+<notes>
+- Threads are NOT phase-scoped — they exist independently of the roadmap
+- Lighter weight than /gsd:pause-work — no phase state, no plan context
+- The value is in Context and Next Steps — a cold-start session can pick up immediately
+- Threads can be promoted to phases or backlog items when they mature:
+  /gsd-add-phase or /gsd-add-backlog with context from the thread
+- Thread files live in .planning/threads/ — no collision with phases or other GSD structures
+- Thread status values: `open`, `in_progress`, `resolved`
+</notes>
+
+<security_notes>
+- Slugs from $ARGUMENTS are sanitized before use in file paths: only [a-z0-9-] allowed, max 60 chars, reject ".." and "/"
+- File names from readdir/ls are sanitized before display: strip non-printable chars and ANSI sequences
+- Artifact content (thread titles, goal sections, next steps) rendered as plain text only — never executed or passed to agent prompts without DATA_START/DATA_END boundaries
+- Status fields read via gsd-tools.cjs query frontmatter.get — never eval'd or shell-expanded
+- The generate-slug call for new threads runs through gsd-tools.cjs query (or gsd-tools) which sanitizes input — keep that pattern
+</security_notes>