Skip to content

Commit 30512c5

Browse files
codeaholicguycodeaholicguy
committed
Add logo
1 parent d03ad6b commit 30512c5

9 files changed

Lines changed: 573 additions & 0 deletions

File tree

‎docs/ai/design/feature-setup-wizard.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
phase: design
3+
title: System Design & Architecture
4+
description: Define the technical architecture, components, and data models
5+
---
6+
7+
# System Design & Architecture
8+
9+
## Architecture Overview
10+
**What is the high-level system structure?**
11+
12+
- Include a mermaid diagram that captures the main components and their relationships. Example:
13+
```mermaid
14+
graph TD
15+
User -->|CLI| SetupWizard
16+
SetupWizard --> Detector[Environment Detector]
17+
SetupWizard --> ProfileEngine[Profile Recommender]
18+
SetupWizard --> Planner[Plan Builder]
19+
Planner --> Adapters[Tool Adapters]
20+
Adapters --> FileOps[Safe File Ops]
21+
FileOps --> ToolDirs[Global Tool Directories]
22+
Planner --> StateStore[Setup State + Manifest]
23+
SetupWizard --> Reporter[Result Reporter]
24+
```
25+
- Key components and their responsibilities
26+
- SetupWizard: orchestrates interactive and non-interactive flows.
27+
- Environment Detector: discovers installed/supported tools and existing global configs.
28+
- Profile Recommender: proposes setup defaults by user persona (quickstart, team baseline, custom).
29+
- Plan Builder: computes deterministic operations (`create`, `update`, `skip`, `backup`).
30+
- Tool Adapters: map tool capabilities and paths (commands/skills/instruction files).
31+
- Safe File Ops: apply with backup, dry-run preview, conflict handling, and rollback boundaries.
32+
- State Store: keeps setup metadata for idempotency and drift detection.
33+
- Reporter: prints result summary and next-step recommendations.
34+
- Technology stack choices and rationale
35+
- Node/TypeScript to align with current CLI architecture.
36+
- Reuse existing prompt UI (`inquirer` and terminal-ui abstractions) for consistent UX.
37+
- Adapter-based design to avoid hardcoded branching and simplify future tool expansion.
38+
39+
## Data Models
40+
**What data do we need to manage?**
41+
42+
- Core entities and their relationships
43+
- ToolAdapter: describes capabilities and paths for one environment.
44+
- SetupProfile: predefined recommendation set (assets + policies).
45+
- SetupPlan: resolved operations generated from user choices + current state.
46+
- SetupState: persisted metadata from prior setup runs.
47+
- SetupReport: structured outcome summary of applied/skipped/failed operations.
48+
- Data schemas/structures
49+
- `ToolAdapter`
50+
- `{ code, name, capabilities: { globalCommands, globalSkills, globalInstructionFile }, paths, formats }`
51+
- `SetupPlan`
52+
- `{ id, createdAt, toolSelections, operations[], backupPolicy, overwritePolicy, dryRun }`
53+
- `Operation`
54+
- `{ type, source, target, assetType, toolCode, strategy, status, reason? }`
55+
- `SetupState`
56+
- `{ version, lastRunAt, fingerprintsByTarget, selectedProfile, selectedTools }`
57+
- Data flow between components
58+
- Detector -> Profile Recommender -> Plan Builder -> Safe File Ops -> State Store -> Reporter.
59+
60+
## API Design
61+
**How do components communicate?**
62+
63+
- External APIs (if applicable)
64+
- No mandatory external API calls in v1 core flow.
65+
- Optional future metadata refresh may use registry endpoints if online.
66+
- Internal interfaces
67+
- `detectEnvironments(): DetectedEnvironment[]`
68+
- `recommendProfiles(context): SetupProfile[]`
69+
- `buildPlan(input): SetupPlan`
70+
- `applyPlan(plan): SetupReport`
71+
- `renderReport(report): void`
72+
- Request/response formats
73+
- CLI entry points
74+
- `npx ai-devkit setup` (interactive wizard default)
75+
- `npx ai-devkit setup --non-interactive --profile <name> --tools codex,claude --assets commands,skills`
76+
- `npx ai-devkit setup --dry-run`
77+
- `npx ai-devkit setup --doctor` (recommended extension for diagnostics)
78+
- Output
79+
- Human-readable summary by default.
80+
- Optional machine-readable JSON report (`--json`) for CI/auditing.
81+
- Authentication/authorization approach
82+
- Setup writes only to user-accepted paths.
83+
- No secret material stored in setup state.
84+
- Existing auth for each tool remains managed by that tool.
85+
86+
## Component Breakdown
87+
**What are the major building blocks?**
88+
89+
- Frontend components (if applicable)
90+
- Terminal wizard screens: welcome, profile selection, tool selection, asset selection, preview, apply, summary.
91+
- Backend services/modules
92+
- `SetupWizardService`
93+
- `EnvironmentDetector`
94+
- `ProfileRecommendationService`
95+
- `SetupPlanner`
96+
- `SetupExecutor`
97+
- `SetupStateRepository`
98+
- `SetupReporter`
99+
- Database/storage layer
100+
- Local state file under user config/cache path (for example `~/.ai-devkit/setup-state.json`).
101+
- Backup snapshots with timestamps when overwrite policy requires backup.
102+
- Third-party integrations
103+
- Tool path conventions from Codex/Claude/Antigravity adapter definitions.
104+
- Optional shells for environment checks where required.
105+
106+
## Design Decisions
107+
**Why did we choose this approach?**
108+
109+
- Key architectural decisions and trade-offs
110+
- Make wizard the default instead of requiring `--global`:
111+
- Pros: better discoverability, lower onboarding friction.
112+
- Cons: users who prefer scripts need explicit non-interactive flags.
113+
- Use capability-driven adapters instead of tool-specific branching:
114+
- Pros: scalable for new tools and clearer testability.
115+
- Cons: initial refactor overhead.
116+
- Use plan/apply workflow with dry-run:
117+
- Pros: safer writes, auditable operations, easier debugging.
118+
- Cons: slightly more implementation complexity.
119+
- Keep idempotent state + fingerprints:
120+
- Pros: fast reruns, accurate drift detection.
121+
- Cons: need robust state migration/versioning.
122+
- Keep setup local-first (no required network):
123+
- Pros: reliable and fast.
124+
- Cons: recommendations may be less dynamic without optional online metadata.
125+
- Alternatives considered
126+
- Keep `setup --global` and add more flags:
127+
- Rejected: scales poorly as feature matrix grows.
128+
- One-off shell scripts per tool:
129+
- Rejected: difficult to maintain and non-portable.
130+
- Full policy engine in v1:
131+
- Deferred: high complexity for limited initial user value.
132+
- Patterns and principles applied
133+
- Progressive disclosure (quick path vs advanced mode).
134+
- Idempotent infrastructure-like planning/apply model.
135+
- Fail-soft execution: partial success with explicit report.
136+
137+
## Non-Functional Requirements
138+
**How should the system perform?**
139+
140+
- Performance targets
141+
- Startup detection and wizard initialization under 2s for typical local setups.
142+
- Dry-run planning under 1s with warm state.
143+
- Scalability considerations
144+
- Adapter registry should support 10+ environments without major UX degradation.
145+
- File operation engine should handle large command/skill templates predictably.
146+
- Security requirements
147+
- Never write outside approved user paths.
148+
- Never overwrite without policy confirmation.
149+
- Never persist secrets in state, logs, or reports.
150+
- Reliability/availability needs
151+
- Each operation isolated; one tool failure should not corrupt others.
152+
- Backup and recoverable operations for overwrite scenarios.
153+
- Clear actionable failure messages with remediation steps.
154+

‎docs/ai/implementation/feature-setup-wizard.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
phase: implementation
3+
title: Implementation Guide
4+
description: Technical implementation notes, patterns, and code guidelines
5+
---
6+
7+
# Implementation Guide
8+
9+
## Development Setup
10+
**How do we get started?**
11+
12+
- Prerequisites and dependencies
13+
- Node.js and npm installed
14+
- Existing CLI project bootstrap complete
15+
- Environment setup steps
16+
- `npm install`
17+
- `npm run build`
18+
- `npm test` (baseline before changes)
19+
- Configuration needed
20+
- Existing templates in `packages/cli/templates`
21+
- Environment capability definitions in `packages/cli/src/util/env.ts`
22+
23+
## Code Structure
24+
**How is the code organized?**
25+
26+
- Directory structure
27+
- `packages/cli/src/commands/setup.ts` (entrypoint orchestration)
28+
- `packages/cli/src/lib/EnvironmentSelector.ts` (wizard interaction)
29+
- `packages/cli/src/lib/TemplateManager.ts` (asset application)
30+
- Add new modules:
31+
- `packages/cli/src/lib/setup/SetupWizardService.ts`
32+
- `packages/cli/src/lib/setup/SetupPlanner.ts`
33+
- `packages/cli/src/lib/setup/SetupExecutor.ts`
34+
- `packages/cli/src/lib/setup/SetupStateRepository.ts`
35+
- `packages/cli/src/lib/setup/ProfileRecommendationService.ts`
36+
- `packages/cli/src/lib/setup/adapters/*.ts`
37+
- Module organization
38+
- Keep command thin and push behavior into testable services.
39+
- Keep planner pure (input -> plan) and executor side-effectful.
40+
- Naming conventions
41+
- `*Plan`, `*Executor`, `*Adapter`, `*Report` for clear responsibility boundaries.
42+
43+
## Implementation Notes
44+
**Key technical details to remember:**
45+
46+
### Core Features
47+
- Feature 1: Wizard-first setup flow
48+
- Default `setup` runs wizard.
49+
- Legacy `--global` remains as compatibility alias and maps into wizard preset.
50+
- Feature 2: Plan/apply architecture
51+
- Build a deterministic `SetupPlan` before any write.
52+
- Support `--dry-run` and `--json` reporting.
53+
- Feature 3: Multi-tool adapter support
54+
- Implement adapters for Codex, Claude Code, Antigravity first.
55+
- Each adapter exposes capabilities and path rules for commands/skills/instruction docs.
56+
- Feature 4: Idempotent reruns
57+
- Fingerprint targets; skip unchanged files.
58+
- Backup modified targets before overwrite if policy requires.
59+
60+
### Patterns & Best Practices
61+
- Keep CLI prompts and business logic separate.
62+
- Use explicit operation objects rather than inline file writes.
63+
- Treat partial failure as recoverable; continue safe operations and summarize errors.
64+
- Prefer append-only logs/reporting and avoid hidden side effects.
65+
66+
## Integration Points
67+
**How do pieces connect?**
68+
69+
- API integration details
70+
- No required external APIs for v1.
71+
- Optional future online metadata can be integrated behind a feature flag.
72+
- Database connections
73+
- No database; local JSON state only.
74+
- Third-party service setup
75+
- No third-party service required for core wizard execution.
76+
77+
## Error Handling
78+
**How do we handle failures?**
79+
80+
- Error handling strategy
81+
- Planner errors fail fast before any write.
82+
- Executor errors are collected per operation and reported clearly.
83+
- Logging approach
84+
- Reuse terminal UI helpers for info/warn/error channels.
85+
- Include target path + operation type in error output.
86+
- Retry/fallback mechanisms
87+
- For write conflicts, allow retry with alternate policy (skip/overwrite/backup).
88+
- Preserve successfully applied operations even when later steps fail.
89+
90+
## Performance Considerations
91+
**How do we keep it fast?**
92+
93+
- Optimization strategies
94+
- Cache detection results during a single wizard run.
95+
- Compare fingerprints to skip unchanged targets.
96+
- Caching approach
97+
- Persist setup state to avoid redundant checks across reruns.
98+
- Query optimization
99+
- Not applicable (local file operations only in v1).
100+
- Resource management
101+
- Use bounded concurrency for file operations to avoid I/O spikes.
102+
103+
## Security Notes
104+
**What security measures are in place?**
105+
106+
- Authentication/authorization
107+
- No auth handling inside setup; delegate to tool-native auth.
108+
- Input validation
109+
- Validate all tool codes, profile names, and asset types before planning.
110+
- Data encryption
111+
- Not required for non-sensitive setup state.
112+
- Secrets management
113+
- Never copy or persist API keys from environment/tool configs.
114+
- Explicitly avoid touching credential stores (`auth.json`, keychain-backed configs).
115+

‎docs/ai/planning/feature-setup-wizard.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
phase: planning
3+
title: Project Planning & Task Breakdown
4+
description: Break down work into actionable tasks and estimate timeline
5+
---
6+
7+
# Project Planning & Task Breakdown
8+
9+
## Milestones
10+
**What are the major checkpoints?**
11+
12+
- [ ] Milestone 1: Requirements/design approved and migration strategy locked
13+
- [ ] Milestone 2: Core wizard + plan/apply execution implemented
14+
- [ ] Milestone 3: Tool adapters, tests, docs, and rollout guidance complete
15+
16+
## Task Breakdown
17+
**What specific work needs to be done?**
18+
19+
### Phase 1: Foundation
20+
- [ ] Task 1.1: Audit current `setup --global` behavior and codify compatibility requirements
21+
- [ ] Task 1.2: Define `ToolAdapter`, `SetupPlan`, `SetupState`, and `SetupReport` types
22+
- [ ] Task 1.3: Implement environment detection and capability resolution
23+
- [ ] Task 1.4: Define setup profiles (`quickstart`, `team-default`, `custom`)
24+
- [ ] Task 1.5: Add state repository and fingerprint utilities
25+
26+
### Phase 2: Core Features
27+
- [ ] Task 2.1: Build interactive wizard flow for profile/tool/asset selection
28+
- [ ] Task 2.2: Implement dry-run plan preview with clear operation listing
29+
- [ ] Task 2.3: Implement setup executor with backup and overwrite policies
30+
- [ ] Task 2.4: Implement non-interactive mode flags and validation
31+
- [ ] Task 2.5: Add summary/report output (human + optional json)
32+
33+
### Phase 3: Integration & Polish
34+
- [ ] Task 3.1: Migrate existing `setup --global` entry to new wizard architecture
35+
- [ ] Task 3.2: Add adapter support for Codex, Claude Code, and Antigravity
36+
- [ ] Task 3.3: Implement conflict UX for existing customized files
37+
- [ ] Task 3.4: Add `--doctor` diagnostics mode (recommended extension)
38+
- [ ] Task 3.5: Update CLI help, README, and migration notes
39+
40+
### Phase 4: Validation
41+
- [ ] Task 4.1: Unit tests for planner, executor, and adapter mappings
42+
- [ ] Task 4.2: Integration tests for interactive and non-interactive flows
43+
- [ ] Task 4.3: Manual matrix test across macOS/Linux/Windows path behaviors
44+
- [ ] Task 4.4: Benchmark cold and warm run timing against targets
45+
46+
## Dependencies
47+
**What needs to happen in what order?**
48+
49+
- Task dependencies and blockers
50+
- Data model definitions (Phase 1) must land before planner/executor implementation (Phase 2).
51+
- Adapter contracts must be stable before writing integration tests.
52+
- Migration strategy should be confirmed before changing default command behavior.
53+
- External dependencies (APIs, services, etc.)
54+
- None required for v1 local setup path.
55+
- Optional online recommendation sync should remain behind a feature flag.
56+
- Team/resource dependencies
57+
- CLI maintainer for architecture changes.
58+
- Reviewer with cross-platform path and file-permission expertise.
59+
60+
## Timeline & Estimates
61+
**When will things be done?**
62+
63+
- Estimated effort per task/phase
64+
- Phase 1: 1.5-2 days
65+
- Phase 2: 2-3 days
66+
- Phase 3: 1.5-2 days
67+
- Phase 4: 1-1.5 days
68+
- Target dates for milestones
69+
- Milestone 1: end of week 1
70+
- Milestone 2: mid week 2
71+
- Milestone 3: end of week 2
72+
- Buffer for unknowns
73+
- +20% for tool path variance, overwrite edge cases, and migration surprises
74+
75+
## Risks & Mitigation
76+
**What could go wrong?**
77+
78+
- Technical risks
79+
- Incorrect path assumptions per tool may cause invalid writes.
80+
- Migration from `--global` behavior could break existing scripts.
81+
- Resource risks
82+
- Cross-platform validation may be under-tested if limited test machines.
83+
- Dependency risks
84+
- Tool ecosystem changes can invalidate adapter mappings.
85+
- Mitigation strategies
86+
- Add adapter contract tests and fixture-based path validation.
87+
- Preserve compatibility alias for `setup --global` during transition.
88+
- Add explicit preview + confirmation to prevent accidental writes.
89+
- Keep a fast rollback path: feature flag to restore legacy behavior temporarily.
90+
91+
## Resources Needed
92+
**What do we need to succeed?**
93+
94+
- Team members and roles
95+
- CLI implementer, reviewer, and docs owner
96+
- Tools and services
97+
- Existing TypeScript test framework and CI workflow
98+
- Infrastructure
99+
- Cross-platform CI runners or local validation checklists
100+
- Documentation/knowledge
101+
- Canonical tool path/capability matrix for supported environments
102+

0 commit comments

Comments
 (0)