feat(cli): prioritize project skill registries over global and default

Author: codeaholicguy

docs/ai/design/feature-project-skill-registry-priority.md

@@ -0,0 +1,50 @@
+---
+phase: design
+title: System Design & Architecture
+description: Merge registry sources with project-first precedence for skill installation
+---
+
+# System Design & Architecture
+
+## Architecture Overview
+```mermaid
+graph TD
+  SkillAdd[ai-devkit skill add] --> SkillManager
+  SkillManager --> DefaultRegistry[Remote default registry.json]
+  SkillManager --> GlobalConfig[~/.ai-devkit/.ai-devkit.json]
+  SkillManager --> ProjectConfig[./.ai-devkit.json]
+  DefaultRegistry --> Merge[Registry merge]
+  GlobalConfig --> Merge
+  ProjectConfig --> Merge
+  Merge --> Resolved[Resolved registry map]
+```
+
+- `SkillManager.fetchMergedRegistry` remains the single merge point.
+- `ConfigManager` adds project registry extraction.
+- Merge order is implemented as object spread with source ordering.
+
+## Data Models
+- Registry map shape: `Record<string, string>`.
+- Project registry extraction supports:
+  - `registries` at root.
+  - `skills.registries` when `skills` is an object.
+
+## API Design
+- `ConfigManager.getSkillRegistries(): Promise<Record<string, string>>`.
+- `SkillManager.fetchMergedRegistry()` now merges three sources.
+
+## Component Breakdown
+- `packages/cli/src/lib/Config.ts`: parse project registry mappings.
+- `packages/cli/src/lib/SkillManager.ts`: apply precedence order.
+- Tests:
+  - `packages/cli/src/__tests__/lib/Config.test.ts`
+  - `packages/cli/src/__tests__/lib/SkillManager.test.ts`
+
+## Design Decisions
+- Keep merge logic centralized in `SkillManager` to avoid drift.
+- Keep parser tolerant to allow gradual config evolution.
+- Favor project determinism by applying project map last.
+
+## Non-Functional Requirements
+- No additional network calls.
+- No change to failure mode when default registry fetch fails (still supports fallback sources).

docs/ai/implementation/feature-project-skill-registry-priority.md

@@ -0,0 +1,50 @@
+---
+phase: implementation
+title: Implementation Guide
+description: Implementation notes for project-level registry override precedence
+---
+
+# Implementation Guide
+
+## Development Setup
+- Work in feature branch/worktree: `feature-project-skill-registry-priority`.
+- Install deps via `npm ci`.
+
+## Code Structure
+- `SkillManager` owns merged registry resolution.
+- `ConfigManager` owns project config parsing helpers.
+
+## Implementation Notes
+### Core Features
+- Added `ConfigManager.getSkillRegistries()` to read project registry map from:
+  - `registries` (root), or
+  - `skills.registries` (legacy-compatible fallback when `skills` is object).
+- Updated `SkillManager.fetchMergedRegistry()` to merge in this order:
+  - default registry,
+  - global registries,
+  - project registries.
+
+### Patterns & Best Practices
+- Ignore malformed/non-string registry values.
+- Keep merge deterministic and centralized.
+
+## Error Handling
+- If project config has no valid registry map, return `{}` and continue.
+- Existing default-registry fetch warning behavior remains unchanged.
+
+## Performance Considerations
+- No new network requests.
+- Constant-time map merge relative to source map sizes.
+
+## Check Implementation (Phase 6)
+- Requirements-to-code mapping:
+- Project registry source support implemented in `packages/cli/src/lib/Config.ts` via `getSkillRegistries()`.
+- Precedence contract (`project > global > default`) implemented in `packages/cli/src/lib/SkillManager.ts` within `fetchMergedRegistry()`.
+- Compatibility preserved:
+- Existing global override behavior still works.
+- Default registry fetch fallback behavior unchanged.
+
+## Code Review (Phase 8)
+- Reviewed changed production files for regressions in install flow and config parsing.
+- No blocking issues found.
+- Residual risk: only unit-level validation was run; end-to-end CLI fixture validation is still optional follow-up.

docs/ai/planning/feature-project-skill-registry-priority.md

@@ -0,0 +1,42 @@
+---
+phase: planning
+title: Project Planning & Task Breakdown
+description: Implement and validate project/global/default registry precedence
+---
+
+# Project Planning & Task Breakdown
+
+## Milestones
+- [x] Milestone 1: Define requirements and precedence contract.
+- [x] Milestone 2: Implement registry source parsing and merge order.
+- [x] Milestone 3: Add automated tests and validate feature docs.
+
+## Task Breakdown
+### Phase 1: Requirements & Design
+- [x] Task 1.1: Confirm desired precedence (`project > global > default`).
+- [x] Task 1.2: Define where project registry mappings are read from.
+
+### Phase 2: Implementation
+- [x] Task 2.1: Add `ConfigManager.getSkillRegistries()`.
+- [x] Task 2.2: Update `SkillManager.fetchMergedRegistry()` merge order.
+
+### Phase 3: Validation
+- [x] Task 3.1: Add/adjust tests for project registry parsing.
+- [x] Task 3.2: Add/adjust tests for precedence conflicts.
+- [x] Task 3.3: Run focused CLI tests and feature lint.
+
+## Dependencies
+- Existing `ConfigManager` and `GlobalConfigManager` APIs.
+- Existing `SkillManager` registry merge flow.
+
+## Timeline & Estimates
+- Implementation and tests: same working session.
+- Validation: focused unit suite execution.
+
+## Risks & Mitigation
+- Risk: project config schema ambiguity.
+- Mitigation: support both root and nested registry map formats and ignore invalid entries.
+
+## Execution Log
+- 2026-02-27: Ran focused tests for `ConfigManager` and `SkillManager` (73 passing).
+- 2026-02-27: Ran `npx ai-devkit@latest lint --feature project-skill-registry-priority` (pass).

docs/ai/requirements/feature-project-skill-registry-priority.md

@@ -0,0 +1,40 @@
+---
+phase: requirements
+title: Requirements & Problem Understanding
+description: Add project-level registry source with deterministic precedence for skill installation
+---
+
+# Requirements & Problem Understanding
+
+## Problem Statement
+- Skill installation currently resolves registries from default remote registry plus global config (`~/.ai-devkit/.ai-devkit.json`).
+- Teams need project-specific overrides in repository config so installs are reproducible across contributors and CI.
+- Without project-level override, users must edit global state and cannot keep registry decisions version-controlled.
+
+## Goals & Objectives
+- Add project `.ai-devkit.json` as an additional registry source for skill installation.
+- Enforce deterministic conflict precedence: `project > global > default`.
+- Preserve backward compatibility for existing projects and global-only users.
+
+## Non-Goals
+- Redesigning the entire `.ai-devkit.json` schema.
+- Changing non-install commands that do not rely on registry resolution.
+- Introducing remote registry auth or secret management.
+
+## User Stories & Use Cases
+- As a project maintainer, I can define custom registry mappings in project config so all contributors use the same registry source.
+- As a developer with personal global overrides, project overrides still win inside that repository.
+- As an existing user with only global config, behavior remains unchanged.
+
+## Success Criteria
+- `ai-devkit skill add` reads registry maps from project config, global config, and default registry.
+- On key collision, selected URL follows `project > global > default`.
+- Unit tests cover precedence and parsing behavior.
+
+## Constraints & Assumptions
+- Current runtime already reads `.ai-devkit.json` via `ConfigManager`.
+- Project configs may contain either root `registries` or nested `skills.registries`; both should be accepted for resilience.
+- Invalid non-string entries are ignored.
+
+## Questions & Open Items
+- None blocking for implementation.

docs/ai/testing/feature-project-skill-registry-priority.md

@@ -0,0 +1,36 @@
+---
+phase: testing
+title: Testing Strategy
+description: Test precedence and parsing for project/global/default skill registries
+---
+
+# Testing Strategy
+
+## Test Coverage Goals
+- Unit coverage for new/changed behavior in `ConfigManager` and `SkillManager`.
+- Validate precedence conflict resolution and parser resilience.
+
+## Unit Tests
+### ConfigManager
+- [x] Reads registry map from root `registries`.
+- [x] Falls back to nested `skills.registries` when root map is absent.
+- [x] Returns empty map when no valid registry map exists.
+
+### SkillManager
+- [x] Uses custom global registry over default (existing behavior retained).
+- [x] Uses project registry over global and default on ID collision.
+
+## Integration Tests
+- [ ] Optional follow-up: CLI-level `skill add` using fixture `.ai-devkit.json` with project overrides.
+
+## Test Reporting & Coverage
+- Focused command executed:
+  - `npm run test --workspace=packages/cli -- --runInBand src/__tests__/lib/Config.test.ts src/__tests__/lib/SkillManager.test.ts`
+  - Result: 2 suites passed, 73 tests passed, 0 failed.
+- Feature documentation lint:
+  - `npx ai-devkit@latest lint --feature project-skill-registry-priority`
+  - Result: pass.
+
+## Coverage Gaps
+- No known unit-test gaps for changed paths.
+- Optional integration follow-up remains open for full CLI fixture validation.

packages/cli/src/__tests__/lib/Config.test.ts

@@ -404,4 +404,66 @@ describe('ConfigManager', () => {
       expect(mockFs.writeJson).not.toHaveBeenCalled();
     });
   });
+
+  describe('getSkillRegistries', () => {
+    it('returns registries from root-level "registries"', async () => {
+      (mockFs.pathExists as any).mockResolvedValue(true);
+      (mockFs.readJson as any).mockResolvedValue({
+        version: '1.0.0',
+        environments: ['cursor'],
+        phases: [],
+        registries: {
+          'project/skills': 'https://github.com/project/skills.git',
+          'invalid/entry': 123
+        },
+        createdAt: '2024-01-01T00:00:00.000Z',
+        updatedAt: '2024-01-01T00:00:00.000Z'
+      });
+
+      const registries = await configManager.getSkillRegistries();
+
+      expect(registries).toEqual({
+        'project/skills': 'https://github.com/project/skills.git'
+      });
+    });
+
+    it('falls back to nested "skills.registries" when root registries are missing', async () => {
+      (mockFs.pathExists as any).mockResolvedValue(true);
+      (mockFs.readJson as any).mockResolvedValue({
+        version: '1.0.0',
+        environments: ['cursor'],
+        phases: [],
+        skills: {
+          registries: {
+            'nested/skills': 'https://github.com/nested/skills.git',
+            'invalid/value': false
+          }
+        },
+        createdAt: '2024-01-01T00:00:00.000Z',
+        updatedAt: '2024-01-01T00:00:00.000Z'
+      });
+
+      const registries = await configManager.getSkillRegistries();
+
+      expect(registries).toEqual({
+        'nested/skills': 'https://github.com/nested/skills.git'
+      });
+    });
+
+    it('returns empty object when no registry map exists', async () => {
+      (mockFs.pathExists as any).mockResolvedValue(true);
+      (mockFs.readJson as any).mockResolvedValue({
+        version: '1.0.0',
+        environments: ['cursor'],
+        phases: [],
+        skills: [{ registry: 'codeaholicguy/ai-devkit', name: 'debug' }],
+        createdAt: '2024-01-01T00:00:00.000Z',
+        updatedAt: '2024-01-01T00:00:00.000Z'
+      });
+
+      const registries = await configManager.getSkillRegistries();
+
+      expect(registries).toEqual({});
+    });
+  });
 });

packages/cli/src/__tests__/lib/SkillManager.test.ts

@@ -75,6 +75,7 @@ describe("SkillManager", () => {
       new MockedGlobalConfigManager() as jest.Mocked<GlobalConfigManager>;
 
     mockGlobalConfigManager.getSkillRegistries.mockResolvedValue({});
+    mockConfigManager.getSkillRegistries.mockResolvedValue({});
 
     skillManager = new SkillManager(
       mockConfigManager,
@@ -216,6 +217,56 @@ describe("SkillManager", () => {
       );
     });
 
+    it("should prefer project registry URL over global and default", async () => {
+      const defaultGitUrl = "https://github.com/default/skills.git";
+      const globalGitUrl = "https://github.com/global/skills.git";
+      const projectGitUrl = "https://github.com/project/skills.git";
+
+      mockFetch({
+        registries: {
+          [mockRegistryId]: defaultGitUrl,
+        },
+      });
+
+      mockGlobalConfigManager.getSkillRegistries.mockResolvedValue({
+        [mockRegistryId]: globalGitUrl,
+      });
+      mockConfigManager.getSkillRegistries.mockResolvedValue({
+        [mockRegistryId]: projectGitUrl,
+      });
+
+      const repoPath = path.join(
+        os.homedir(),
+        ".ai-devkit",
+        "skills",
+        mockRegistryId,
+      );
+
+      (mockedFs.pathExists as any).mockImplementation((checkPath: string) => {
+        if (checkPath === repoPath) {
+          return Promise.resolve(false);
+        }
+
+        if (checkPath.includes(`${path.sep}skills${path.sep}${mockSkillName}`)) {
+          return Promise.resolve(true);
+        }
+
+        if (checkPath.endsWith(`${path.sep}SKILL.md`)) {
+          return Promise.resolve(true);
+        }
+
+        return Promise.resolve(true);
+      });
+
+      await skillManager.addSkill(mockRegistryId, mockSkillName);
+
+      expect(mockedGitUtil.cloneRepository).toHaveBeenCalledWith(
+        path.join(os.homedir(), ".ai-devkit", "skills"),
+        mockRegistryId,
+        projectGitUrl,
+      );
+    });
+
     it("should read custom registries from global config", async () => {
       const customGitUrl = "https://github.com/custom/skills.git";
       const { GlobalConfigManager: RealGlobalConfigManager } = jest.requireActual(

packages/cli/src/lib/Config.ts

@@ -112,4 +112,23 @@ export class ConfigManager {
     skills.push(skill);
     return this.update({ skills });
   }
+
+  async getSkillRegistries(): Promise<Record<string, string>> {
+    const config = await this.read() as any;
+    const rootRegistries = config?.registries;
+    const nestedRegistries =
+      config?.skills && !Array.isArray(config.skills)
+        ? config.skills.registries
+        : undefined;
+
+    const registries = rootRegistries ?? nestedRegistries;
+
+    if (!registries || typeof registries !== 'object' || Array.isArray(registries)) {
+      return {};
+    }
+
+    return Object.fromEntries(
+      Object.entries(registries).filter(([, value]) => typeof value === 'string')
+    ) as Record<string, string>;
+  }
 }

packages/cli/src/lib/SkillManager.ts

@@ -379,12 +379,14 @@ export class SkillManager {
       defaultRegistries = {};
     }
 
-    const customRegistries = await this.globalConfigManager.getSkillRegistries();
+    const globalRegistries = await this.globalConfigManager.getSkillRegistries();
+    const projectRegistries = await this.configManager.getSkillRegistries();
 
     return {
       registries: {
         ...defaultRegistries,
-        ...customRegistries
+        ...globalRegistries,
+        ...projectRegistries
       }
     };
   }