3 Commits
Author SHA1 Message Date
Sascha König 39952ceb02 docs: propose client labels for per-client content selection
Add docs/proposals/client-labels.md: an optional agent-lib.labels.json in
the work repository, a "labels" field in the client config (admin-pinned),
filtering before planning with deselected items following the
upstream-deletion rules, plus status and validate support.

Tracked as beads issue agent_lib-fh4.
2026-11-14 10:35:48 +01:00
m3ta-chiron d6821c6d7c feat(vendor): add rename command for deployed item names
- Add `vendor rename <source> [upstream-id=name ...] [--reset ids]` to change deployed names after `vendor add`, without moving the pinned rev or selection
- Persist renames in the lockfile so they survive `vendor update` and `vendor select`
- Rewrite SKILL.md frontmatter `name:` to the folder name so OpenCode loads renamed skills
- Validate rename targets: single path segment, no leading dot, and OpenCode skill naming rules for skills
- Re-run collision checks before writing; failed renames leave lockfile and external area untouched
- Add unit tests for frontmatter rewrite and name validation, plus e2e rename coverage
- Document renames in README; sync beads issue export
2026-11-05 08:48:52 +01:00
m3tam3re f37c3dce5e bd init: initialize beads issue tracking 2026-11-01 14:04:16 +01:00
29 changed files with 1386 additions and 2 deletions

No files matched your search

+80
View File
@@ -0,0 +1,80 @@
---
name: beads
description: Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking.
---
# Beads
Use Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work.
## First Step
Run:
```bash
bd prime
```
If that prints nothing, check whether the repository has an active Beads workspace:
```bash
bd where
```
## Preferred Route
Use the `bd` CLI when shell access is available. It is the most compact and direct Beads interface.
## Core CLI Workflow
1. Find work:
```bash
bd ready
bd list --status=open
bd list --status=in_progress
```
2. Inspect before editing:
```bash
bd show <id>
```
3. Claim work atomically:
```bash
bd update <id> --claim
```
4. Create durable follow-up work when implementation reveals new tasks:
```bash
bd create "Short title" --description="Why this exists and what needs to be done" --type=task --priority=2
```
5. Close completed work:
```bash
bd close <id> --reason="Completed"
```
## What Belongs In Beads
Use Beads for:
- shared project tasks
- blockers and dependencies
- discovered follow-up work
- work that must survive thread reset, compaction, or handoff
- status that another person or agent should be able to resume
Use agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state.
## Rules
- Do not create markdown TODO files as the source of truth when Beads is available.
- Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead.
- Prefer `--json` when parsing `bd` output programmatically.
- If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing.
- Do not auto-close or mutate tasks unless the work is actually complete.
+4
View File
@@ -0,0 +1,4 @@
interface:
display_name: "Beads"
short_description: "Project task tracking with bd"
default_prompt: "Use $beads to inspect ready work and manage durable project tasks."
+1
View File
@@ -0,0 +1 @@
{"size":51360,"mtime_ns":1793863936779644645}
+7
View File
@@ -68,3 +68,10 @@ bd.db
# They would override fork protection in .git/info/exclude.
# Config files (metadata.json, config.yaml) are tracked by git by default
# since no pattern above ignores them.
# Added by bd (missing required patterns)
*.gate.lock*
last_pull
proxieddb/
dolt-server-config.yaml
proxied_server_client_info.json
+4
View File
@@ -1 +1,5 @@
no-git-ops: true
sync:
remote: "git+ssh://gitea@code.m3ta.dev/m3tam3re/agent-lib.git"
export:
auto: true
+59
View File
@@ -0,0 +1,59 @@
#!/usr/bin/env sh
# --- BEGIN BEADS INTEGRATION v1.3.2 ---
# This section is managed by beads. Do not remove these markers.
if command -v bd >/dev/null 2>&1; then
export BD_GIT_HOOK=1
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
case "$_bd_timeout" in
*[!0-9]*|'') _bd_timeout_invalid=1 ;;
*[1-9]*) _bd_timeout_invalid=0 ;;
*) _bd_timeout_invalid=1 ;;
esac
if [ "$_bd_timeout_invalid" -eq 1 ]; then
echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
_bd_timeout=300
fi
_bd_timeout_backend=none
_bd_timeout_command=
for _bd_timeout_candidate in timeout gtimeout; do
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
case "$_bd_timeout_version" in
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
esac
fi
fi
done
if [ -n "$_bd_timeout_command" ]; then
_bd_timeout_backend=coreutils
if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run post-checkout "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
elif command -v perl >/dev/null 2>&1; then
_bd_timeout_backend=perl
if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run post-checkout "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
else
echo >&2 "beads: hook 'post-checkout' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
if bd hooks run post-checkout "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
fi
if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
echo >&2 "beads: hook 'post-checkout' timed out after ${_bd_timeout}s — continuing without beads"
_bd_exit=0
fi
if [ "$_bd_exit" -eq 3 ]; then
echo >&2 "beads: database not initialized — skipping hook 'post-checkout'"
_bd_exit=0
fi
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
fi
# --- END BEADS INTEGRATION v1.3.2 ---
+59
View File
@@ -0,0 +1,59 @@
#!/usr/bin/env sh
# --- BEGIN BEADS INTEGRATION v1.3.2 ---
# This section is managed by beads. Do not remove these markers.
if command -v bd >/dev/null 2>&1; then
export BD_GIT_HOOK=1
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
case "$_bd_timeout" in
*[!0-9]*|'') _bd_timeout_invalid=1 ;;
*[1-9]*) _bd_timeout_invalid=0 ;;
*) _bd_timeout_invalid=1 ;;
esac
if [ "$_bd_timeout_invalid" -eq 1 ]; then
echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
_bd_timeout=300
fi
_bd_timeout_backend=none
_bd_timeout_command=
for _bd_timeout_candidate in timeout gtimeout; do
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
case "$_bd_timeout_version" in
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
esac
fi
fi
done
if [ -n "$_bd_timeout_command" ]; then
_bd_timeout_backend=coreutils
if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run post-merge "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
elif command -v perl >/dev/null 2>&1; then
_bd_timeout_backend=perl
if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run post-merge "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
else
echo >&2 "beads: hook 'post-merge' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
if bd hooks run post-merge "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
fi
if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
echo >&2 "beads: hook 'post-merge' timed out after ${_bd_timeout}s — continuing without beads"
_bd_exit=0
fi
if [ "$_bd_exit" -eq 3 ]; then
echo >&2 "beads: database not initialized — skipping hook 'post-merge'"
_bd_exit=0
fi
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
fi
# --- END BEADS INTEGRATION v1.3.2 ---
+59
View File
@@ -0,0 +1,59 @@
#!/usr/bin/env sh
# --- BEGIN BEADS INTEGRATION v1.3.2 ---
# This section is managed by beads. Do not remove these markers.
if command -v bd >/dev/null 2>&1; then
export BD_GIT_HOOK=1
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
case "$_bd_timeout" in
*[!0-9]*|'') _bd_timeout_invalid=1 ;;
*[1-9]*) _bd_timeout_invalid=0 ;;
*) _bd_timeout_invalid=1 ;;
esac
if [ "$_bd_timeout_invalid" -eq 1 ]; then
echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
_bd_timeout=300
fi
_bd_timeout_backend=none
_bd_timeout_command=
for _bd_timeout_candidate in timeout gtimeout; do
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
case "$_bd_timeout_version" in
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
esac
fi
fi
done
if [ -n "$_bd_timeout_command" ]; then
_bd_timeout_backend=coreutils
if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run pre-commit "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
elif command -v perl >/dev/null 2>&1; then
_bd_timeout_backend=perl
if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run pre-commit "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
else
echo >&2 "beads: hook 'pre-commit' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
if bd hooks run pre-commit "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
fi
if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
echo >&2 "beads: hook 'pre-commit' timed out after ${_bd_timeout}s — continuing without beads"
_bd_exit=0
fi
if [ "$_bd_exit" -eq 3 ]; then
echo >&2 "beads: database not initialized — skipping hook 'pre-commit'"
_bd_exit=0
fi
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
fi
# --- END BEADS INTEGRATION v1.3.2 ---
+59
View File
@@ -0,0 +1,59 @@
#!/usr/bin/env sh
# --- BEGIN BEADS INTEGRATION v1.3.2 ---
# This section is managed by beads. Do not remove these markers.
if command -v bd >/dev/null 2>&1; then
export BD_GIT_HOOK=1
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
case "$_bd_timeout" in
*[!0-9]*|'') _bd_timeout_invalid=1 ;;
*[1-9]*) _bd_timeout_invalid=0 ;;
*) _bd_timeout_invalid=1 ;;
esac
if [ "$_bd_timeout_invalid" -eq 1 ]; then
echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
_bd_timeout=300
fi
_bd_timeout_backend=none
_bd_timeout_command=
for _bd_timeout_candidate in timeout gtimeout; do
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
case "$_bd_timeout_version" in
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
esac
fi
fi
done
if [ -n "$_bd_timeout_command" ]; then
_bd_timeout_backend=coreutils
if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run pre-push "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
elif command -v perl >/dev/null 2>&1; then
_bd_timeout_backend=perl
if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run pre-push "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
else
echo >&2 "beads: hook 'pre-push' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
if bd hooks run pre-push "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
fi
if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
echo >&2 "beads: hook 'pre-push' timed out after ${_bd_timeout}s — continuing without beads"
_bd_exit=0
fi
if [ "$_bd_exit" -eq 3 ]; then
echo >&2 "beads: database not initialized — skipping hook 'pre-push'"
_bd_exit=0
fi
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
fi
# --- END BEADS INTEGRATION v1.3.2 ---
+59
View File
@@ -0,0 +1,59 @@
#!/usr/bin/env sh
# --- BEGIN BEADS INTEGRATION v1.3.2 ---
# This section is managed by beads. Do not remove these markers.
if command -v bd >/dev/null 2>&1; then
export BD_GIT_HOOK=1
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
case "$_bd_timeout" in
*[!0-9]*|'') _bd_timeout_invalid=1 ;;
*[1-9]*) _bd_timeout_invalid=0 ;;
*) _bd_timeout_invalid=1 ;;
esac
if [ "$_bd_timeout_invalid" -eq 1 ]; then
echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
_bd_timeout=300
fi
_bd_timeout_backend=none
_bd_timeout_command=
for _bd_timeout_candidate in timeout gtimeout; do
if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
case "$_bd_timeout_version" in
"timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
esac
fi
fi
done
if [ -n "$_bd_timeout_command" ]; then
_bd_timeout_backend=coreutils
if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run prepare-commit-msg "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
elif command -v perl >/dev/null 2>&1; then
_bd_timeout_backend=perl
if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run prepare-commit-msg "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
else
echo >&2 "beads: hook 'prepare-commit-msg' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
if bd hooks run prepare-commit-msg "$@"; then
_bd_exit=0
else
_bd_exit=$?
fi
fi
if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
echo >&2 "beads: hook 'prepare-commit-msg' timed out after ${_bd_timeout}s — continuing without beads"
_bd_exit=0
fi
if [ "$_bd_exit" -eq 3 ]; then
echo >&2 "beads: database not initialized — skipping hook 'prepare-commit-msg'"
_bd_exit=0
fi
if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
fi
# --- END BEADS INTEGRATION v1.3.2 ---
+2
View File
@@ -1,3 +1,5 @@
{"_type":"issue","id":"agent_lib-fh4","title":"Client labels: deliver items only to clients with a matching label","description":"Design: docs/proposals/client-labels.md (proposed 14.11.2026).\n\nOptional repo file agent-lib.labels.json ({version:1, labels:{label:[item names]}}); unlabeled items go to everyone. Client config gains 'labels'; absent = no filtering, [] = only unlabeled. Admin default config's labels win over user/env config. Invalid labels file aborts sync before any disk change. Filter before planning (internal/client/sync.go loop over inv.Deployable()); deselected items reuse the upstream-deleted path with reason 'not selected for this client's labels'. status --json reports labels/source/filtered; validate checks the file (names resolve incl. MCP). Revises README non-goal 'client-side selection or profiles'.\n\nConsumer: az-agent-defaults (agent-lib.labels.json already prepared) + az-fleet agent_lib role.","acceptance_criteria":"Tests per proposal section 'Tests' green; README documents file format, config field, admin precedence; release tagged; second sync with labels is a byte-level no-op.","status":"open","priority":2,"issue_type":"feature","owner":"m3ta-chiron@agentmail.to","created_at":"2026-11-14T09:11:57Z","created_by":"m3ta-chiron","updated_at":"2026-11-14T09:11:57Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"agent-lib-u5t","title":"vendor rename: Vendor-Skills nachträglich umbenennen","description":"Kuratoren sollen vendored Items nachträglich (nicht nur bei vendor add) benutzerfreundlich umbenennen können. Neuer Befehl vendor rename \u003csource\u003e up=new / --reset; umbenannte Skills bekommen den name: im SKILL.md-Frontmatter angepasst (OpenCode verlangt name == Ordnername).","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"m3ta-chiron@agentmail.to","created_at":"2026-11-05T07:43:31Z","created_by":"m3ta-chiron","updated_at":"2026-11-05T07:45:14Z","started_at":"2026-11-05T07:43:50Z","closed_at":"2026-11-05T07:45:14Z","close_reason":"vendor rename implemented with SKILL.md name rewrite, tests + README","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"agent-lib-4wx.11","title":"Deliver end-to-end documentation and release gate","description":"Finish the MVP by documenting the full workflow and proving it through an offline end-to-end acceptance path. The slice should provide README content, quickstart, CLI reference, Home Manager examples, security/trust notes, troubleshooting, and a release gate that demonstrates init, Source add, inspect, snippet, Home Manager eval/render, target Manifests, and a green offline check.","acceptance_criteria":"- Documentation covers installation, quickstart, CLI reference, Home Manager configuration, Lockfile behavior, discovery conventions, security/trust model, troubleshooting, MVP scope, and non-goals\n- An offline end-to-end fixture workflow demonstrates initialization, Source discovery, selection, Pi and Opencode Rendered output, target Manifests, and no unmanaged overwrites\n- nix flake check is green without external network access and verifies the MVP acceptance criteria","notes":"E2E fixture check green. All steps verified: init creates lockfile, discover finds all items, lockfile has rev/narHash/HM-compatible schema, inspect/snippet/validate commands work, managed-file protection present. nix flake check passes.","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:50:02Z","created_by":"m3tam3re","updated_at":"2026-05-28T08:13:15Z","started_at":"2026-05-28T07:46:50Z","closed_at":"2026-05-28T08:13:15Z","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:50:01Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.1","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.10","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.2","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.3","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.4","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.5","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.6","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.9","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":10,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"agent-lib-4wx.10","title":"Complete CLI operational workflows and snippets","description":"Complete the day-to-day CLI workflow around existing Sources, Profiles, and Targets. The slice should make update/review/switch workflows practical with added/removed Item reports, offline and fetch validation modes, minimal and full Nix snippets, JSON output, non-interactive defaults, and an optional interactive entry point without automatic Nix edits.","acceptance_criteria":"- source update and source update --all report added and removed Items without changing Home Manager selection\n- validate runs offline by default, validate --fetch performs explicit reachability checks, and list/inspect/validate support stable JSON output\n- snippet emits both minimal Profile include snippets and full example configuration, while the CLI remains non-interactive by default and never edits Nix files","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:57Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:46:28Z","started_at":"2026-05-28T07:39:36Z","closed_at":"2026-05-28T07:46:28Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:56Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.3","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.5","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":4,"dependent_count":1,"comment_count":0}
{"_type":"issue","id":"agent-lib-4wx.9","title":"Apply item-specific patches and deployment safety controls","description":"Add safety and customization controls around selected Items, including item-specific patches, target-specific overrides, targetName collision handling, editable-copy escape hatch, license propagation, and configurable incompatibility policy. The slice should prove that patches affect only copied Artifacts and never mutate original source content.","acceptance_criteria":"- Item-specific patches apply only to copied Artifacts, while original Canonical source content remains immutable and auditable\n- targetName overrides, target-specific enable/disable overrides, collision detection, and onIncompatible policies are enforced for both Pi and Opencode\n- License files, provenance headers for rendered Markdown, preserved file permissions, and editable-copy deployment mode are covered by tests","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:51Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:39:25Z","started_at":"2026-05-28T07:25:13Z","closed_at":"2026-05-28T07:39:25Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.9","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:51Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.9","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:49:52Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.9","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:49:52Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":2,"dependent_count":1,"comment_count":0}
+15
View File
@@ -0,0 +1,15 @@
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"command": "bd prime --hook-json",
"type": "command"
}
],
"matcher": ""
}
]
}
}
+2
View File
@@ -0,0 +1,2 @@
[features]
hooks = true
+51
View File
@@ -0,0 +1,51 @@
{
"hooks": {
"PostCompact": [
{
"hooks": [
{
"command": "bd codex-hook PostCompact",
"statusMessage": "Scheduling Beads context refresh",
"type": "command"
}
],
"matcher": "manual|auto"
}
],
"PreCompact": [
{
"hooks": [
{
"command": "bd codex-hook PreCompact",
"statusMessage": "Checking Beads context",
"type": "command"
}
],
"matcher": "manual|auto"
}
],
"SessionStart": [
{
"hooks": [
{
"command": "bd codex-hook SessionStart",
"statusMessage": "Loading Beads context",
"type": "command"
}
],
"matcher": "startup|resume|clear"
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"command": "bd codex-hook UserPromptSubmit",
"statusMessage": "Refreshing Beads context",
"type": "command"
}
]
}
]
}
}
+20
View File
@@ -0,0 +1,20 @@
{
"hooks": {
"postToolUse": [
{
"command": "bd cursor-hook postToolUse"
}
],
"preCompact": [
{
"command": "bd cursor-hook preCompact"
}
],
"sessionStart": [
{
"command": "bd cursor-hook sessionStart"
}
]
},
"version": 1
}
+67
View File
@@ -0,0 +1,67 @@
---
alwaysApply: true
---
<!-- BEGIN BEADS INTEGRATION -->
<!-- Auto-generated by 'bd setup cursor'. Content between these markers is managed by bd. -->
# Beads Issue Tracking
This project uses [Beads (bd)](https://github.com/gastownhall/beads) for issue tracking.
## Core Rules
- Track ALL work in bd (never use markdown TODOs or comment-based task lists)
- Use `bd ready` to find available work
- Use `bd create` to track new issues/tasks/bugs
- Treat commit, push, and Dolt remote sync as policy-controlled handoff actions
- Run `bd prime` for complete workflow context (SSOT for operational commands)
- Default to conservative git authority: report status and proposed commands unless the user, orchestrator, or repository profile explicitly authorizes commit/sync/push
## Quick Reference
```bash
bd prime # Load complete workflow context (SSOT)
bd ready # Show issues ready to work (no blockers)
bd list --status=open # List all open issues
bd create "title" -t task -p 2 # Create new issue
bd update <id> --claim # Claim work atomically
bd unclaim <id> # Release stuck issue (agent crashed)
bd close <id> # Mark complete
bd dep add <issue> <depends-on> # Add dependency
bd dolt push # Sync with remote when authorized
```
## Workflow
1. Check for ready work: `bd ready`
2. Claim an issue atomically: `bd update <id> --claim`
3. Do the work
4. Mark complete: `bd close <id>`
5. Handoff: report changed files, validation, issue status, and any proposed commit/sync/push commands
## Issue Types
- `bug` - Something broken
- `feature` - New functionality
- `task` - Work item (tests, docs, refactoring)
- `epic` - Large feature with subtasks
- `chore` - Maintenance (dependencies, tooling)
## Priorities
- `0` - Critical (security, data loss, broken builds)
- `1` - High (major features, important bugs)
- `2` - Medium (default, nice-to-have)
- `3` - Low (polish, optimization)
- `4` - Backlog (future ideas)
## Context Loading
Run `bd prime` to get complete workflow documentation in AI-optimized format.
`bd prime` is the single source of truth for operational commands and session workflow.
For detailed docs: see AGENTS.md, the beads quickstart
(https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md), or run `bd --help`
<!-- END BEADS INTEGRATION -->
+4
View File
@@ -25,3 +25,7 @@ coverage.*
# Local env overrides (never commit)
.env
.env.local
# Beads / Dolt files (added by bd init)
.beads/proxieddb/
*.gate.lock*
+128
View File
@@ -0,0 +1,128 @@
# Agent Instructions
This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
> **Architecture in one line:** Issues live in a local Dolt database
> (`.beads/dolt/`); cross-machine sync uses `bd dolt push/pull` (a
> git-compatible protocol), stored under `refs/dolt/data` on your git
> remote — separate from `refs/heads/*` where your code lives.
> `.beads/issues.jsonl` is a passive export, not the wire protocol.
>
> See [sync-concepts](https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md)
> for the one-screen overview and anti-patterns (don't treat JSONL as the
> source of truth; don't `bd import` during normal operation; don't
> reach for third-party Dolt hosting before trying the default).
## Quick Reference
```bash
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work atomically
bd close <id> # Complete work
bd dolt push # Push beads data to remote
```
## Non-Interactive Shell Commands
**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
**Use these forms instead:**
```bash
# Force overwrite without prompting
cp -f source dest # NOT: cp source dest
mv -f source dest # NOT: mv source dest
rm -f file # NOT: rm file
# For recursive operations
rm -rf directory # NOT: rm -r directory
cp -rf source dest # NOT: cp -r source dest
```
**Other commands that may prompt:**
- `scp` - use `-o BatchMode=yes` for non-interactive
- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
- `apt-get` - use `-y` flag
- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:46cd31e7 -->
## Beads Issue Tracker
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
### Quick Reference
```bash
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete work
```
### Rules
- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Run `bd prime` for detailed command reference and session close protocol
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
## Agent Context Profiles
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
## Session Completion
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
1. **File issues for remaining work** - Create beads for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **Handle git/sync by active profile**:
```bash
# Conservative/minimal/default: report status and proposed commands; wait for approval.
git status
# Team-maintainer opt-in only, unless current instructions forbid it:
git pull --rebase
bd dolt push
git push
git status
```
5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step
**Critical rules:**
- Explicit user or orchestrator instructions override this Beads block.
- Do not commit or push without clear authority from the active profile or the current user request.
- If a required sync or push is blocked, stop and report the exact command and error.
<!-- END BEADS INTEGRATION -->
<!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->
## Beads Issue Tracker
Use Beads (`bd`) for durable task tracking in repositories that include it. Use the `beads` skill at `.agents/skills/beads/SKILL.md` (project install) or `~/.agents/skills/beads/SKILL.md` (global install) for Beads workflow guidance, then use the `bd` CLI for issue operations.
### Quick Reference
```bash
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete work
bd prime # Refresh Beads context
```
### Rules
- Use `bd` for all task tracking; do not create markdown TODO lists.
- Run `bd prime` when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use `/hooks` to inspect or toggle them.
- Keep persistent project memory in Beads via `bd remember`; do not create ad hoc memory files.
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
<!-- END BEADS CODEX SETUP -->
+77
View File
@@ -0,0 +1,77 @@
# Project Instructions for AI Agents
This file provides instructions and context for AI coding agents working on this project.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:1105d646 -->
## Beads Issue Tracker
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
### Quick Reference
```bash
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete work
```
### Rules
- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Run `bd prime` for detailed command reference and session close protocol
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
## Agent Context Profiles
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
## Session Completion
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
1. **File issues for remaining work** - Create beads for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **Handle git/sync by active profile**:
```bash
# Conservative/minimal/default: report status and proposed commands; wait for approval.
git status
# Team-maintainer opt-in only, unless current instructions forbid it:
git pull --rebase
git push
git status
```
5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step
**Critical rules:**
- Explicit user or orchestrator instructions override this Beads block.
- Do not commit or push without clear authority from the active profile or the current user request.
- If a required sync or push is blocked, stop and report the exact command and error.
<!-- END BEADS INTEGRATION -->
## Build & Test
_Add your build and test commands here_
```bash
# Example:
# npm install
# npm test
```
## Architecture Overview
_Add a brief overview of your project architecture_
## Conventions & Patterns
_Add your project-specific conventions here_
+26
View File
@@ -153,6 +153,32 @@ agent-lib vendor add superpowers "$URL" --rename review=superpowers-review
The on-disk folder always carries exactly the deployed name. Renaming onto
another collision is an error.
### Friendlier names for your users
Renames are not only for collisions — use them to give vendored items names
your colleagues recognize. `vendor rename` changes them at any time, without
moving the pinned revision or the selection:
```sh
agent-lib vendor rename superpowers brainstorming=ideen-sammeln tdd=test-first
agent-lib vendor rename superpowers --reset tdd # back to the upstream id
agent-lib vendor rename superpowers # list current renames
```
- The rename map lives in the lockfile and survives `vendor update` and
`vendor select`.
- A renamed skill gets the `name:` in its `SKILL.md` frontmatter rewritten to
the new folder name (OpenCode requires both to match and shows that name).
Commands and agents are renamed via their file name only.
- Skill names must be 1–64 lowercase letters, digits and single hyphens
(`code-review`, not `Code Review`). No name of any type may contain path
separators or start with a dot.
- Renaming an id that is not selected yet is allowed; it applies once the
item is added via `vendor select --add`.
- On the next `agent-lib sync`, clients receive the item under the new name;
the old name is removed from their machine like any upstream deletion
(locally modified copies stay, as usual).
### The maintenance loop
```sh
+159
View File
@@ -0,0 +1,159 @@
# Proposal: client labels — deliver content to a subset of clients
Status: proposed (14.11.2026)
## Problem
A work repository serves every client the same content. Organisations with
teams want *relevant* content per team: finance needs finance skills, sales
needs sales agents, and nobody benefits from all of it. A long skill list
also hurts routing quality of small models.
Today the only way to split is one repository or one branch per team. Both
force shared content to be maintained N times (merges, drift) and cannot
serve a client that belongs to two teams — a client pulls exactly one ref.
## Decision in one sentence
Content items may carry **labels** in the work repository; clients carry
**labels** in their config; `sync` delivers an item when it is unlabeled or
shares at least one label with the client.
agent-lib stays generic: it knows "label" and "item", never "department",
"role" or any organisation's vocabulary. What a label means and who gets it
is decided outside agent-lib (curator: which item has which label; fleet
tooling: which client has which label).
This revises the v2 non-goal "client-side selection or profiles": labels are
a selection, but no profiles — there is no per-label content, overrides or
inheritance, only a filter over the one shared inventory.
## Repository side: `agent-lib.labels.json`
Optional file in the work repository root, next to `agent-lib.lock.json`.
JSON keeps the binary free of a YAML dependency (frontmatter is hand-parsed
today) and matches the lockfile and client config.
```json
{
"version": 1,
"labels": {
"sales": ["crm-agent", "quote-writer"],
"finance": ["officecli-financial-model", "invoice-check"],
"dev": ["grilling", "to-spec"]
}
}
```
Rules:
- **Unlabeled = everyone.** Only items that should be restricted appear in
the file. Adding an item to the repository without touching the file
delivers it to all clients — same as today.
- An item may appear under several labels (OR).
- Entries are **deployed item names** (after vendor renames), matched across
types: `foo` covers the skill `foo` and the command `foo` alike. Type-
qualified entries are not needed until a real collision appears.
- Label form `^[a-z0-9][a-z0-9-]*$`; lists must be non-empty.
- Names may also refer to MCP fragments. The binary never deploys MCP, but
fleet tooling can read the same file to scope MCP servers — one source of
truth for "who gets what".
- Unknown top-level keys are an error (typo protection); `version` is
required.
## Client side: `labels` in the client config
```json
{
"repo_url": "https://git.example.com/company/agent-content.git",
"ref": "main",
"labels": ["sales", "leadership"]
}
```
| `labels` | Effect |
|---|---|
| field absent | **no filtering** — every item, as today (backward compatible) |
| `[]` | only unlabeled items |
| `["a","b"]` | unlabeled items plus items labeled `a` or `b` |
Client labels that no item uses are fine (no warning): a client may be
labeled ahead of content.
### Admin-pinned labels
Today the first config found wins as a whole, and the user-level config
precedes the admin default. For labels that would let a user widen their
own selection. Rule:
> If the admin default config exists and contains `labels`, that value
> applies — whichever config supplied `repo_url`. User-level and env
> configs cannot set or override `labels` while an admin value exists.
> Without an admin value, `labels` from the chosen config applies
> (personal machines keep full control).
`--labels a,b` as a flag is deliberately not offered for sync; for testing
use `--config` with a file that has no admin counterpart, i.e. on a machine
without an admin default.
Labels are a **relevance filter, not access control**: the whole repository
revision is still fetched into the local cache. Confidential content needs
a separately authenticated repository.
## Sync behaviour
1. Build the inventory as today.
2. Read `agent-lib.labels.json` from the **same revision**.
- Absent → no filtering.
- Invalid (parse error, bad label form, empty list, unknown key,
unknown version) → **sync aborts before any change** with a clear
error. Never fall back to "deliver everything".
- A name that matches no item → warning in sync log/status, not fatal
(the curator-side `validate` is the hard gate).
3. Drop items whose labels do not intersect the client labels before
hashing/planning (`internal/client/sync.go`, loop over
`inv.Deployable()`).
4. Planning is unchanged. A previously deployed item that is no longer
selected is handled exactly like an upstream deletion: unmodified →
remove; locally modified → skip + warn (`--force` removes). The plan
reason and toast text say **"not selected for this client's labels"**
instead of "upstream deleted" so users understand why.
## Status
`status --json` gains:
```json
"labels": { "client": ["sales"], "source": "admin", "filtered": 12 }
```
`source` is `admin` | `user` | `env` | `flag` | `none`. Human output
prints one line: `labels: sales (admin) — 12 items not selected`.
## Curator side
`agent-lib validate` checks `agent-lib.labels.json` when present:
schema/version, label form, non-empty lists, every name resolves to an
inventory item (own or external, any type including MCP). Errors are
fatal, so a broken file never reaches clients through CI.
No new curator command is required; the file is edited by hand. A later
`agent-lib labels list` (item → labels table) is a nice-to-have.
## Tests
- planner/sync: absent field, `[]`, single/multi label, item under two
labels, label removed from client → remove unmodified / keep modified,
`--force`.
- config: admin labels beat user labels; user labels apply without admin
value; absent everywhere → no filtering.
- labels file: absent, invalid variants (abort, no disk change), unknown
name (warning).
- validate: each error class.
- e2e: second run is a byte-level no-op with labels active.
## Rollout
Additive and backward compatible: old clients ignore the file, new
clients without `labels` ignore the file. Fleet tooling adds the field
after pinning the release that understands it.
+35
View File
@@ -16,6 +16,7 @@ func newVendorCmd() *cobra.Command {
}
cmd.AddCommand(newVendorAddCmd())
cmd.AddCommand(newVendorSelectCmd())
cmd.AddCommand(newVendorRenameCmd())
cmd.AddCommand(newVendorListCmd())
cmd.AddCommand(newVendorInspectCmd())
cmd.AddCommand(newVendorUpdateCmd())
@@ -70,6 +71,40 @@ func newVendorAddCmd() *cobra.Command {
return cmd
}
func newVendorRenameCmd() *cobra.Command {
var reset []string
cmd := &cobra.Command{
Use: "rename <name> [upstream-id=deployed-name ...]",
Short: "Give vendored items user-friendly deployed names",
Long: "Sets or resets deployed-name overrides for a vendored source after\n" +
"vendor add. The rename map is pinned in the lockfile and survives\n" +
"vendor update and vendor select. Renamed skills get their SKILL.md\n" +
"frontmatter name rewritten to the new folder name, so OpenCode lists\n" +
"them under the new name. Skill names must be lowercase letters, digits\n" +
"and single hyphens (e.g. code-review). The pinned revision and the\n" +
"selection never change; collisions re-run before anything is written.\n" +
"Without arguments the current renames are listed.\n\n" +
"Examples:\n" +
" agent-lib vendor rename superpowers brainstorming=ideen-sammeln\n" +
" agent-lib vendor rename superpowers --reset brainstorming\n" +
" agent-lib vendor rename superpowers",
Args: cobra.MinimumNArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
set, err := vendor.ParseRenames(args[1:])
if err != nil {
return err
}
opts := vendor.RenameOptions{Set: set, Reset: splitList(reset)}
if err := vendor.Rename(".", args[0], opts, cmd.OutOrStdout()); err != nil {
return fmt.Errorf("vendor rename: %w", err)
}
return nil
},
}
cmd.Flags().StringSliceVar(&reset, "reset", nil, "comma-separated upstream ids whose rename is dropped (deploy under the upstream id again)")
return cmd
}
func splitList(in []string) []string {
var out []string
for _, s := range in {
+89
View File
@@ -0,0 +1,89 @@
package e2e
import (
"os"
"path/filepath"
"testing"
)
func TestVendorRenameAfterAdd(t *testing.T) {
h := newHarness(t)
standardFixture(h, t)
h.mustRun(t, "vendor", "add", "superpowers", h.upstreamDir)
out := h.mustRun(t, "vendor", "rename", "superpowers", "good-skill=gute-skill", "review=pruefen")
for _, want := range []string{"good-skill → gute-skill", "review → pruefen"} {
if !contains(out, want) {
t.Errorf("report must contain %q:\n%s", want, out)
}
}
skill := readFile(t, filepath.Join(h.workDir, "external/superpowers/skills/gute-skill/SKILL.md"))
if !contains(skill, "name: gute-skill\n") || !contains(skill, "description: works") {
t.Errorf("renamed skill must carry the new frontmatter name and keep the rest:\n%s", skill)
}
if _, err := os.Stat(filepath.Join(h.workDir, "external/superpowers/skills/gute-skill/helper.py")); err != nil {
t.Error("skill artifacts must move with the rename")
}
if _, err := os.Stat(filepath.Join(h.workDir, "external/superpowers/skills/good-skill")); err == nil {
t.Error("old skill folder must be gone")
}
if _, err := os.Stat(filepath.Join(h.workDir, "external/superpowers/commands/pruefen.md")); err != nil {
t.Error("renamed command must exist under the new name")
}
lock := readLock(t, h.workDir)
if got := lock.Sources["superpowers"].Renames["good-skill"]; got != "gute-skill" {
t.Errorf("lockfile rename = %q", got)
}
h.mustRun(t, "validate")
// Listing.
if out := h.mustRun(t, "vendor", "rename", "superpowers"); !contains(out, "good-skill → gute-skill") {
t.Errorf("listing must show renames:\n%s", out)
}
// Survives update with new upstream content.
h.write(t, "skills/good-skill/SKILL.md", "---\nname: Good Skill\ndescription: v2\n---\n# Good v2\n")
h.commitUpstream(t, "v2")
h.mustRun(t, "vendor", "update", "superpowers")
skill = readFile(t, filepath.Join(h.workDir, "external/superpowers/skills/gute-skill/SKILL.md"))
if !contains(skill, "name: gute-skill\n") || !contains(skill, "description: v2") {
t.Errorf("update must keep the rename and frontmatter rewrite:\n%s", skill)
}
// Reset.
h.mustRun(t, "vendor", "rename", "superpowers", "--reset", "good-skill")
if _, err := os.Stat(filepath.Join(h.workDir, "external/superpowers/skills/good-skill/SKILL.md")); err != nil {
t.Error("reset must restore the upstream folder name")
}
if got := readLock(t, h.workDir).Sources["superpowers"].Renames["good-skill"]; got != "" {
t.Errorf("reset must drop the rename, got %q", got)
}
h.mustRun(t, "validate")
}
func TestVendorRenameRejectsBadInput(t *testing.T) {
h := newHarness(t)
ownSkillFixture(h, t) // own skills/good-skill
standardFixture(h, t)
h.mustRun(t, "vendor", "add", "superpowers", h.upstreamDir, "--rename", "good-skill=sp-good")
before := readFile(t, filepath.Join(h.workDir, "agent-lib.lock.json"))
for _, args := range [][]string{
{"broken-skill=good-skill"}, // collides with own skill
{"good-skill=Gute Skill"}, // invalid skill name
{"does-not-exist=whatever"}, // unknown upstream id
{"--reset", "broken-skill"}, // nothing to reset
} {
out, err := h.run(t, append([]string{"vendor", "rename", "superpowers"}, args...)...)
if err == nil {
t.Errorf("rename %v must fail:\n%s", args, out)
}
}
if after := readFile(t, filepath.Join(h.workDir, "agent-lib.lock.json")); after != before {
t.Error("failed renames must not touch the lockfile")
}
if _, err := os.Stat(filepath.Join(h.workDir, "external/superpowers/skills/sp-good")); err != nil {
t.Error("failed renames must not touch the external area")
}
}
+3
View File
@@ -310,6 +310,9 @@ func materialize(workDir, name string, tree discovery.Tree, selected []discovery
case lockfile.TypeSkill:
dst = filepath.Join(base, dep)
err = deploy.Dir(tree, it.RelPath, dst)
if err == nil && dep != it.UpstreamID {
err = rewriteSkillName(dst, dep)
}
default:
dst = filepath.Join(base, dep+filepath.Ext(it.RelPath))
err = deploy.File(tree, it.RelPath, dst)
+4 -2
View File
@@ -103,8 +103,10 @@ func checkCollisions(workDir string, lf *lockfile.Lockfile, source string, selec
seen := map[string]string{}
for _, it := range selected {
deployed := deployedName(it.UpstreamID, renames)
if deployed == "" {
return fmt.Errorf("source %q: rename of %q maps to an empty name", source, it.UpstreamID)
if deployed != it.UpstreamID {
if err := validateRenameTarget(it.Type, it.UpstreamID, deployed); err != nil {
return fmt.Errorf("source %q: %w", source, err)
}
}
if prev, dup := seen[deployed]; dup {
return &CollisionError{
+180
View File
@@ -0,0 +1,180 @@
package vendor
import (
"fmt"
"io"
"os"
"path/filepath"
"sort"
"github.com/m3tam3re/agent-lib/internal/discovery"
"github.com/m3tam3re/agent-lib/internal/gitsource"
"github.com/m3tam3re/agent-lib/internal/lockfile"
)
// RenameOptions parameterize vendor rename.
type RenameOptions struct {
// Set maps upstream ids to new deployed names. Mapping an id onto itself
// is the same as resetting it.
Set map[string]string
// Reset drops existing renames so the items deploy under their upstream id.
Reset []string
}
// Rename changes the deployed names of a vendored source's items after the
// fact — without advancing the pinned revision or touching the selection.
// Ids are validated against the pinned upstream, collisions re-run, and the
// external area is rewritten atomically. With no options it only lists the
// current renames.
func Rename(workDir, name string, opts RenameOptions, stdout io.Writer) error {
lockPath := filepath.Join(workDir, lockfile.FileName)
lf, err := lockfile.Load(lockPath)
if err != nil {
return err
}
src, ok := lf.Sources[name]
if !ok {
return fmt.Errorf("source %q is not in the lockfile", name)
}
if len(opts.Set) == 0 && len(opts.Reset) == 0 {
printRenames(stdout, name, src.Renames)
return nil
}
newRenames := map[string]string{}
for k, v := range src.Renames {
newRenames[k] = v
}
for _, id := range opts.Reset {
if _, ok := newRenames[id]; !ok {
return fmt.Errorf("source %q: --reset %q has no rename to reset", name, id)
}
delete(newRenames, id)
}
for up, dep := range opts.Set {
if up == dep {
delete(newRenames, up)
continue
}
newRenames[up] = dep
}
repo, err := gitsource.Clone(src.URL, src.Ref)
if err != nil {
return err
}
pinned, err := repo.Pin(src.Rev)
if err != nil {
return fmt.Errorf("%w — run vendor update to re-pin", err)
}
tree, err := pinned.Tree()
if err != nil {
return err
}
items, err := discovery.Scan(tree, discovery.FromLockfileDiscovery(derefDiscovery(src)))
if err != nil {
return err
}
ids := append(sortedKeys(boolSet(keysOf(opts.Set))), opts.Reset...)
if err := checkIDEntries(items, ids, name, "rename"); err != nil {
return err
}
types := map[string]string{}
for _, it := range items {
if !it.Skipped {
types[it.UpstreamID] = it.Type
}
}
for up, dep := range opts.Set {
if up == dep {
continue
}
if err := validateRenameTarget(types[up], up, dep); err != nil {
return fmt.Errorf("source %q: %w", name, err)
}
}
selected := applySelection(items, src.Selection)
if err := checkCollisions(workDir, lf, name, selected, newRenames); err != nil {
return err
}
cleanupStaleStaging(workDir)
staging := filepath.Join(workDir, externalDir, ".staging-"+name)
if err := os.RemoveAll(staging); err != nil {
return err
}
if err := materializeTree(tree, selected, newRenames, staging); err != nil {
os.RemoveAll(staging)
return err
}
oldDir := filepath.Join(workDir, externalDir, name)
if err := os.RemoveAll(oldDir); err != nil {
return fmt.Errorf("replacing %s: %w", oldDir, err)
}
if err := os.Rename(staging, oldDir); err != nil {
return fmt.Errorf("swapping in new external area: %w", err)
}
oldRenames := src.Renames
if len(newRenames) == 0 {
newRenames = nil
}
src.Renames = newRenames
src.Inventory = inventoryOf(selected)
src.Warnings = dedupe(warningsOf(items))
if err := lf.Save(lockPath); err != nil {
return err
}
inSelection := idSet(selected)
fmt.Fprintf(stdout, "source %s: renames updated at pinned rev %s\n", name, short(src.Rev))
for _, id := range ids {
before := deployedName(id, oldRenames)
after := deployedName(id, newRenames)
note := ""
if !inSelection[types[id]][id] {
note = " (not selected — applies once added)"
}
if before == after {
fmt.Fprintf(stdout, " %s %s: unchanged (%s)%s\n", types[id], id, after, note)
continue
}
fmt.Fprintf(stdout, " %s %s: %s → %s%s\n", types[id], id, before, after, note)
}
return nil
}
func printRenames(w io.Writer, name string, renames map[string]string) {
if len(renames) == 0 {
fmt.Fprintf(w, "source %s: no renames\n", name)
return
}
fmt.Fprintf(w, "source %s renames (upstream → deployed):\n", name)
ups := make([]string, 0, len(renames))
for up := range renames {
ups = append(ups, up)
}
sort.Strings(ups)
for _, up := range ups {
fmt.Fprintf(w, " %s → %s\n", up, renames[up])
}
}
func keysOf(m map[string]string) []string {
out := make([]string, 0, len(m))
for k := range m {
out = append(out, k)
}
return out
}
func boolSet(ids []string) map[string]bool {
out := map[string]bool{}
for _, id := range ids {
out[id] = true
}
return out
}
+91
View File
@@ -0,0 +1,91 @@
package vendor
import (
"fmt"
"os"
"path/filepath"
"regexp"
"strings"
"github.com/m3tam3re/agent-lib/internal/lockfile"
)
// skillNameRe is the OpenCode / Agent Skills naming rule: lowercase
// alphanumerics with single hyphen separators. OpenCode additionally requires
// the SKILL.md frontmatter name to equal the folder name.
var skillNameRe = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)
const maxSkillNameLen = 64
// validateRenameTarget checks a deployed-name override before it becomes a
// path segment. Every type rejects path separators and dot-names; skills must
// additionally follow the OpenCode skill naming rule so the renamed skill
// still loads.
func validateRenameTarget(typ, upstreamID, deployed string) error {
if deployed == "" {
return fmt.Errorf("rename of %q maps to an empty name", upstreamID)
}
if strings.ContainsAny(deployed, `/\`) || strings.HasPrefix(deployed, ".") || strings.TrimSpace(deployed) != deployed {
return fmt.Errorf("rename of %q to %q: name must be a single path segment without leading dot or surrounding whitespace", upstreamID, deployed)
}
if typ == lockfile.TypeSkill {
if len(deployed) > maxSkillNameLen || !skillNameRe.MatchString(deployed) {
return fmt.Errorf("rename of skill %q to %q: skill names must be 1-%d lowercase letters, digits and single hyphens (e.g. \"code-review\")", upstreamID, deployed, maxSkillNameLen)
}
}
return nil
}
// rewriteSkillName sets the frontmatter `name:` of dir/SKILL.md to name so a
// renamed skill matches its folder (OpenCode loads skills by that pairing and
// shows the frontmatter name to the user). A missing name key is inserted, a
// missing frontmatter block is created. Everything else stays byte-identical.
func rewriteSkillName(dir, name string) error {
path := filepath.Join(dir, "SKILL.md")
info, err := os.Stat(path)
if err != nil {
return err
}
data, err := os.ReadFile(path)
if err != nil {
return err
}
out := setFrontmatterName(string(data), name)
if out == string(data) {
return nil
}
tmp := path + ".agent-lib-tmp"
if err := os.WriteFile(tmp, []byte(out), info.Mode().Perm()); err != nil {
return err
}
return os.Rename(tmp, path)
}
func setFrontmatterName(content, name string) string {
lines := strings.SplitAfter(content, "\n")
if len(lines) == 0 || strings.TrimRight(lines[0], "\r\n") != "---" {
return "---\nname: " + name + "\n---\n" + content
}
eol := "\n"
if strings.HasSuffix(lines[0], "\r\n") {
eol = "\r\n"
}
for i := 1; i < len(lines); i++ {
bare := strings.TrimRight(lines[i], "\r\n")
if bare == "---" {
break
}
if bare == "" || bare[0] == ' ' || bare[0] == '\t' {
continue // nested/continuation lines never carry the top-level name
}
key, _, ok := strings.Cut(bare, ":")
if ok && strings.EqualFold(strings.TrimSpace(key), "name") {
lineEOL := lines[i][len(bare):]
lines[i] = "name: " + name + lineEOL
return strings.Join(lines, "")
}
}
// No name key: insert one right after the opening fence.
rest := strings.Join(lines[1:], "")
return lines[0] + "name: " + name + eol + rest
}
+39
View File
@@ -0,0 +1,39 @@
package vendor
import "testing"
func TestSetFrontmatterName(t *testing.T) {
cases := []struct{ name, in, want string }{
{"replace", "---\nname: Good Skill\ndescription: d\n---\nbody\n", "---\nname: ideen\ndescription: d\n---\nbody\n"},
{"crlf", "---\r\nname: x\r\n---\r\nb", "---\r\nname: ideen\r\n---\r\nb"},
{"insert", "---\ndescription: d\n---\n", "---\nname: ideen\ndescription: d\n---\n"},
{"no frontmatter", "# Title\n", "---\nname: ideen\n---\n# Title\n"},
{"nested name untouched", "---\nmeta:\n name: inner\n---\n", "---\nname: ideen\nmeta:\n name: inner\n---\n"},
{"name in body untouched", "---\ndescription: d\n---\nname: body\n", "---\nname: ideen\ndescription: d\n---\nname: body\n"},
}
for _, c := range cases {
if got := setFrontmatterName(c.in, "ideen"); got != c.want {
t.Errorf("%s:\n got %q\nwant %q", c.name, got, c.want)
}
}
}
func TestValidateRenameTarget(t *testing.T) {
ok := []struct{ typ, dep string }{
{"skills", "code-review"}, {"skills", "a1"}, {"commands", "Review_Things"},
}
for _, c := range ok {
if err := validateRenameTarget(c.typ, "up", c.dep); err != nil {
t.Errorf("%s %q should be valid: %v", c.typ, c.dep, err)
}
}
bad := []struct{ typ, dep string }{
{"skills", "Code Review"}, {"skills", "code--review"}, {"skills", "-x"}, {"skills", "Gross"},
{"commands", "../x"}, {"agents", "a/b"}, {"commands", ".hidden"}, {"skills", ""},
}
for _, c := range bad {
if err := validateRenameTarget(c.typ, "up", c.dep); err == nil {
t.Errorf("%s %q should be rejected", c.typ, c.dep)
}
}
}
+3
View File
@@ -264,6 +264,9 @@ func materializeTree(tree discovery.Tree, selected []discovery.Item, renames map
case lockfile.TypeSkill:
target = filepath.Join(base, dep)
err = deploy.Dir(tree, it.RelPath, target)
if err == nil && dep != it.UpstreamID {
err = rewriteSkillName(target, dep)
}
default:
target = filepath.Join(base, dep+filepath.Ext(it.RelPath))
err = deploy.File(tree, it.RelPath, target)