Skip to content

Commit ed9fad2

Browse files
codeaholicguycodeaholicguy
committed
Add lint command planning
1 parent 3d3325d commit ed9fad2

File tree

5 files changed

+479
-0
lines changed

5 files changed

+479
-0
lines changed

‎docs/ai/design/feature-lint-command.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
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+
```mermaid
13+
graph TD
14+
User --> CLI[ai-devkit lint command]
15+
CLI --> ArgParser[Feature and output argument parser]
16+
ArgParser --> LintService[Lint validation service]
17+
LintService --> BaseCheck[Base docs checker]
18+
LintService --> FeatureCheck[Feature docs checker]
19+
LintService --> GitCheck[Worktree and branch checker]
20+
BaseCheck --> FS[(File System)]
21+
FeatureCheck --> FS
22+
GitCheck --> Git[(Git metadata)]
23+
LintService --> Reporter[Terminal and JSON reporter]
24+
```
25+
26+
- Key components and responsibilities
27+
- `lint` command handler: parse options and orchestrate checks.
28+
- Name normalizer: convert `--feature` input into canonical `<name>` and `feature-<name>` (accept `foo` and `feature-foo`).
29+
- Base docs checker: validate required phase template files (`docs/ai/*/README.md`).
30+
- Feature docs checker: validate `docs/ai/{phase}/feature-<name>.md` across lifecycle phases.
31+
- Git/worktree checker: evaluate feature branch/worktree convention used by `dev-lifecycle` Phase 1 prerequisite.
32+
- Reporter: consistent output rows (`[OK]`, `[MISS]`, `[WARN]`) and final summary with exit code.
33+
- Technology stack choices and rationale
34+
- TypeScript within existing CLI package for shared UX and testability.
35+
- Extract shell script checks into reusable TS utilities to avoid behavior drift.
36+
- Git checks via lightweight git commands (`git worktree list`, branch existence checks) to preserve compatibility.
37+
38+
## Data Models
39+
**What data do we need to manage?**
40+
41+
- Core entities and their relationships
42+
- `LintOptions`: parsed CLI options.
43+
- `LintTarget`: normalized feature identity (`name`, `branchName`, `docSlug`).
44+
- `LintCheckResult`: result of individual check.
45+
- `LintSummary`: aggregate counts and final status.
46+
- Data schemas/structures
47+
- `LintOptions`
48+
- `{ feature?: string, json?: boolean }`
49+
- `LintTarget`
50+
- `{ rawFeature: string, normalizedName: string, branchName: string, docFilePrefix: string }`
51+
- `LintCheckResult`
52+
- `{ id: string, level: 'ok' | 'miss' | 'warn', category: 'base-docs' | 'feature-docs' | 'git-worktree', required: boolean, message: string, fix?: string }`
53+
- `LintSummary`
54+
- `{ checks: LintCheckResult[], hasRequiredFailures: boolean, warningCount: number }`
55+
- Data flow between components
56+
- Parse args -> normalize feature -> run applicable checks -> collect results -> render terminal or JSON output -> return exit code.
57+
58+
## API Design
59+
**How do components communicate?**
60+
61+
- External APIs (if applicable)
62+
- CLI invocations:
63+
- `ai-devkit lint`
64+
- `ai-devkit lint --feature <name>`
65+
- `ai-devkit lint --feature <name> --json`
66+
- Internal interfaces
67+
- `runLint(options): Promise<number>`
68+
- `checkBaseDocs(cwd): Promise<LintCheckResult[]>`
69+
- `checkFeatureDocs(cwd, target): Promise<LintCheckResult[]>`
70+
- `checkFeatureWorktree(cwd, target): Promise<LintCheckResult[]>`
71+
- `renderLintOutput(summary, options): void`
72+
- Request/response formats
73+
- Input: CLI flags and current working directory.
74+
- Output:
75+
- Default: human-readable checklist and summary.
76+
- `--json`: structured JSON object for CI parsing (checks, counts, normalized feature, pass/fail state).
77+
- Exit code policy:
78+
- `0`: no required failures.
79+
- `1`: one or more required failures.
80+
- Warnings (including missing dedicated worktree) do not change exit code when required checks pass.
81+
- Authentication/authorization approach
82+
- Read-only operations only (filesystem + git metadata queries).
83+
84+
## Component Breakdown
85+
**What are the major building blocks?**
86+
87+
- Frontend components (if applicable)
88+
- Terminal output formatter using existing CLI conventions.
89+
- JSON formatter for machine-readable mode.
90+
- Backend services/modules
91+
- `commands/lint` command entry.
92+
- `services/lint` for composable checks.
93+
- `utils/feature-name` normalization utility.
94+
- `utils/git` helpers for worktree checks.
95+
- Database/storage layer
96+
- None.
97+
- Third-party integrations
98+
- Local git executable.
99+
100+
## Design Decisions
101+
**Why did we choose this approach?**
102+
103+
- Key architectural decisions and trade-offs
104+
- Re-implement shell checks in TypeScript while keeping output semantics:
105+
- Pros: testable, reusable, cross-command integration.
106+
- Cons: initial duplication until script is retired/repointed.
107+
- Classify checks as required vs warning:
108+
- Pros: keeps lifecycle gating strict for missing docs while allowing advisory worktree guidance.
109+
- Cons: users may ignore warnings if not enforced in team policy.
110+
- Normalize feature names automatically:
111+
- Pros: better UX (`foo` and `feature-foo` both accepted).
112+
- Cons: requires clear messaging of normalized value.
113+
- Include `--json` output in v1:
114+
- Pros: CI-friendly parsing and automated reporting.
115+
- Cons: requires stable output schema maintenance.
116+
- Alternatives considered
117+
- Keep shell script only and wrap it from CLI:
118+
- Rejected due to weaker cross-platform consistency and lower unit-test coverage.
119+
- Hard-fail when dedicated worktree is missing:
120+
- Rejected; requirement is warning-only behavior for this condition.
121+
- Patterns and principles applied
122+
- Single-responsibility check modules.
123+
- Deterministic output for CI and humans.
124+
- Collect-all-results reporting to surface all issues in one run.
125+
126+
## Non-Functional Requirements
127+
**How should the system perform?**
128+
129+
- Performance targets
130+
- Complete typical checks in under 1 second on standard repositories.
131+
- Scalability considerations
132+
- Check implementation should be extensible for additional lifecycle validations later.
133+
- Security requirements
134+
- No file writes or mutations.
135+
- No network access required.
136+
- Reliability/availability needs
137+
- Command should gracefully handle missing git repo context and provide actionable fixes.

‎docs/ai/implementation/feature-lint-command.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
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+
- Environment setup steps
14+
- Configuration needed
15+
16+
## Code Structure
17+
**How is the code organized?**
18+
19+
- Directory structure
20+
- Module organization
21+
- Naming conventions
22+
23+
## Implementation Notes
24+
**Key technical details to remember:**
25+
26+
### Core Features
27+
- Feature 1: Implementation approach
28+
- Feature 2: Implementation approach
29+
- Feature 3: Implementation approach
30+
31+
### Patterns & Best Practices
32+
- Design patterns being used
33+
- Code style guidelines
34+
- Common utilities/helpers
35+
36+
## Integration Points
37+
**How do pieces connect?**
38+
39+
- API integration details
40+
- Database connections
41+
- Third-party service setup
42+
43+
## Error Handling
44+
**How do we handle failures?**
45+
46+
- Error handling strategy
47+
- Logging approach
48+
- Retry/fallback mechanisms
49+
50+
## Performance Considerations
51+
**How do we keep it fast?**
52+
53+
- Optimization strategies
54+
- Caching approach
55+
- Query optimization
56+
- Resource management
57+
58+
## Security Notes
59+
**What security measures are in place?**
60+
61+
- Authentication/authorization
62+
- Input validation
63+
- Data encryption
64+
- Secrets management
65+

‎docs/ai/planning/feature-lint-command.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
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: Lint requirements/design approved
13+
- [ ] Milestone 2: `ai-devkit lint` base + feature checks implemented
14+
- [ ] Milestone 3: Tests, docs, and rollout complete
15+
16+
## Task Breakdown
17+
**What specific work needs to be done?**
18+
19+
### Phase 1: Foundation
20+
- [ ] Task 1.1: Audit current CLI command registration and identify insertion point for `lint`
21+
- [ ] Task 1.2: Extract/reimplement `check-docs.sh` base and feature doc checks in TypeScript utilities
22+
- [ ] Task 1.3: Implement feature-name normalization utility (`foo` and `feature-foo` -> `foo`)
23+
- [ ] Task 1.4: Define shared lint result model and formatter (`ok/miss/warn`, remediation hints)
24+
25+
### Phase 2: Core Features
26+
- [ ] Task 2.1: Add `ai-devkit lint` command handler with base workspace checks
27+
- [ ] Task 2.2: Add `--feature <name>` mode with feature doc checks across all lifecycle phases
28+
- [ ] Task 2.3: Add git checks for `feature-<name>` branch/worktree presence and mapping
29+
- [ ] Task 2.4: Ensure proper exit codes and summary output for CI compatibility
30+
31+
### Phase 3: Integration & Polish
32+
- [ ] Task 3.1: Update help text and README command documentation
33+
- [ ] Task 3.2: Decide whether to keep `skills/dev-lifecycle/scripts/check-docs.sh` as wrapper or migrate references to `ai-devkit lint`
34+
- [ ] Task 3.3: Add actionable remediation guidance in failures (`npx ai-devkit init`, worktree creation command)
35+
- [ ] Task 3.4: Validate behavior against existing lifecycle docs and feature naming conventions
36+
37+
### Phase 4: Validation
38+
- [ ] Task 4.1: Unit tests for base docs checks and feature docs checks
39+
- [ ] Task 4.2: Unit tests for feature normalization and git/worktree validation logic
40+
- [ ] Task 4.3: Integration tests for CLI exit codes and terminal output
41+
- [ ] Task 4.4: Manual verification on repositories with and without required docs/worktrees
42+
43+
## Dependencies
44+
**What needs to happen in what order?**
45+
46+
- Task dependencies and blockers
47+
- Command registration and result model must be in place before integration tests.
48+
- Feature-name normalization should be implemented before feature doc and git checks.
49+
- Git check module should be stable before finalizing remediation messages.
50+
- External dependencies (APIs, services, etc.)
51+
- Local git executable availability for feature-level checks.
52+
- Team/resource dependencies
53+
- Maintainer review for lifecycle workflow compatibility and naming conventions.
54+
55+
## Timeline & Estimates
56+
**When will things be done?**
57+
58+
- Estimated effort per task/phase
59+
- Phase 1: 0.5-1 day
60+
- Phase 2: 1-1.5 days
61+
- Phase 3: 0.5 day
62+
- Phase 4: 0.5-1 day
63+
- Target dates for milestones
64+
- Milestone 1: day 1
65+
- Milestone 2: day 2-3
66+
- Milestone 3: day 3-4
67+
- Buffer for unknowns
68+
- +20% for git/worktree edge-case handling and cross-platform output differences
69+
70+
## Risks & Mitigation
71+
**What could go wrong?**
72+
73+
- Technical risks
74+
- Git worktree detection may vary by repo state and user flow.
75+
- Divergence between shell script and new TypeScript checks can cause inconsistent behavior.
76+
- Resource risks
77+
- Limited test coverage for unusual git/worktree layouts.
78+
- Dependency risks
79+
- Existing scripts or docs may still assume `check-docs.sh` behavior/output.
80+
- Mitigation strategies
81+
- Add fixture-based tests for multiple git states.
82+
- Keep output mapping close to existing `check-docs.sh` semantics initially.
83+
- Update docs and scripts in same change to avoid workflow drift.
84+
85+
## Resources Needed
86+
**What do we need to succeed?**
87+
88+
- Team members and roles
89+
- CLI implementer and reviewer
90+
- Tools and services
91+
- Existing TypeScript unit/integration test tooling
92+
- Infrastructure
93+
- Local git repo fixtures for worktree tests
94+
- Documentation/knowledge
95+
- Dev-lifecycle skill conventions and existing `check-docs.sh` behavior

0 commit comments

Comments
 (0)