Add skill selection when adding from skill registry

docs/ai/design/feature-skill-add-interactive-selection.md

@@ -0,0 +1,137 @@
+---
+phase: design
+title: System Design & Architecture
+description: Define the technical architecture, components, and data models
+feature: skill-add-interactive-selection
+---
+
+# System Design & Architecture - Skill Add Interactive Selection
+
+## Architecture Overview
+**What is the high-level system structure?**
+
+```mermaid
+graph TD
+  User[User: ai-devkit skill add <registry>] --> SkillCommand
+  SkillCommand --> SkillManager
+  SkillManager --> RegistryResolver[fetchMergedRegistry]
+  SkillManager --> CacheResolver[cloneRepositoryToCache]
+  CacheResolver --> RegistryRepo[registry checkout/cache]
+  RegistryRepo --> SkillEnumerator[scan skills/*/SKILL.md]
+  SkillEnumerator --> Prompt[inquirer checkbox prompt]
+  Prompt --> SkillManager
+  SkillManager --> Installer[existing addSkill install path]
+  Installer --> ConfigManager[project config update]
+```
+
+- `packages/cli/src/commands/skill.ts` will change `add` from two required args to one required registry arg plus an optional skill arg.
+- `SkillManager` will own the interactive fallback so CLI wiring stays thin and existing validation/cache logic is reused.
+- The prompt list will be built from the selected registry checkout after registry resolution; if refresh fails but cache exists, the cached checkout is still used with a warning.
+
+## Data Models
+**What data do we need to manage?**
+
+```ts
+interface RegistrySkillChoice {
+  name: string;
+  description?: string;
+}
+
+interface AddSkillOptions {
+  global?: boolean;
+  environments?: string[];
+}
+```
+
+- `RegistrySkillChoice` is an internal prompt model only.
+- The persisted config format does not change.
+- Skill names continue to be the canonical installation IDs.
+
+## API Design
+**How do components communicate?**
+
+**CLI surface:**
+
+- Existing explicit form remains:
+  - `ai-devkit skill add <registry> <skill-name>`
+- New interactive shorthand:
+  - `ai-devkit skill add <registry>`
+
+**Internal interfaces (proposed):**
+
+```ts
+async addSkill(registryId: string, skillName?: string, options?: AddSkillOptions): Promise<void>;
+async listRegistrySkills(registryId: string): Promise<RegistrySkillChoice[]>;
+async promptForSkillSelection(skills: RegistrySkillChoice[]): Promise<string[]>;
+```
+
+**Behavior contract:**
+
+- If `skillName` is provided, skip prompting.
+- If `skillName` is missing and `stdout`/`stdin` are interactive, enumerate skills and prompt for one or more selections.
+- If `skillName` is missing in a non-interactive context, fail with an error instructing the user to provide `<skill-name>`.
+- If the prompt is cancelled, exit without side effects.
+- If exactly one valid skill exists and `skillName` is omitted, still show the selector instead of auto-installing.
+
+## Component Breakdown
+**What are the major building blocks?**
+
+1. `packages/cli/src/commands/skill.ts`
+   - Update the command signature to optional `[skill-name]`.
+   - Pass control to `SkillManager.addSkill`.
+2. `packages/cli/src/lib/SkillManager.ts`
+   - Split current `addSkill` flow into:
+     - registry resolution and cache preparation
+     - optional interactive skill selection
+     - existing installation logic
+   - Add a helper that enumerates valid skills from the cloned registry.
+   - Add a helper that prompts with `inquirer`.
+   - Reuse the existing install path for each selected skill.
+3. `packages/cli/src/__tests__/commands/skill.test.ts`
+   - Add command-level coverage for omitted skill name.
+4. `packages/cli/src/__tests__/lib/SkillManager.test.ts`
+   - Add behavior coverage for enumeration, prompt selection, cancellation, and non-interactive mode.
+
+## Design Decisions
+**Why did we choose this approach?**
+
+- Enumerate from the resolved registry checkout instead of the global search index:
+  - It guarantees the list reflects the exact target registry the user requested.
+  - It works with custom registries that may not yet be indexed.
+  - It avoids coupling install behavior to index freshness.
+- Keep interactive selection explicit even for single-skill registries:
+  - It matches the stated UX requirement.
+  - It avoids hidden behavior changes between one-skill and multi-skill registries.
+- Allow multi-select installation in the prompt:
+  - It reduces repetitive command invocations when a user wants several skills from the same registry.
+  - It keeps the explicit two-argument command unchanged for scripted single-skill installs.
+- Prefer cached registry contents when refresh fails:
+  - It keeps the command usable offline or during transient network failures.
+  - It aligns with existing cache-oriented registry behavior.
+- Keep the prompt in `SkillManager`:
+  - Registry validation, caching, and installation already live there.
+  - The command layer should not duplicate repo-reading logic.
+- Fail in non-interactive mode when the skill name is omitted:
+  - This preserves scriptability and avoids hanging CI jobs.
+
+**Alternatives considered:**
+
+- Use `skill find` index results to populate the prompt.
+  - Rejected because it is broader than the selected registry and may be stale.
+- Always auto-install when a registry has exactly one skill.
+  - Rejected for now to keep behavior explicit and predictable.
+
+## Non-Functional Requirements
+**How should the system perform?**
+
+- Performance:
+  - Interactive enumeration should reuse the existing cache and only fetch/update the chosen registry once.
+- Reliability:
+  - Invalid skill folders are skipped during enumeration instead of breaking the entire list.
+  - Empty registries produce a clear error.
+  - Refresh failures degrade to cached registry contents when available.
+- Security:
+  - Continue validating `registryId` and selected `skillName` before installation.
+- Usability:
+  - Prompt entries should display skill name and short description when available.
+  - Users should be able to select multiple skills in one prompt.

docs/ai/implementation/feature-skill-add-interactive-selection.md

@@ -0,0 +1,62 @@
+---
+phase: implementation
+title: Implementation Guide
+description: Technical implementation notes, patterns, and code guidelines
+feature: skill-add-interactive-selection
+---
+
+# Implementation Guide - Skill Add Interactive Selection
+
+## Development Setup
+**How do we get started?**
+
+- Work in branch `feature-skill-add-interactive-selection`.
+- Use the existing CLI test setup under `packages/cli/src/__tests__`.
+- Reuse `inquirer` and existing `SkillManager` helpers instead of adding new dependencies.
+
+## Code Structure
+**How is the code organized?**
+
+- Command entrypoint: `packages/cli/src/commands/skill.ts`
+- Main orchestration: `packages/cli/src/lib/SkillManager.ts`
+- Tests: `packages/cli/src/__tests__/commands/skill.test.ts` and `packages/cli/src/__tests__/lib/SkillManager.test.ts`
+
+## Implementation Notes
+**Key technical details to remember:**
+
+### Core Features
+- Feature 1: Accept an omitted `<skill-name>` argument in the `skill add` command.
+- Feature 2: Enumerate installable skills from the resolved registry checkout.
+- Feature 3: Prompt for one skill and hand the result back into the existing install path.
+
+### Patterns & Best Practices
+- Keep explicit two-argument installs on the current path.
+- Isolate prompt selection from installation side effects.
+- Skip malformed entries instead of failing enumeration wholesale.
+
+## Integration Points
+**How do pieces connect?**
+
+- Registry lookup continues through merged registry resolution.
+- Cache refresh continues through the current clone/pull helpers.
+- Project config updates remain in `ConfigManager.addSkill`.
+
+## Error Handling
+**How do we handle failures?**
+
+- Missing registry: fail before prompting.
+- Empty registry: fail with a message explaining no valid skills were found.
+- Prompt cancellation: exit cleanly without installation.
+- Non-interactive invocation without skill name: fail with explicit remediation text.
+
+## Performance Considerations
+**How do we keep it fast?**
+
+- Reuse the cloned cache after registry resolution.
+- Read only direct `skills/*/SKILL.md` entries needed to build the prompt.
+
+## Security Notes
+**What security measures are in place?**
+
+- Preserve existing registry and skill name validation.
+- Do not install unvalidated paths derived from arbitrary user input.

docs/ai/planning/feature-skill-add-interactive-selection.md

@@ -0,0 +1,75 @@
+---
+phase: planning
+title: Project Planning & Task Breakdown
+description: Break down work into actionable tasks and estimate timeline
+feature: skill-add-interactive-selection
+---
+
+# Project Planning & Task Breakdown - Skill Add Interactive Selection
+
+## Milestones
+**What are the major checkpoints?**
+
+- [x] Milestone 1: Command contract updated to allow omitted skill name without breaking explicit installs.
+- [x] Milestone 2: `SkillManager` can enumerate registry skills and prompt for one interactively.
+- [x] Milestone 3: Tests cover prompt and non-prompt flows, plus failure cases.
+
+## Task Breakdown
+**What specific work needs to be done?**
+
+### Phase 1: Command Surface
+- [x] Task 1.1: Update `packages/cli/src/commands/skill.ts` so `add` accepts `[skill-name]`.
+- [x] Task 1.2: Update command descriptions/help text to document the interactive shorthand.
+
+### Phase 2: Interactive Selection Flow
+- [x] Task 2.1: Refactor `SkillManager.addSkill` so it can resolve a missing skill name before install.
+- [x] Task 2.2: Implement registry skill enumeration from the cloned/cached repository.
+- [x] Task 2.3: Implement an `inquirer` selection prompt with skill name and short description labels.
+- [x] Task 2.4: Handle cancel, empty registry, invalid registry, and non-interactive contexts cleanly.
+
+### Phase 3: Validation & Regression Coverage
+- [x] Task 3.1: Add `SkillManager` unit tests for enumeration and prompt behavior.
+- [x] Task 3.2: Add command-level tests for `ai-devkit skill add <registry>` and explicit two-arg installs.
+- [x] Task 3.3: Verify no regression in config updates and environment resolution after interactive selection.
+
+## Dependencies
+**What needs to happen in what order?**
+
+```mermaid
+graph TD
+  T11[1.1 Optional skill arg] --> T21[2.1 Refactor addSkill]
+  T21 --> T22[2.2 Enumerate registry skills]
+  T22 --> T23[2.3 Prompt selection]
+  T23 --> T24[2.4 Edge-case handling]
+  T24 --> T31[3.1 SkillManager tests]
+  T11 --> T32[3.2 Command tests]
+  T23 --> T33[3.3 Regression verification]
+```
+
+## Timeline & Estimates
+**When will things be done?**
+
+- Phase 1: completed
+- Phase 2: completed
+- Phase 3: completed
+- Total implementation effort: completed within the current session
+
+## Risks & Mitigation
+**What could go wrong?**
+
+- Risk: Some registries contain nested or malformed skill directories.
+  - Mitigation: enumerate only folders containing `SKILL.md` and skip invalid entries.
+- Risk: Prompt behavior makes CI jobs hang.
+  - Mitigation: detect non-interactive execution and require explicit `<skill-name>`.
+- Risk: Refactoring `addSkill` accidentally changes direct-install behavior.
+  - Mitigation: keep installation steps intact after skill resolution and add regression tests for the two-arg path.
+
+## Resources Needed
+**What do we need to succeed?**
+
+- Existing `inquirer` dependency already used across the CLI.
+- Existing `SkillManager` cache and registry resolution helpers.
+- Jest command/lib test suites for regression coverage.
+
+## Progress Summary
+Implementation is complete for the current scope. The `skill add` command now accepts an omitted skill name, `SkillManager` resolves available skills from the target registry checkout with cached fallback on refresh failure, and targeted Jest coverage verifies direct install, interactive multi-selection, cancellation, non-interactive failure, and cache-backed selection behavior. Remaining lifecycle work should move to implementation review rather than additional Phase 4 coding unless new scope is introduced.

docs/ai/requirements/feature-skill-add-interactive-selection.md

@@ -0,0 +1,111 @@
+---
+phase: requirements
+title: Requirements & Problem Understanding
+description: Clarify the problem space, gather requirements, and define success criteria
+feature: skill-add-interactive-selection
+---
+
+# Requirements & Problem Understanding - Skill Add Interactive Selection
+
+## Problem Statement
+**What problem are we solving?**
+
+- `ai-devkit skill add` currently requires both `<registry-repo>` and `<skill-name>`, even when the user already knows the registry but not the exact skill identifier.
+- Users installing from a registry often need a discovery step before installation, so they must leave the CLI and inspect the registry manually.
+- This creates friction for first-time installs and makes the add flow inconsistent with the rest of the CLI, which already uses interactive prompts in several commands.
+
+**Who is affected by this problem?**
+
+- Developers using `ai-devkit skill add <registry>` without knowing the exact skill name.
+- Teams exposing many skills from a private or custom registry.
+- New users evaluating available skills before installation.
+
+**What is the current situation/workaround?**
+
+- Users must inspect the registry repository manually and identify the skill folder name under `skills/<skill-name>`.
+- If they omit the skill name, the command fails at CLI argument parsing instead of helping them continue interactively.
+
+## Goals & Objectives
+**What do we want to achieve?**
+
+**Primary goals:**
+
+- Allow `ai-devkit skill add <registry>` to enter an interactive selection flow when `<skill-name>` is omitted.
+- Build the selectable list from the requested registry itself, not from a hardcoded list.
+- Reuse the existing installation path once the user selects one or more skills.
+- Keep the existing explicit flow `ai-devkit skill add <registry> <skill-name>` unchanged.
+
+**Secondary goals:**
+
+- Show clear, user-friendly errors when the registry is missing, empty, or cannot be read.
+- Support the same registry sources already supported by `SkillManager` (default, global custom, project custom, cached).
+- Keep the selection labels descriptive enough for users to distinguish similar skills.
+
+**Non-goals (explicitly out of scope):**
+
+- Fuzzy search across all registries in the add flow.
+- Changing `skill find` behavior.
+- Adding a new registry metadata format.
+
+## User Stories & Use Cases
+**How will users interact with the solution?**
+
+1. As a developer, I want to run `ai-devkit skill add my-org/skills` so I can choose one or more skills interactively when I do not remember the exact skill names.
+2. As a developer, I want the CLI to show the actual skills available in that registry so I can install several of them without opening GitHub.
+3. As an automation user, I want `ai-devkit skill add <registry> <skill-name>` to keep working non-interactively so existing scripts do not break.
+
+**Key workflows and scenarios:**
+
+- User runs `ai-devkit skill add <registry>` in a TTY:
+  - CLI validates the registry.
+  - CLI fetches or reuses the cached registry repository.
+  - CLI extracts available skills from `skills/*/SKILL.md`.
+  - CLI shows an interactive multi-selection list, even if the registry only exposes one valid skill.
+  - CLI installs each selected skill using the existing add flow.
+- User runs `ai-devkit skill add <registry> <skill-name>`:
+  - Existing direct install flow continues with no interactive prompt.
+- User cancels the prompt:
+  - CLI exits without installing anything and reports cancellation clearly.
+- Registry refresh fails but a cached copy exists:
+  - CLI warns and uses the cached registry contents to build the selection list.
+
+**Edge cases to consider:**
+
+- Registry ID does not exist and is not cached.
+- Registry exists but contains no valid skills.
+- Registry contains directories without `SKILL.md`.
+- Prompt is triggered in a non-interactive environment.
+- Cached registry is stale or update fails before enumeration.
+
+## Success Criteria
+**How will we know when we're done?**
+
+- `ai-devkit skill add <registry>` is accepted by the CLI.
+- When run interactively, the command displays a selection list populated from the target registry.
+- The command still shows the selection list when the registry contains exactly one valid skill.
+- Selecting one or more skills installs each of them through the existing installation path and updates project config exactly as today.
+- `ai-devkit skill add <registry> <skill-name>` continues to work without prompting.
+- Invalid, empty, and non-interactive cases return actionable error messages.
+- If registry refresh fails but a cached copy exists, the command warns and uses the cached list.
+- Automated tests cover direct install, interactive selection, cancellation, empty registry, and non-TTY behavior.
+
+## Constraints & Assumptions
+**What limitations do we need to work within?**
+
+**Technical constraints:**
+
+- Registry resolution must remain consistent with existing merged registry behavior.
+- Skill discovery should rely on the registry repository structure already assumed elsewhere: `skills/<skill-name>/SKILL.md`.
+- The feature should reuse the current `inquirer` dependency rather than adding a new prompt library.
+
+**Assumptions:**
+
+- The selected registry is either configured remotely or already available in the local cache.
+- Skill folder names remain the install identifiers.
+- Description text can be derived from `SKILL.md` when available, or omitted/fallback when not available.
+- If a skill name is explicitly provided in the command, direct installation remains the highest-priority path.
+
+## Questions & Open Items
+**What do we still need to clarify?**
+
+- None for Phase 2 review. The prompt uses a multi-select list whenever `<skill-name>` is omitted, and cached registry content is acceptable when refresh fails.