mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-19 02:17:09 +00:00
Add comprehensive agents_commands_runbook.md covering all agent CLI commands: list, sync, status, diff, collect, uninstall, trash, update, backup, and doctor (30 steps). Fix 18 previously failing runbooks: - Add workdir: $HOME to mdproof.json to prevent workspace pollution from project mode auto-detection - Fix jq assertions using positional index to use select(.name == ...) - Fix extras_flatten legacy agents/ dir conflict (rm in cleanup) - Fix auto_create_target_dir sed insertion and Will/Would wording - Fix uninstall_sync_orphan config indentation for migrated format - Fix universal_target_path grep pattern (name vs global_name) - Fix uninstall_all_glob registry.yaml filter in verify step - Fix target_naming grep for actual CLI warning output - Fix registry_yaml_split anchored grep for top-level skills: - Fix skillignore_source_discovery stdout suppression and jq filter - Fix ui_base_path: use pre-built binary, PID files, high ports, redirect server log to stderr to keep JSON pure - Fix extras init redirect to suppress ANSI warnings in JSON steps
6.8 KiB
6.8 KiB
CLI E2E Runbook: Extras Flatten Option
Validates flatten: true for extras targets — syncing subdirectory files
directly into the target root instead of preserving directory structure.
Origin: Issue #97 — flatten option for extras sync.
Scope
flatten: truesyncs files flat (ignoring subdirectory structure)--flattenflag onextras init--flatten/--no-flattenonextras mode- Filename collision: first file wins, subsequent skipped with warning
- Flatten + symlink mode: rejected
- Flatten prune
- JSON output includes flatten field and warnings
Environment
Run inside devcontainer.
Steps
1. Flatten sync — files from subdirectories land in target root
ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents/curriculum
mkdir -p ~/.config/skillshare/extras/agents/software
echo "# Tactician" > ~/.config/skillshare/extras/agents/curriculum/tactician.md
echo "# Planner" > ~/.config/skillshare/extras/agents/curriculum/planner.md
echo "# Implementer" > ~/.config/skillshare/extras/agents/software/implementer.md
echo "# Reviewer" > ~/.config/skillshare/extras/agents/reviewer.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss sync extras --json -g
Expected:
- exit_code: 0
- jq: [.extras[] | select(.name == "agents")][0].targets[0].synced == 4
2. Verify flat file layout — no subdirectories in target
ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents/sub1 ~/.config/skillshare/extras/agents/sub2
echo "a" > ~/.config/skillshare/extras/agents/sub1/a.md
echo "b" > ~/.config/skillshare/extras/agents/sub2/b.md
echo "c" > ~/.config/skillshare/extras/agents/root.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss sync extras -g >/dev/null
echo "files=$(find ~/.claude/agents/ -maxdepth 1 -name '*.md' | wc -l)"
echo "dirs=$(find ~/.claude/agents/ -mindepth 1 -type d | wc -l)"
Expected:
- exit_code: 0
- files=3
- dirs=0
3. Extras list JSON includes flatten field
ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents
echo "x" > ~/.config/skillshare/extras/agents/x.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss extras list --json -g
Expected:
- exit_code: 0
- jq: .[0].targets[0].flatten == true
4. Flatten collision — first file wins, second skipped with warning
ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents/team-a
mkdir -p ~/.config/skillshare/extras/agents/team-b
echo "# From team-a" > ~/.config/skillshare/extras/agents/team-a/agent.md
echo "# From team-b" > ~/.config/skillshare/extras/agents/team-b/agent.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss sync extras --json -g
Expected:
- exit_code: 0
- jq: [.extras[] | select(.name == "agents")][0].targets[0].synced == 1
- jq: [.extras[] | select(.name == "agents")][0].targets[0].skipped == 1
- jq: [.extras[] | select(.name == "agents")][0].targets[0].warnings | length == 1
5. Flatten collision warning in human-readable output
ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents/a ~/.config/skillshare/extras/agents/b
echo "1" > ~/.config/skillshare/extras/agents/a/same.md
echo "2" > ~/.config/skillshare/extras/agents/b/same.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss sync extras -g
Expected:
- exit_code: 0
- flatten conflict
6. Toggle flatten off via extras mode
ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents
echo "x" > ~/.config/skillshare/extras/agents/x.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss extras agents --no-flatten -g >/dev/null
ss extras list --json -g
Expected:
- exit_code: 0
- jq: .[0].targets[0].flatten == false
7. Toggle flatten on via extras mode
ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents
echo "x" > ~/.config/skillshare/extras/agents/x.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents -g >/dev/null 2>&1
ss extras agents --flatten -g >/dev/null
ss extras list --json -g
Expected:
- exit_code: 0
- jq: .[0].targets[0].flatten == true
8. Flatten + symlink mode rejected
ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents
echo "x" > ~/.config/skillshare/extras/agents/x.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss extras agents --mode symlink -g 2>&1 || true
Expected:
- flatten cannot be used with symlink mode
9. Flatten prune — orphaned flat file removed after source deletion
ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents/sub
echo "# Keep" > ~/.config/skillshare/extras/agents/sub/keep.md
echo "# Remove" > ~/.config/skillshare/extras/agents/sub/remove.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss sync extras -g >/dev/null
rm ~/.config/skillshare/extras/agents/sub/remove.md
ss sync extras --json -g
Expected:
- exit_code: 0
- jq: [.extras[] | select(.name == "agents")][0].targets[0].pruned == 1
Pass Criteria
- All steps pass
- Flatten sync produces flat symlinks (no subdirectories in target)
- Collision detection works with correct warning and skip
- Flatten toggle via
--flatten/--no-flattenworks - Flatten + symlink mode is rejected
- Prune works with flattened paths