Add install command

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Install Command** - Added `ai-devkit install` to apply project configuration from `.ai-devkit.json`
+  - Supports `--config <path>` for custom config file locations
+  - Supports `--overwrite` for non-interactive full overwrite mode
+  - Installs environments, phases, and skills in a single run with summary output
+
 ## [0.14.0] - 2026-02-21
 
 ### Changed

docs/ai/design/feature-install-command.md

@@ -0,0 +1,120 @@
+---
+phase: design
+title: System Design & Architecture
+description: Define the technical architecture, components, and data models
+feature: install-command
+---
+
+# System Design & Architecture - Install Command
+
+## Architecture Overview
+
+**What is the high-level system structure?**
+
+```mermaid
+graph TD
+  User[User: ai-devkit install] --> InstallCommand
+  InstallCommand --> ConfigLoader[Config Service: load .ai-devkit.json]
+  ConfigLoader --> Validator[Config Util Validator]
+  Validator --> Reconciler[Install Reconciler]
+  Reconciler --> Confirmer[Overwrite Confirmation Prompt]
+  Reconciler --> EnvSetup[TemplateManager.setupMultipleEnvironments]
+  Reconciler --> PhaseSetup[TemplateManager.copyPhaseTemplate]
+  Reconciler --> SkillSetup[SkillManager.addSkill]
+  SkillSetup --> SkillConfigSync[ConfigManager.update skills metadata]
+  Reconciler --> Reporter[Install Summary Reporter]
+```
+
+**Key components and responsibilities:**
+
+- `install` command handler: orchestrates install lifecycle.
+- `InstallConfig Validator`: validates environments, phases, and optional skills.
+- `Install Reconciler`: computes desired state vs existing files.
+- `TemplateManager` integration: applies environment and phase templates.
+- `SkillManager` integration: installs skills from config entries.
+- `Overwrite Confirmation Prompt`: when destination artifacts already exist, ask user to confirm replacement.
+- `SkillConfigSync`: ensures `ai-devkit skill add` writes skill metadata back to `.ai-devkit.json`.
+- `Reporter`: emits per-section summary and final exit status.
+
+## Data Models
+
+**What data do we need to manage?**
+
+```typescript
+interface DevKitInstallConfig {
+  version: string;
+  environments: EnvironmentCode[];
+  phases: Phase[];
+  skills?: Array<{
+    registry: string;
+    name: string;
+  }>;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+- Existing fields continue unchanged.
+- New `skills` field is optional for backward compatibility.
+- Duplicate skill entries deduplicated by `registry + name`.
+
+## API Design
+
+**How do components communicate?**
+
+**CLI surface:**
+
+- `ai-devkit install`
+- Optional follow-up flags (proposed):
+  - `--config <path>` (default `.ai-devkit.json`)
+  - `--overwrite` (overwrite all existing artifacts without additional prompts)
+
+**Internal interfaces (proposed):**
+
+```typescript
+async function installCommand(options: InstallOptions): Promise<void>;
+async function validateInstallConfig(config: unknown): Promise<ValidatedInstallConfig>;
+async function reconcileAndInstall(config: ValidatedInstallConfig, options: InstallOptions): Promise<InstallReport>;
+```
+
+**Output contract:**
+
+- Section summaries for environments, phases, and skills.
+- Final totals: installed/skipped/failed.
+- Exit codes:
+  - Invalid/missing config: `1`
+  - Valid config with success: `0`
+  - Partial skill-install failures: `0` with warning output and failed item details.
+
+## Component Breakdown
+
+**What are the major building blocks?**
+
+1. `packages/cli/src/commands/install.ts` (new): top-level command execution.
+2. `packages/cli/src/services/config/config.service.ts` (new): load config file from disk.
+3. `packages/cli/src/util/config.ts` (new): schema validation and normalization.
+4. `packages/cli/src/services/install/install.service.ts` (new): reconcile and apply installation.
+5. `packages/cli/src/lib/Config.ts` (update): persist/read `skills` metadata.
+6. `packages/cli/src/lib/SkillManager.ts` (update): on successful `addSkill`, sync skill entry into `.ai-devkit.json`.
+7. `packages/cli/src/cli.ts` (update): register `install` command and options.
+
+## Design Decisions
+
+**Why did we choose this approach?**
+
+- Reuse existing managers (`TemplateManager`, `SkillManager`) for consistency and lower risk.
+- Add `install` as separate command instead of overloading `init` to keep intent clear:
+  - `init`: configure project interactively/template-first.
+  - `install`: apply existing project config deterministically.
+- Keep new config field optional to avoid breaking older projects.
+- Existing artifacts require explicit user confirmation before overwrite (safe interactive default).
+- Partial skill failures do not fail the whole install run; command exits `0` and reports warnings for failed items.
+
+## Non-Functional Requirements
+
+**How should the system perform?**
+
+- Performance: install should scale linearly with configured phases and skills.
+- Reliability: each section continues independently and reports failures.
+- Security: validate config values before filesystem/network actions.
+- Usability: actionable errors that point to field names and file path.

docs/ai/implementation/feature-install-command.md

@@ -0,0 +1,76 @@
+---
+phase: implementation
+title: Implementation Guide
+description: Technical implementation notes, patterns, and code guidelines
+feature: install-command
+---
+
+# Implementation Guide - Install Command
+
+## Development Setup
+
+- Implemented in `packages/cli` using existing command architecture (`commander`).
+- Uses `zod` for schema-based config validation.
+- Feature reuses existing managers: `ConfigManager`, `TemplateManager`, `SkillManager`.
+
+## Code Structure
+
+- `packages/cli/src/commands/install.ts`
+  - New CLI handler for `ai-devkit install`.
+  - Handles config loading, report output, and process exit code.
+- `packages/cli/src/services/config/config.service.ts`
+  - Loads and parses config file JSON from disk.
+- `packages/cli/src/util/config.ts`
+  - Validates and normalizes install config data using Zod.
+  - Supports skill shape normalization (`name` and legacy `skill` key).
+- `packages/cli/src/services/install/install.service.ts`
+  - Reconciles desired state and applies environment/phase/skill installation.
+  - Implements overwrite and warning-based partial-failure policy.
+- `packages/cli/src/types.ts`
+  - Adds optional `skills` metadata to `DevKitConfig`.
+- `packages/cli/src/lib/Config.ts`
+  - Adds `addSkill` helper to persist unique `registry + name` entries.
+- `packages/cli/src/lib/SkillManager.ts`
+  - Persists metadata to `.ai-devkit.json` after successful `skill add`.
+- `packages/cli/src/cli.ts`
+  - Registers new `install` command and options.
+
+## Implementation Notes
+
+### CLI Surface
+
+- `ai-devkit install`
+- Options:
+  - `--config <path>`: alternate config file path (default `.ai-devkit.json`)
+  - `--overwrite`: overwrite all existing artifacts without additional prompts
+
+### Reconcile Behavior
+
+- Environments and phases are installed section-by-section.
+- Existing artifacts are skipped unless overwrite mode is confirmed.
+- Skill failures are collected as warnings and do not fail run by default.
+- Skills are deduplicated by `registry + name` before installation.
+
+### Exit Code Policy
+
+- `1` for invalid/missing config.
+- `1` for environment/phase failures.
+- `0` for successful run and for skill-only partial failures.
+
+## Error Handling
+
+- Validation errors include field-level context and config file path.
+- Orchestrator aggregates per-item warnings and reports all failures at the end.
+- Install command prints summary and warnings before setting final exit code.
+
+## Performance Considerations
+
+- Linear processing by environments/phases/skills.
+- No additional network calls beyond existing `SkillManager` behavior.
+- Config normalization avoids duplicate work for duplicate entries.
+
+## Security Notes
+
+- Input is validated before filesystem/network operations.
+- Unsupported environments/phases are rejected early.
+- Empty/invalid skill metadata is rejected before installation.

docs/ai/planning/feature-install-command.md

@@ -0,0 +1,95 @@
+---
+phase: planning
+title: Project Planning & Task Breakdown
+description: Break down work into actionable tasks and estimate timeline
+feature: install-command
+---
+
+# Project Planning & Task Breakdown - Install Command
+
+## Milestones
+
+**What are the major checkpoints?**
+
+- [x] Milestone 1: Requirements/design approved for `ai-devkit install`.
+- [x] Milestone 2: Core install flow (config read + env/phase reconcile) implemented.
+- [x] Milestone 3: Skill install integration + tests + docs completed.
+
+## Task Breakdown
+
+**What specific work needs to be done?**
+
+### Phase 1: Foundation
+
+- [x] Task 1.1: Add `install` command wiring in `packages/cli/src/cli.ts`.
+- [x] Task 1.2: Implement install config validator for `.ai-devkit.json`.
+- [x] Task 1.3: Define backward-compatible skills schema (`skills[]` optional).
+- [x] Task 1.4: Add install report model (installed/skipped/failed counters).
+
+### Phase 2: Core Features
+
+- [x] Task 2.1: Implement environment setup from `environments` using `TemplateManager`.
+- [x] Task 2.2: Implement phase setup from `phases` using `TemplateManager`.
+- [x] Task 2.3: Add idempotent handling for existing artifacts.
+- [x] Task 2.4: Add `--overwrite` behavior and conflict messaging.
+
+### Phase 3: Skills Integration
+
+- [x] Task 3.1: Implement skills install loop from config skills entries.
+- [x] Task 3.2: Deduplicate skill entries by `registry + name`.
+- [x] Task 3.3: Add partial-failure handling with warning-only skill failures.
+- [x] Task 3.4: Update config types/read-write paths for optional `skills` field.
+
+### Phase 4: Validation & Docs
+
+- [x] Task 4.1: Unit tests for config validation and normalization.
+- [x] Task 4.2: Integration tests for full `ai-devkit install` happy path.
+- [x] Task 4.3: Integration tests for missing config, invalid config, and partial failures.
+- [x] Task 4.4: Update README/CLI help/changelog with usage examples.
+
+## Dependencies
+
+**What needs to happen in what order?**
+
+```mermaid
+graph TD
+  T11[1.1 CLI wiring] --> T12[1.2 validator]
+  T12 --> T21[2.1 env setup]
+  T12 --> T22[2.2 phase setup]
+  T13[1.3 skills schema] --> T31[3.1 skills install]
+  T31 --> T33[3.3 strict/partial failure]
+  T21 --> T41[4.1 tests]
+  T22 --> T42[4.2 integration]
+  T33 --> T43[4.3 failure tests]
+  T42 --> T44[4.4 docs]
+  T43 --> T44
+```
+
+## Timeline & Estimates
+
+**When will things be done?**
+
+- Phase 1: completed
+- Phase 2: completed
+- Phase 3: completed
+- Phase 4: completed
+- Remaining estimate: 0 day
+
+## Risks & Mitigation
+
+**What could go wrong?**
+
+- Risk: Existing `.ai-devkit.json` files lack `skills`.
+  - Mitigation: keep field optional and treat as empty array.
+- Risk: Skill installs fail because of network/registry issues.
+  - Mitigation: continue on error and collect warnings with clear per-skill failure details.
+- Risk: Overwrite policy causes accidental template replacement.
+  - Mitigation: default skip existing artifacts unless `--overwrite` is enabled.
+
+## Resources Needed
+
+**What do we need to succeed?**
+
+- Existing CLI command framework (`commander`).
+- Existing managers (`ConfigManager`, `TemplateManager`, `SkillManager`).
+- Test harness for command-level tests.