Cross-Library KB Onboarding

Walk a new consultant or a fresh project through KB cross-library setup. Replaces the hand-walked sequence of "discover ~/.sdlc/global-libraries.json, get paths from someone, run kb-register-library or hand-edit, test it manually" with a single skill.

Modes

• Default — full interactive setup (discover → add → validate → activate → smoke-test → report)
• --dry-run — go through discovery + validation but don't write to .sdlc/libraries.json or modify any files
• --verify-only — skip prompting; just validate existing registry + activation and report status (covers Task 23 functionality)

Steps

Preflight: verify scripts package importable

python3 -c "
import sys, os, importlib.util
PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT', '')
SCRIPTS = os.path.join(PLUGIN_ROOT, 'scripts')
INIT = os.path.join(SCRIPTS, '__init__.py')
if os.path.isfile(INIT) and 'sdlc_knowledge_base_scripts' not in sys.modules:
    spec = importlib.util.spec_from_file_location(
        'sdlc_knowledge_base_scripts',
        INIT,
        submodule_search_locations=[SCRIPTS],
    )
    if spec and spec.loader:
        module = importlib.util.module_from_spec(spec)
        sys.modules['sdlc_knowledge_base_scripts'] = module
        spec.loader.exec_module(module)
try:
    import sdlc_knowledge_base_scripts.registry
    print('OK')
except ImportError:
    print('MISSING')
"

If MISSING, see kb-query for fallback options.

1. Discover existing user-scope registrations

python3 -c "
import sys, os, importlib.util
PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT', '')
SCRIPTS = os.path.join(PLUGIN_ROOT, 'scripts')
INIT = os.path.join(SCRIPTS, '__init__.py')
if os.path.isfile(INIT) and 'sdlc_knowledge_base_scripts' not in sys.modules:
    spec = importlib.util.spec_from_file_location(
        'sdlc_knowledge_base_scripts',
        INIT,
        submodule_search_locations=[SCRIPTS],
    )
    if spec and spec.loader:
        module = importlib.util.module_from_spec(spec)
        sys.modules['sdlc_knowledge_base_scripts'] = module
        spec.loader.exec_module(module)

from pathlib import Path
from sdlc_knowledge_base_scripts.registry import load_global_registry, validate_library_path
from sdlc_knowledge_base_scripts.shelf_index_header import parse_shelf_index_header

gr = load_global_registry(Path(os.path.expanduser('~/.sdlc/global-libraries.json')))
print(f'Registered libraries: {len(gr.libraries)}')
for lib in gr.libraries:
    print(f'  {lib.name}  ({lib.type})  -> {lib.path}')
    if lib.type == 'filesystem' and lib.path:
        ok, reason = validate_library_path(Path(lib.path))
        if ok:
            header = parse_shelf_index_header(Path(lib.path) / '_shelf-index.md')
            print(f'    last_rebuilt: {header.last_rebuilt}, handle: {header.library_handle}')
        else:
            print(f'    INVALID: {reason}')
for w in gr.warnings:
    print(f'  Warning: {w}')
"

This shows what's already known + the validation status of each registration.

2. Prompt for additions (skip in --verify-only mode)

In default mode: ask the user if they want to register additional libraries beyond what's already there. For each one:

• Get handle, absolute path, optional description
• Validate via validate_library_path (the kb-register-library skill's logic)
• If valid, append to ~/.sdlc/global-libraries.json (preserving the JSON structure)

If the user has no additions, proceed to step 3.

In --verify-only mode: skip this step. Just report on what's already registered.

3. Validate all registrations

For every library in the (possibly updated) registry:

• Path validation: validate_library_path returns OK
• Header parse: shelf-index has at least format_version
• Handle consistency: if shelf-index has library_handle, it must match the registry name

Report per-library status. Don't block on a single failure — list them all so the user has a punch-list.

4. Per-project activation (skip in --verify-only mode)

In default mode:

# Read current activation
test -f .sdlc/libraries.json && cat .sdlc/libraries.json || echo '{"version": 1, "activated_sources": []}'

Show the user the list of registered library handles. Ask which apply to this engagement (multi-select). Write the activated handles to .sdlc/libraries.json:

mkdir -p .sdlc
cat > .sdlc/libraries.json <<'EOF'
{
  "version": 1,
  "activated_sources": ["<selected handles>"]
}
EOF

In --verify-only mode: just read and report what's currently activated.

5. Smoke test

For each activated library, dispatch a trivial query via the research-librarian Agent tool:

SCOPE: <library path>
SOURCE_HANDLE: <library handle>

Question: test connection — what is the most recent finding in your library?

Read the shelf-index, identify any one library file, deep-read it, and return its title and one fact. This is a smoke test confirming the library is queryable.

Capture which sources respond successfully. A source that returns valid findings → smoke test passed for that source. A source that errors or returns "no evidence" → smoke test note (the latter may be expected for a fresh empty library).

6. Final report

Output one of:

Ready (all sources smoke-test passed):

✓ KB environment ready
  Registered libraries: 3 (corp-semi, corp-health, internal-research)
  Activated for this project: 2 (corp-semi, internal-research)
  Smoke test: 2 of 2 passed

Issues to fix:

✗ KB environment NOT ready — fix these issues:
  • corp-semi: path /Users/.../semi-library has no _shelf-index.md
    Suggestion: cd /Users/.../semi-library && /sdlc-knowledge-base:kb-rebuild-indexes
  • corp-health: handle in registry conflicts with shelf-index handle
    Suggestion: rebuild shelf-index with --handle corp-health, or rename registry entry
  • Smoke test failed for internal-research: dispatcher timeout

Re-run /sdlc-knowledge-base:kb-setup-consulting --verify-only after fixing.

What this skill does NOT do

• It does not create corporate libraries — those exist independently and must be cloned/mounted by the user before registration
• It does not modify corporate libraries — only registers pointers
• It does not run kb-rebuild-indexes against external libraries (their owners control that)
• It does not write audit log entries — onboarding is a setup operation, not a query operation

Examples

First-time setup for a new consultant:

/sdlc-knowledge-base:kb-setup-consulting

Verify environment after fixing reported issues:

/sdlc-knowledge-base:kb-setup-consulting --verify-only

Preview without writing:

/sdlc-knowledge-base:kb-setup-consulting --dry-run

Errors

• ~/.sdlc/global-libraries.json is malformed — error and recommend manual repair
• No CLAUDE_PLUGIN_ROOT set — print install fallback (export var or pip install -e the plugin)