Skip to content

Commit 53a68cd

Browse files
codeaholicguycodeaholicguy
committed
feat(cli): add init template mode with YAML/JSON support
1 parent c93008a commit 53a68cd

File tree

11 files changed

+1147
-14
lines changed

11 files changed

+1147
-14
lines changed

‎docs/ai/design/feature-init-template.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
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.
13+
```mermaid
14+
graph TD
15+
User -->|init --template| InitCommand
16+
InitCommand --> TemplateLoader
17+
TemplateLoader --> TemplateValidator
18+
TemplateValidator --> InitConfigurator
19+
InitConfigurator --> EnvConfigurator[Environment Configurator]
20+
InitConfigurator --> PhaseConfigurator[Phase Configurator]
21+
InitConfigurator --> SkillInstaller[Skill Installer Bridge]
22+
SkillInstaller --> SkillAdd[Existing skill add flow]
23+
InitConfigurator --> Reporter
24+
```
25+
- Key components and their responsibilities
26+
- `InitCommand`: reads CLI args and routes interactive vs template-driven flow.
27+
- `TemplateLoader`: reads template file from path and parses YAML/JSON.
28+
- `TemplateValidator`: validates schema for `environments`, `skills`, and `phases`.
29+
- `InitConfigurator`: orchestrates applying resolved values.
30+
- `SkillInstaller Bridge`: adapts template skill entries into `skill add` invocations.
31+
- `Reporter`: prints summary of applied config + skill install results.
32+
- Technology stack choices and rationale
33+
- Continue with existing Node/TypeScript CLI stack.
34+
- Reuse current argument parsing and prompt layers.
35+
- Reuse existing `skill add` domain logic to avoid duplicated install behavior.
36+
37+
## Data Models
38+
**What data do we need to manage?**
39+
40+
- Core entities and their relationships
41+
- `InitTemplate`
42+
- `TemplateSkill`
43+
- `TemplateValidationResult`
44+
- `SkillInstallResult`
45+
- Data schemas/structures
46+
- `InitTemplate`
47+
- `{ version?, environments?, phases?, skills? }`
48+
- `TemplateSkill`
49+
- `{ registry: string, skill: string, options?: Record<string, string> }`
50+
- Skill entry processing key
51+
- Unique key is `registry + skill`; same registry with different skills is valid and processed as separate installs.
52+
- `SkillInstallResult`
53+
- `{ registry, skill, status: 'installed' | 'skipped' | 'failed', reason? }`
54+
- Data flow between components
55+
- CLI args -> template file parse -> validation -> init apply -> per-skill install -> summary output.
56+
57+
## API Design
58+
**How do components communicate?**
59+
60+
- External APIs (if applicable)
61+
- None required; optional network access occurs only through existing skill installation behavior.
62+
- Internal interfaces
63+
- `loadTemplate(path: string): Promise<unknown>` (supports relative and absolute paths)
64+
- `validateTemplate(raw: unknown): TemplateValidationResult`
65+
- `applyTemplate(config: InitTemplate): Promise<InitApplyResult>`
66+
- `installSkills(skills: TemplateSkill[]): Promise<SkillInstallResult[]>`
67+
- Request/response formats
68+
- CLI command
69+
- `npx ai-devkit init --template <path>`
70+
- Path resolution: absolute path as-is; relative path resolved from current working directory.
71+
- Sample YAML template
72+
```yaml
73+
version: 1
74+
environments:
75+
- codex
76+
- claude
77+
phases:
78+
- requirements
79+
- design
80+
- planning
81+
- implementation
82+
- testing
83+
skills:
84+
- registry: codeaholicguy/ai-devkit
85+
skill: debug
86+
- registry: codeaholicguy/ai-devkit
87+
skill: memory
88+
```
89+
- Output
90+
- Validation errors include template path + invalid field(s).
91+
- Success summary includes configured environments/phases and skill outcomes.
92+
- Skill installation failures are warnings; command exits with code `0` and includes failed items in report.
93+
- Authentication/authorization approach
94+
- No new auth model. Skill installation uses current auth/network behavior in existing `skill add` flow.
95+
96+
## Component Breakdown
97+
**What are the major building blocks?**
98+
99+
- Frontend components (if applicable)
100+
- CLI prompt layer remains as fallback when template is partial.
101+
- Backend services/modules
102+
- `init.command` argument handling (`--template`).
103+
- `template-parser` module.
104+
- `template-validator` module.
105+
- `init-apply` orchestration module.
106+
- `skill-install-adapter` module (bridge to existing install logic).
107+
- Database/storage layer
108+
- No new persistent store required for v1.
109+
- Third-party integrations
110+
- YAML parser library (existing or new lightweight dependency).
111+
112+
## Design Decisions
113+
**Why did we choose this approach?**
114+
115+
- Key architectural decisions and trade-offs
116+
- Reuse `skill add` implementation:
117+
- Pros: consistent behavior and less duplication.
118+
- Cons: init flow depends on skill module API stability.
119+
- Add template as optional mode, not replacement:
120+
- Pros: backward compatibility and low migration risk.
121+
- Cons: dual paths increase test surface.
122+
- Continue-on-error for skill install with exit code `0`:
123+
- Pros: init can apply as much as possible and provide complete failure report in one run.
124+
- Cons: downstream automation must inspect warning/report output instead of relying only on exit code.
125+
- Validate template before applying side effects:
126+
- Pros: deterministic behavior and better errors.
127+
- Cons: requires explicit schema maintenance.
128+
- Alternatives considered
129+
- Implement separate installer inside `init`.
130+
- Rejected due to divergence from `skill add` behavior.
131+
- Force non-interactive mode whenever template provided.
132+
- Rejected; fallback prompts for missing values are more user-friendly.
133+
- Patterns and principles applied
134+
- Schema-first validation.
135+
- Orchestrator + adapters for integration points.
136+
- Backward-compatible CLI extension.
137+
138+
## Non-Functional Requirements
139+
**How should the system perform?**
140+
141+
- Performance targets
142+
- Template loading + validation under 300ms for small files.
143+
- No regression in plain interactive init startup.
144+
- Scalability considerations
145+
- Support multiple skill entries without blocking summary reporting.
146+
- Security requirements
147+
- Treat template input as untrusted; validate and sanitize fields before use.
148+
- Avoid arbitrary command execution from template values.
149+
- Reliability/availability needs
150+
- Partial failure handling for multi-skill installs with explicit status.
151+
- Duplicate `registry + skill` entries are deduplicated during execution and reported as skipped/warning.
152+
- Deterministic error codes for invalid template input.

‎docs/ai/implementation/feature-init-template.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
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+
- Work in `packages/cli` (TypeScript + Commander + Jest).
13+
- Template parsing uses existing dependency `yaml` and `fs-extra`.
14+
- Run focused tests with:
15+
- `npm --workspace packages/cli test -- init.test.ts InitTemplate.test.ts`
16+
17+
## Code Structure
18+
**How is the code organized?**
19+
20+
- `packages/cli/src/lib/InitTemplate.ts`
21+
- Loads template file from relative/absolute path.
22+
- Parses YAML (`.yml`/`.yaml`) and JSON (`.json`).
23+
- Validates schema for `environments`, `phases`, `skills`.
24+
- `packages/cli/src/commands/init.ts`
25+
- Adds template-mode resolution for environments/phases.
26+
- Keeps fallback interactive prompts for missing values.
27+
- Installs template skills via `SkillManager.addSkill`.
28+
- Handles duplicate `registry+skill` and continue-on-error warnings.
29+
- `packages/cli/src/cli.ts`
30+
- Adds `--template <path>` option to `init` command.
31+
32+
## Implementation Notes
33+
**Key technical details to remember:**
34+
35+
### Core Features
36+
- `init --template` is additive, not a replacement for interactive mode.
37+
- Resolution order:
38+
- Environments: CLI `--environment` > template `environments` > prompt.
39+
- Phases: CLI `--all/--phases` > template `phases` > prompt.
40+
- Skill processing:
41+
- Same registry with multiple skills is valid.
42+
- Exact duplicate `registry+skill` entries are skipped with warning.
43+
- Failed skill installs are reported; init continues.
44+
45+
### Patterns & Best Practices
46+
- Validation errors include template file path + field context.
47+
- Template is fully validated before applying side effects.
48+
- Existing `skill add` logic is reused through `SkillManager` to avoid behavior drift.
49+
50+
## Integration Points
51+
**How do pieces connect?**
52+
53+
- `init` command orchestrates:
54+
- `loadInitTemplate` -> environment/phase setup via `TemplateManager` -> skill installs via `SkillManager`.
55+
- No new storage/manifest is introduced in v1.
56+
57+
## Error Handling
58+
**How do we handle failures?**
59+
60+
- Invalid template path/format/schema: fail early with actionable error.
61+
- Skill install failures: continue processing remaining skills, emit warnings.
62+
- Exit behavior for partial skill failure: command returns success (`0`) with warnings.
63+
64+
## Performance Considerations
65+
**How do we keep it fast?**
66+
67+
- Parsing/validation are in-memory and lightweight.
68+
- No network operation introduced beyond existing `skill add` behavior.
69+
70+
## Security Notes
71+
**What security measures are in place?**
72+
73+
- Template input is treated as untrusted and schema-validated.
74+
- No shell execution from template fields.
75+
- Only known keys and expected scalar/array/object shapes are accepted.

‎docs/ai/planning/feature-init-template.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
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+
- [x] Milestone 1: Template requirements + schema/design approved
13+
- [x] Milestone 2: `init --template` core flow implemented
14+
- [x] Milestone 3: Skill auto-install integration + tests/documentation complete
15+
16+
## Task Breakdown
17+
**What specific work needs to be done?**
18+
19+
### Phase 1: Foundation
20+
- [x] Task 1.1: Audit current `init` flow and identify integration point for `--template`
21+
- [x] Task 1.2: Define template schema for `environments`, `skills`, and `phases`
22+
- [x] Task 1.3: Add template loader/parser with path + format handling
23+
- [x] Task 1.4: Add validation and user-friendly error formatting
24+
25+
### Phase 2: Core Features
26+
- [x] Task 2.1: Add `--template <path>` CLI option to `init`
27+
- [x] Task 2.2: Implement template-driven value resolution into init config
28+
- [x] Task 2.3: Add fallback prompts for missing required values
29+
- [x] Task 2.4: Add execution summary output for applied template fields
30+
31+
### Phase 3: Integration & Polish
32+
- [x] Task 3.1: Implement skill-install bridge that invokes existing `skill add` logic
33+
- [x] Task 3.2: Add handling for duplicate/already-installed skills
34+
- [x] Task 3.3: Implement continue-on-error/fail-fast policy based on decided behavior
35+
- [x] Task 3.4: Update CLI help/docs with template examples
36+
37+
### Phase 4: Validation
38+
- [x] Task 4.1: Unit tests for parser/validator/config resolver
39+
- [x] Task 4.2: Integration tests for `init --template` end-to-end flow
40+
- [x] Task 4.3: Integration tests for skill install success/failure matrix
41+
- [x] Task 4.4: Regression tests for existing interactive init behavior
42+
43+
## Dependencies
44+
**What needs to happen in what order?**
45+
46+
- Task dependencies and blockers
47+
- Schema and validation must land before template-driven apply logic.
48+
- Skill bridge implementation depends on stable callable interface from existing skill-add module.
49+
- Error/report format should be agreed before writing integration tests.
50+
- External dependencies (APIs, services, etc.)
51+
- Potential registry/network dependency via skill install path.
52+
- Team/resource dependencies
53+
- CLI maintainer for `init` command.
54+
- Reviewer familiar with skill installation internals.
55+
56+
## Timeline & Estimates
57+
**When will things be done?**
58+
59+
- Estimated effort per task/phase
60+
- Phase 1: 0.5-1 day
61+
- Phase 2: 1-1.5 days
62+
- Phase 3: 0.5-1 day
63+
- Phase 4: 1 day
64+
- Target dates for milestones
65+
- Milestone 1: Day 1
66+
- Milestone 2: Day 2
67+
- Milestone 3: Day 3
68+
- Buffer for unknowns
69+
- +20% for schema evolution and skill-install edge cases
70+
71+
## Risks & Mitigation
72+
**What could go wrong?**
73+
74+
- Technical risks
75+
- Skill-add integration may not expose reusable programmatic interface.
76+
- Template schema ambiguity could produce inconsistent behavior.
77+
- Resource risks
78+
- Limited test fixtures for different skill registry/availability states.
79+
- Dependency risks
80+
- Registry/network instability during skill installation tests.
81+
- Mitigation strategies
82+
- Introduce thin adapter around skill-install logic with explicit contract.
83+
- Lock schema with versioned docs and validation tests.
84+
- Use mockable installation layer for deterministic tests.
85+
86+
## Resources Needed
87+
**What do we need to succeed?**
88+
89+
- Team members and roles
90+
- CLI implementer and reviewer.
91+
- Tools and services
92+
- Existing TypeScript test runner and mocking utilities.
93+
- Infrastructure
94+
- CI job for integration tests covering template mode.
95+
- Documentation/knowledge
96+
- Existing init/skill command architecture references.
97+
98+
## Progress Summary
99+
100+
Feature implementation is complete for template-driven init, including YAML/JSON parsing, relative/absolute template path resolution, template-based environments/phases resolution, and skill auto-install via existing skill-add logic. Duplicate `registry+skill` entries are skipped with warnings, and per-skill failures continue with warning output while preserving exit code `0`. Validation coverage includes parser/validator unit tests and command-level behavior tests for template flow, failure matrix, and interactive regression.
101+
102+
## Next Focus
103+
104+
- Confirm desired behavior for future lock/manifest output (currently out of scope).
105+
- Run full workspace test/lint pipelines before release cut.
106+
- Proceed to implementation check and final code review.

0 commit comments

Comments
 (0)