203 changed files with 24277 additions and 11796 deletions
@ -0,0 +1,151 @@ |
|||
# .cursor Rules Organization |
|||
|
|||
This directory contains all the rules and guidelines for AI assistants working |
|||
with the TimeSafari project. |
|||
|
|||
## Directory Structure |
|||
|
|||
### **`core/`** - Core Principles and Context |
|||
|
|||
Core rules that apply to all AI interactions and provide fundamental context. |
|||
|
|||
- **`base_context.mdc`** - Human competence first principles and interaction guidelines |
|||
- **`harbor_pilot_universal.mdc`** - Technical guide creation and investigation rules |
|||
- **`less_complex.mdc`** - Minimalist solution principle and complexity guidelines |
|||
|
|||
### **`development/`** - Development Practices and Standards |
|||
|
|||
Rules for software development, coding standards, and development workflows. |
|||
|
|||
- **`software_development.mdc`** - Core development principles and evidence requirements |
|||
- **`type_safety_guide.mdc`** - TypeScript type safety guidelines and best practices |
|||
- **`development_guide.mdc`** - Development environment setup and standards |
|||
- **`logging_standards.mdc`** - Logging implementation standards and rules |
|||
- **`logging_migration.mdc`** - Migration from console.* to structured logging |
|||
- **`time.mdc`** - Time handling principles and UTC standards |
|||
- **`time_examples.mdc`** - Practical time implementation examples |
|||
- **`time_implementation.mdc`** - Detailed time implementation guidelines |
|||
- **`realistic_time_estimation.mdc`** - Time estimation framework and principles |
|||
- **`planning_examples.mdc`** - Planning examples and best practices |
|||
- **`complexity_assessment.mdc`** - Complexity evaluation and assessment |
|||
- **`dependency_management.mdc`** - Dependency management and version control |
|||
- **`asset_configuration.mdc`** - Asset configuration and build integration |
|||
- **`research_diagnostic.mdc`** - Research and investigation workflows |
|||
- **`investigation_report_example.mdc`** - Investigation report templates and examples |
|||
- **`historical_comment_management.mdc`** - Historical comment transformation rules |
|||
- **`historical_comment_patterns.mdc`** - Comment transformation patterns and examples |
|||
|
|||
### **`architecture/`** - Architecture and Design Patterns |
|||
|
|||
Rules for architectural decisions, patterns, and system design. |
|||
|
|||
- **`build_architecture_guard.mdc`** - Build system protection and change levels |
|||
- **`build_validation.mdc`** - Build validation procedures and testing |
|||
- **`build_testing.mdc`** - Build testing requirements and feedback collection |
|||
|
|||
### **`app/`** - Application-Specific Rules |
|||
|
|||
Rules specific to the TimeSafari application and its architecture. |
|||
|
|||
- **`timesafari.mdc`** - Core application context and principles |
|||
- **`timesafari_platforms.mdc`** - Platform-specific implementation guidelines |
|||
- **`timesafari_development.mdc`** - TimeSafari development workflow |
|||
- **`architectural_decision_record.mdc`** - ADR creation and management |
|||
- **`architectural_implementation.mdc`** - Architecture implementation guidelines |
|||
- **`architectural_patterns.mdc`** - Architectural patterns and examples |
|||
- **`architectural_examples.mdc`** - Architecture examples and testing |
|||
|
|||
### **`database/`** - Database and Data Management |
|||
|
|||
Rules for database operations, migrations, and data handling. |
|||
|
|||
- **`absurd-sql.mdc`** - Absurd SQL implementation and worker thread setup |
|||
- **`legacy_dexie.mdc`** - Legacy Dexie migration guidelines |
|||
|
|||
### **`workflow/`** - Process and Workflow Management |
|||
|
|||
Rules for development workflows, version control, and process management. |
|||
|
|||
- **`version_control.mdc`** - Version control principles and commit guidelines |
|||
- **`version_sync.mdc`** - Version synchronization and changelog management |
|||
- **`commit_messages.mdc`** - Commit message format and conventions |
|||
|
|||
### **`features/** - Feature-Specific Implementations |
|||
|
|||
Rules for implementing specific features across platforms. |
|||
|
|||
- **`camera-implementation.mdc`** - Camera feature implementation overview |
|||
- **`camera_technical.mdc`** - Technical camera implementation details |
|||
- **`camera_platforms.mdc`** - Platform-specific camera implementation |
|||
|
|||
### **`docs/`** - Documentation Standards |
|||
|
|||
Rules for creating and maintaining documentation. |
|||
|
|||
- **`markdown_core.mdc`** - Core markdown formatting standards |
|||
- **`markdown_templates.mdc`** - Document templates and examples |
|||
- **`markdown_workflow.mdc`** - Markdown validation and workflow |
|||
- **`documentation.mdc`** - Documentation generation principles |
|||
- **`meta_rule_usage_guide.md`** - How to use meta-rules in practice |
|||
|
|||
### **`templates/`** - Templates and Examples |
|||
|
|||
Template files and examples for various documentation types. |
|||
|
|||
- **`adr_template.mdc`** - Architectural Decision Record template |
|||
|
|||
### **Meta-Rules** - Workflow Bundling |
|||
|
|||
High-level meta-rules that bundle related sub-rules for specific workflows. |
|||
|
|||
- **`meta_core_always_on.mdc`** - Core rules that apply to every single prompt |
|||
- **`meta_documentation.mdc`** - Documentation writing and education workflow |
|||
- **`meta_feature_planning.mdc`** - Feature planning workflow bundling |
|||
- **`meta_bug_diagnosis.mdc`** - Bug investigation workflow bundling |
|||
- **`meta_bug_fixing.mdc`** - Bug fix implementation workflow bundling |
|||
- **`meta_feature_implementation.mdc`** - Feature implementation workflow bundling |
|||
|
|||
## Usage Guidelines |
|||
|
|||
1. **Always-On Rules**: Start with `meta_core_always_on.mdc` for every |
|||
single prompt |
|||
2. **Core Rules**: Always apply rules from `core/` directory |
|||
3. **Context-Specific**: Use rules from appropriate subdirectories based on |
|||
your task |
|||
4. **Meta-Rules**: Use workflow-specific meta-rules for specialized tasks |
|||
- **Documentation**: Use `meta_documentation.mdc` for all documentation work |
|||
- **Getting Started**: See `docs/meta_rule_usage_guide.md` for comprehensive usage instructions |
|||
5. **Cross-References**: All files contain updated cross-references to |
|||
reflect the new structure |
|||
6. **Validation**: All files pass markdown validation and maintain |
|||
consistent formatting |
|||
|
|||
## Benefits of New Organization |
|||
|
|||
1. **Logical grouping** - Related rules are now co-located |
|||
2. **Easier navigation** - Developers can quickly find relevant rules |
|||
3. **Better maintainability** - Clear separation of concerns |
|||
4. **Scalable structure** - Easy to add new rules in appropriate categories |
|||
5. **Consistent cross-references** - All file links updated and working |
|||
6. **Workflow bundling** - Meta-rules provide high-level workflow guidance |
|||
7. **Feedback integration** - Built-in feedback mechanisms for continuous improvement |
|||
8. **Educational focus** - Documentation emphasizes human competence over technical description |
|||
|
|||
## File Naming Convention |
|||
|
|||
- **Lowercase with underscores**: `file_name.mdc` |
|||
- **Descriptive names**: Names clearly indicate the rule's purpose |
|||
- **Consistent extensions**: All files use `.mdc` extension |
|||
|
|||
## Maintenance |
|||
|
|||
- **Cross-references**: Update when moving files between directories |
|||
- **Markdown validation**: Run `npm run markdown:check` after any changes |
|||
- **Organization**: Keep related rules in appropriate subdirectories |
|||
- **Documentation**: Update this README when adding new rules or directories |
|||
|
|||
--- |
|||
|
|||
**Status**: Active organization structure |
|||
**Last Updated**: 2025-08-21 |
|||
**Maintainer**: Development team |
@ -0,0 +1,246 @@ |
|||
# Time Safari Architecture — Examples and Testing |
|||
|
|||
> **Agent role**: Reference this file for architectural examples and |
|||
testing patterns when working with TimeSafari architecture. |
|||
|
|||
## Error Handling Patterns |
|||
|
|||
### Global Error Handler |
|||
|
|||
```typescript |
|||
|
|||
// main.ts |
|||
app.config.errorHandler = (err, instance, info) => { |
|||
const componentName = instance?.$options?.name || 'Unknown'; |
|||
logger.error(`[${componentName}] Vue error`, err, info); |
|||
}; |
|||
|
|||
window.addEventListener('unhandledrejection', (event) => { |
|||
logger.error('[Global] Unhandled promise rejection', event.reason); |
|||
}); |
|||
|
|||
``` |
|||
|
|||
### Platform-Specific Error Wrapping |
|||
|
|||
```typescript |
|||
|
|||
// services/platforms/CapacitorPlatformService.ts |
|||
export class CapacitorPlatformService { |
|||
async getFileContents(path: string): Promise<string> { |
|||
try { |
|||
const result = await Filesystem.readFile({ |
|||
path: path, |
|||
encoding: 'utf8' |
|||
}); |
|||
return result.data; |
|||
} catch (error) { |
|||
logger.error('[Capacitor API Error] Failed to read file', error, path); |
|||
throw new Error(`Failed to read file: ${path}`); |
|||
} |
|||
} |
|||
} |
|||
|
|||
``` |
|||
|
|||
## Testing Patterns |
|||
|
|||
### Platform-Specific Test Skipping |
|||
|
|||
```typescript |
|||
|
|||
// tests/QRScanner.test.ts |
|||
describe('QRScanner Service', () => { |
|||
test('should start scanning on web', async () => { |
|||
test.skip(process.env.VITE_PLATFORM !== 'web', 'Web-only test'); |
|||
|
|||
const scanner = new WebInlineQRScanner(); |
|||
await scanner.startScanning(); |
|||
// Assert scanning started |
|||
}); |
|||
|
|||
test('should start scanning on mobile', async () => { |
|||
test.skip(process.env.VITE_PLATFORM !== 'capacitor', 'Mobile-only test'); |
|||
|
|||
const scanner = new CapacitorQRScanner(); |
|||
await scanner.startScanning(); |
|||
// Assert scanning started |
|||
}); |
|||
}); |
|||
|
|||
``` |
|||
|
|||
### Mock Service Testing |
|||
|
|||
```typescript |
|||
|
|||
// tests/mocks/QRScannerMock.ts |
|||
export class QRScannerMock implements QRScannerService { |
|||
private isScanning = false; |
|||
private listeners: Map<string, Function[]> = new Map(); |
|||
|
|||
async startScanning(): Promise<void> { |
|||
this.isScanning = true; |
|||
this.emit('scanningStarted'); |
|||
} |
|||
|
|||
async stopScanning(): Promise<void> { |
|||
this.isScanning = false; |
|||
this.emit('scanningStopped'); |
|||
} |
|||
|
|||
addListener(event: string, callback: Function): void { |
|||
if (!this.listeners.has(event)) { |
|||
this.listeners.set(event, []); |
|||
} |
|||
this.listeners.get(event)!.push(callback); |
|||
} |
|||
|
|||
removeListener(event: string, callback: Function): void { |
|||
const callbacks = this.listeners.get(event); |
|||
if (callbacks) { |
|||
const index = callbacks.indexOf(callback); |
|||
if (index > -1) { |
|||
callbacks.splice(index, 1); |
|||
} |
|||
} |
|||
} |
|||
|
|||
private emit(event: string, ...args: any[]): void { |
|||
const callbacks = this.listeners.get(event); |
|||
if (callbacks) { |
|||
callbacks.forEach(callback => callback(...args)); |
|||
} |
|||
} |
|||
|
|||
getScanningState(): boolean { |
|||
return this.isScanning; |
|||
} |
|||
} |
|||
|
|||
``` |
|||
|
|||
## Integration Examples |
|||
|
|||
### Service Composition |
|||
|
|||
```typescript |
|||
|
|||
// services/QRScannerService.ts |
|||
export class QRScannerService { |
|||
constructor( |
|||
private platformService: PlatformService, |
|||
private notificationService: NotificationService |
|||
) {} |
|||
|
|||
async startScanning(): Promise<void> { |
|||
try { |
|||
await this.platformService.startCamera(); |
|||
this.notificationService.show('Camera started'); |
|||
} catch (error) { |
|||
this.notificationService.showError('Failed to start camera'); |
|||
throw error; |
|||
} |
|||
} |
|||
} |
|||
|
|||
``` |
|||
|
|||
### Component Integration |
|||
|
|||
```typescript |
|||
|
|||
// components/QRScannerDialog.vue |
|||
export default class QRScannerDialog extends Vue { |
|||
@Inject() private qrScannerService!: QRScannerService; |
|||
|
|||
async mounted() { |
|||
try { |
|||
await this.qrScannerService.startScanning(); |
|||
} catch (error) { |
|||
this.$notify.error('Failed to start scanner'); |
|||
} |
|||
} |
|||
|
|||
beforeDestroy() { |
|||
this.qrScannerService.stopScanning(); |
|||
} |
|||
} |
|||
|
|||
``` |
|||
|
|||
## Best Practices |
|||
|
|||
### Service Design |
|||
|
|||
- Keep services focused and single-purpose |
|||
|
|||
- Use dependency injection for service composition |
|||
|
|||
- Implement proper error handling and logging |
|||
|
|||
- Provide clear interfaces and contracts |
|||
|
|||
### Testing Strategy |
|||
|
|||
- Test platform-specific behavior separately |
|||
|
|||
- Use mocks for external dependencies |
|||
|
|||
- Test error conditions and edge cases |
|||
|
|||
- Validate service contracts and interfaces |
|||
|
|||
### Error Handling |
|||
|
|||
- Log errors with appropriate context |
|||
|
|||
- Provide user-friendly error messages |
|||
|
|||
- Implement graceful degradation |
|||
|
|||
- Handle platform-specific error scenarios |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/app/architectural_decision_record.mdc` for |
|||
|
|||
core architecture principles |
|||
|
|||
- `.cursor/rules/app/architectural_implementation.mdc` for |
|||
|
|||
implementation details |
|||
|
|||
- `.cursor/rules/app/architectural_patterns.mdc` for core patterns |
|||
|
|||
**Status**: Active examples and testing guide |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: architectural_patterns.mdc |
|||
**Stakeholders**: Development team, Testing team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Architectural Examples |
|||
|
|||
- [ ] **Pattern Selection**: Choose appropriate architectural pattern for the use |
|||
case |
|||
- [ ] **Service Design**: Plan service structure and dependencies |
|||
- [ ] **Testing Strategy**: Plan testing approach for the example |
|||
- [ ] **Error Handling**: Plan error handling and logging strategy |
|||
|
|||
### During Architectural Examples |
|||
|
|||
- [ ] **Service Implementation**: Implement focused, single-purpose services |
|||
- [ ] **Dependency Injection**: Use proper dependency injection patterns |
|||
- [ ] **Error Handling**: Implement proper error handling and logging |
|||
- [ ] **Interface Design**: Provide clear interfaces and contracts |
|||
|
|||
### After Architectural Examples |
|||
|
|||
- [ ] **Testing Execution**: Test platform-specific behavior separately |
|||
- [ ] **Service Validation**: Validate service contracts and interfaces |
|||
- [ ] **Error Testing**: Test error conditions and edge cases |
|||
- [ ] **Documentation**: Update architectural examples documentation |
@ -0,0 +1,139 @@ |
|||
# Time Safari Architecture — Implementation Details |
|||
|
|||
> **Agent role**: Reference this file for detailed implementation details when |
|||
working with TimeSafari architecture implementation. |
|||
|
|||
## Error Handling |
|||
|
|||
- Global Vue error handler → logs with component name. |
|||
|
|||
- Platform-specific wrappers log API errors with platform prefix |
|||
|
|||
(`[Capacitor API Error]`, etc). |
|||
|
|||
- Use structured logging (not `console.log`). |
|||
|
|||
## Best Practices |
|||
|
|||
- Keep platform code **isolated** in `platforms/`. |
|||
|
|||
- Always define a **shared interface** first. |
|||
|
|||
- Use feature detection, not platform detection, when possible. |
|||
|
|||
- Dependency injection for services → improves testability. |
|||
|
|||
- Maintain **Competence Hooks** in PRs (2–3 prompts for dev |
|||
|
|||
discussion). |
|||
|
|||
## Dependency Management |
|||
|
|||
- Key deps: `@capacitor/core`, `electron`, `vue`. |
|||
|
|||
- Use conditional `import()` for platform-specific libs. |
|||
|
|||
## Security Considerations |
|||
|
|||
- **Permissions**: Always check + request gracefully. |
|||
|
|||
- **Storage**: Secure storage for sensitive data; encrypt when possible. |
|||
|
|||
- **Audits**: Schedule quarterly security reviews. |
|||
|
|||
## ADR Process |
|||
|
|||
- All major architecture choices → log in `doc/adr/`. |
|||
|
|||
- Use ADR template with Context, Decision, Consequences, Status. |
|||
|
|||
- Link related ADRs in PR descriptions. |
|||
|
|||
> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min |
|||
> design sync for discussion, not just async review. |
|||
|
|||
## Collaboration Hooks |
|||
|
|||
- **QR features**: Sync with Security before merging → permissions & |
|||
|
|||
privacy. |
|||
|
|||
- **New platform builds**: Demo in team meeting → confirm UX |
|||
|
|||
differences. |
|||
|
|||
- **Critical ADRs**: Present in guild or architecture review. |
|||
|
|||
## Testing Implementation |
|||
|
|||
- **Unit tests** for services. |
|||
|
|||
- **Playwright** for Web + Capacitor: |
|||
|
|||
- `playwright.config-local.ts` includes web + Pixel 5. |
|||
|
|||
- **Electron tests**: add `spectron` or Playwright-Electron. |
|||
|
|||
- Mark tests with platform tags: |
|||
|
|||
```ts |
|||
|
|||
test.skip(!process.env.MOBILE_TEST, "Mobile-only test"); |
|||
|
|||
``` |
|||
|
|||
> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15 |
|||
> min) with QA to align on coverage and flaky test risks. |
|||
|
|||
## Self-Check |
|||
|
|||
- [ ] Does this feature implement a shared interface? |
|||
|
|||
- [ ] Are fallbacks + errors handled gracefully? |
|||
|
|||
- [ ] Have relevant ADRs been updated/linked? |
|||
|
|||
- [ ] Did I add competence hooks or prompts for the team? |
|||
|
|||
- [ ] Was human interaction (sync/review/demo) scheduled? |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/app/architectural_decision_record.mdc` for |
|||
|
|||
core architecture principles |
|||
|
|||
- `.cursor/rules/app/architectural_patterns.mdc` for architectural patterns and |
|||
|
|||
examples |
|||
|
|||
**Status**: Active implementation guidelines |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: architectural_decision_record.mdc |
|||
**Stakeholders**: Development team, Architecture team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Architectural Implementation |
|||
|
|||
- [ ] **Interface Review**: Verify feature implements shared interface |
|||
- [ ] **ADR Review**: Check if ADR is required for major changes |
|||
- [ ] **Security Assessment**: Assess security implications for QR features |
|||
- [ ] **Platform Planning**: Plan platform-specific implementation details |
|||
|
|||
### During Architectural Implementation |
|||
|
|||
- [ ] **Interface Implementation**: Implement shared interfaces consistently |
|||
- [ ] **Error Handling**: Implement graceful fallbacks and error handling |
|||
- [ ] **Testing Strategy**: Plan unit tests for services and E2E tests |
|||
- [ ] **Human Interaction**: Schedule syncs/reviews/demos as needed |
|||
|
|||
### After Architectural Implementation |
|||
|
|||
- [ ] **Interface Validation**: Verify shared interfaces are properly implemented |
|||
- [ ] **Testing Execution**: Run unit tests and platform-specific tests |
|||
- [ ] **ADR Updates**: Update relevant ADRs and link in PR descriptions |
|||
- [ ] **Team Communication**: Share implementation results with team |
@ -0,0 +1,214 @@ |
|||
# Time Safari Architecture — Patterns and Examples |
|||
|
|||
> **Agent role**: Reference this file for architectural patterns and |
|||
> examples when working with TimeSafari architecture design. |
|||
|
|||
## Architectural Patterns |
|||
|
|||
### Factory Pattern Implementation |
|||
|
|||
```typescript |
|||
// PlatformServiceFactory.ts |
|||
export class PlatformServiceFactory { |
|||
private static instance: PlatformServiceFactory; |
|||
|
|||
static getInstance(): PlatformServiceFactory { |
|||
if (!PlatformServiceFactory.instance) { |
|||
PlatformServiceFactory.instance = new PlatformServiceFactory(); |
|||
} |
|||
return PlatformServiceFactory.instance; |
|||
} |
|||
|
|||
getQRScannerService(): QRScannerService { |
|||
const platform = process.env.VITE_PLATFORM; |
|||
|
|||
switch (platform) { |
|||
case 'web': |
|||
return new WebInlineQRScanner(); |
|||
case 'capacitor': |
|||
return new CapacitorQRScanner(); |
|||
case 'electron': |
|||
return new ElectronQRScanner(); |
|||
default: |
|||
throw new Error(`Unsupported platform: ${platform}`); |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Service Interface Definition |
|||
|
|||
```typescript |
|||
// interfaces/QRScannerService.ts |
|||
export interface QRScannerService { |
|||
startScanning(): Promise<void>; |
|||
stopScanning(): Promise<void>; |
|||
addListener(event: string, callback: Function): void; |
|||
removeListener(event: string, callback: Function): void; |
|||
} |
|||
``` |
|||
|
|||
### Platform-Specific Implementation |
|||
|
|||
```typescript |
|||
// services/QRScanner/WebInlineQRScanner.ts |
|||
export class WebInlineQRScanner implements QRScannerService { |
|||
private listeners: Map<string, Function[]> = new Map(); |
|||
|
|||
async startScanning(): Promise<void> { |
|||
// Web-specific implementation |
|||
const stream = await navigator.mediaDevices.getUserMedia({ video: true }); |
|||
// Process video stream for QR codes |
|||
} |
|||
|
|||
async stopScanning(): Promise<void> { |
|||
// Stop video stream |
|||
} |
|||
|
|||
addListener(event: string, callback: Function): void { |
|||
if (!this.listeners.has(event)) { |
|||
this.listeners.set(event, []); |
|||
} |
|||
this.listeners.get(event)!.push(callback); |
|||
} |
|||
|
|||
removeListener(event: string, callback: Function): void { |
|||
const callbacks = this.listeners.get(event); |
|||
if (callbacks) { |
|||
const index = callbacks.indexOf(callback); |
|||
if (index > -1) { |
|||
callbacks.splice(index, 1); |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Deep Linking Implementation |
|||
|
|||
### URL Format |
|||
|
|||
``` |
|||
timesafari://<route>[/<param>][?query=value] |
|||
``` |
|||
|
|||
### Web Implementation |
|||
|
|||
```typescript |
|||
// router/index.ts |
|||
router.beforeEach((to, from, next) => { |
|||
// Parse deep link parameters |
|||
if (to.query.deepLink) { |
|||
const deepLink = to.query.deepLink as string; |
|||
// Process deep link |
|||
handleDeepLink(deepLink); |
|||
} |
|||
next(); |
|||
}); |
|||
|
|||
function handleDeepLink(deepLink: string) { |
|||
// Parse and route deep link |
|||
const url = new URL(deepLink); |
|||
const route = url.pathname; |
|||
const params = url.searchParams; |
|||
|
|||
// Navigate to appropriate route |
|||
router.push({ name: route, query: Object.fromEntries(params) }); |
|||
} |
|||
``` |
|||
|
|||
### Capacitor Implementation |
|||
|
|||
```typescript |
|||
// main.capacitor.ts |
|||
import { App } from '@capacitor/app'; |
|||
|
|||
App.addListener('appUrlOpen', (data) => { |
|||
const url = data.url; |
|||
// Parse deep link and navigate |
|||
handleDeepLink(url); |
|||
}); |
|||
``` |
|||
|
|||
## Platform Detection |
|||
|
|||
### Feature Detection vs Platform Detection |
|||
|
|||
```typescript |
|||
// ✅ Good: Feature detection |
|||
function hasCameraAccess(): boolean { |
|||
return 'mediaDevices' in navigator && |
|||
'getUserMedia' in navigator.mediaDevices; |
|||
} |
|||
|
|||
// ❌ Bad: Platform detection |
|||
function isWeb(): boolean { |
|||
return process.env.VITE_PLATFORM === 'web'; |
|||
} |
|||
``` |
|||
|
|||
### Conditional Imports |
|||
|
|||
```typescript |
|||
// services/platforms/index.ts |
|||
export async function getPlatformService() { |
|||
const platform = process.env.VITE_PLATFORM; |
|||
|
|||
switch (platform) { |
|||
case 'capacitor': |
|||
const { CapacitorPlatformService } = |
|||
await import('./CapacitorPlatformService'); |
|||
return new CapacitorPlatformService(); |
|||
case 'electron': |
|||
const { ElectronPlatformService } = |
|||
await import('./ElectronPlatformService'); |
|||
return new ElectronPlatformService(); |
|||
default: |
|||
const { WebPlatformService } = |
|||
await import('./WebPlatformService'); |
|||
return new WebPlatformService(); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/app/architectural_decision_record.mdc` for core |
|||
architecture principles |
|||
- `.cursor/rules/app/architectural_implementation.mdc` for |
|||
implementation details |
|||
- `.cursor/rules/app/architectural_examples.mdc` for examples and |
|||
testing patterns |
|||
|
|||
**Status**: Active patterns and examples |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: architectural_decision_record.mdc, |
|||
architectural_implementation.mdc |
|||
**Stakeholders**: Development team, Architecture team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Architectural Patterns |
|||
|
|||
- [ ] **Pattern Selection**: Choose appropriate architectural pattern for the use |
|||
case |
|||
- [ ] **Platform Analysis**: Identify platform-specific requirements |
|||
- [ ] **Service Planning**: Plan service structure and dependencies |
|||
- [ ] **Testing Strategy**: Plan testing approach for the pattern |
|||
|
|||
### During Architectural Patterns |
|||
|
|||
- [ ] **Pattern Implementation**: Implement chosen architectural pattern |
|||
- [ ] **Platform Abstraction**: Use platform abstraction layers appropriately |
|||
- [ ] **Service Composition**: Compose services using dependency injection |
|||
- [ ] **Interface Design**: Provide clear interfaces and contracts |
|||
|
|||
### After Architectural Patterns |
|||
|
|||
- [ ] **Pattern Validation**: Verify pattern is implemented correctly |
|||
- [ ] **Platform Testing**: Test across all target platforms |
|||
- [ ] **Service Testing**: Test service composition and dependencies |
|||
- [ ] **Documentation**: Update architectural patterns documentation |
@ -1,316 +1,173 @@ |
|||
--- |
|||
description: |
|||
globs: |
|||
alwaysApply: true |
|||
alwaysApply: false |
|||
--- |
|||
# Time Safari Context |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-19 |
|||
**Status**: 🎯 **ACTIVE** - Core application context |
|||
|
|||
## Project Overview |
|||
|
|||
Time Safari is an application designed to foster community building through gifts, |
|||
gratitude, and collaborative projects. The app should make it extremely easy and |
|||
intuitive for users of any age and capability to recognize contributions, build |
|||
trust networks, and organize collective action. It is built on services that |
|||
preserve privacy and data sovereignty. |
|||
Time Safari is an application designed to foster community building through |
|||
gifts, gratitude, and collaborative projects. The app makes it easy and |
|||
intuitive for users of any age and capability to recognize contributions, |
|||
build trust networks, and organize collective action. It is built on services |
|||
that preserve privacy and data sovereignty. |
|||
|
|||
The ultimate goals of Time Safari are two-fold: |
|||
## Core Goals |
|||
|
|||
1. **Connect** Make it easy, rewarding, and non-threatening for people to |
|||
connect with others who have similar interests, and to initiate activities |
|||
together. This helps people accomplish and learn from other individuals in |
|||
less-structured environments; moreover, it helps them discover who they want |
|||
to continue to support and with whom they want to maintain relationships. |
|||
1. **Connect**: Make it easy, rewarding, and non-threatening for people to |
|||
|
|||
2. **Reveal** Widely advertise the great support and rewards that are being |
|||
given and accepted freely, especially non-monetary ones. Using visuals and text, |
|||
display the kind of impact that gifts are making in the lives of others. Also |
|||
show useful and engaging reports of project statistics and personal accomplishments. |
|||
connect with others who have similar interests, and to initiate activities |
|||
together. |
|||
|
|||
2. **Reveal**: Widely advertise the great support and rewards that are being |
|||
|
|||
## Core Approaches |
|||
given and accepted freely, especially non-monetary ones, showing the impact |
|||
gifts make in people's lives. |
|||
|
|||
Time Safari should help everyday users build meaningful connections and organize |
|||
collective efforts by: |
|||
## Technical Foundation |
|||
|
|||
1. **Recognizing Contributions**: Creating permanent, verifiable records of gifts |
|||
and contributions people give to each other and their communities. |
|||
### Architecture |
|||
|
|||
2. **Facilitating Collaboration**: Making it ridiculously easy for people to ask |
|||
for or propose help on projects and interests that matter to them. |
|||
- **Privacy-preserving claims architecture** via endorser.ch |
|||
|
|||
3. **Building Trust Networks**: Enabling users to maintain their network and activity |
|||
visibility. Developing reputation through verified contributions and references, |
|||
which can be selectively shown to others outside the network. |
|||
- **Decentralized Identifiers (DIDs)**: User identities based on |
|||
|
|||
4. **Preserving Privacy**: Ensuring personal identifiers are only shared with |
|||
explicitly authorized contacts, allowing private individuals including children |
|||
to participate safely. |
|||
public/private key pairs stored on devices |
|||
|
|||
5. **Engaging Content**: Displaying people's records in compelling stories, and |
|||
highlighting those projects that are lifting people's lives long-term, both in |
|||
physical support and in emotional-spiritual-creative thriving. |
|||
- **Cryptographic Verification**: All claims and confirmations are |
|||
|
|||
cryptographically signed |
|||
|
|||
## Technical Foundation |
|||
- **User-Controlled Visibility**: Users explicitly control who can see their |
|||
|
|||
This application is built on a privacy-preserving claims architecture (via |
|||
endorser.ch) with these key characteristics: |
|||
identifiers and data |
|||
|
|||
- **Decentralized Identifiers (DIDs)**: User identities are based on public/private |
|||
key pairs stored on their devices |
|||
- **Cryptographic Verification**: All claims and confirmations are |
|||
cryptographically signed |
|||
- **User-Controlled Visibility**: Users explicitly control who can see their |
|||
identifiers and data |
|||
- **Merkle-Chained Claims**: Claims are cryptographically chained for verification |
|||
and integrity |
|||
- **Native and Web App**: Works on Capacitor (iOS, Android), Desktop (Electron |
|||
and CEFPython), and web browsers |
|||
- **Cross-Platform**: Web (PWA), Mobile (Capacitor), Desktop (Electron) |
|||
|
|||
### Current Database State |
|||
|
|||
- **Database**: SQLite via Absurd SQL (browser) and native SQLite |
|||
|
|||
(mobile/desktop) |
|||
|
|||
- **Legacy Support**: IndexedDB (Dexie) for backward compatibility |
|||
|
|||
- **Status**: Modern database architecture fully implemented |
|||
|
|||
## User Journey |
|||
### Core Technologies |
|||
|
|||
The typical progression of usage follows these stages: |
|||
- **Frontend**: Vue 3 + TypeScript + vue-facing-decorator |
|||
|
|||
1. **Gratitude & Recognition**: Users begin by expressing and recording gratitude |
|||
for gifts received, building a foundation of acknowledgment. |
|||
- **Styling**: TailwindCSS |
|||
|
|||
2. **Project Proposals**: Users propose projects and ideas, reaching out to connect |
|||
with others who share similar interests. |
|||
- **Build**: Vite with platform-specific configs |
|||
|
|||
3. **Action Triggers**: Offers of help serve as triggers and motivations to execute |
|||
proposed projects, moving from ideas to action. |
|||
- **Testing**: Playwright E2E, Jest unit tests |
|||
|
|||
## Context for LLM Development |
|||
- **Database**: SQLite (Absurd SQL in browser), IndexedDB (legacy) |
|||
|
|||
When developing new functionality for Time Safari, consider these design principles: |
|||
- **State**: Pinia stores |
|||
|
|||
1. **Accessibility First**: Features should be usable by non-technical users with |
|||
minimal learning curve. |
|||
- **Platform Services**: Abstracted behind interfaces with factory pattern |
|||
|
|||
2. **Privacy by Design**: All features must respect user privacy and data sovereignty. |
|||
## Development Principles |
|||
|
|||
3. **Progressive Enhancement**: Core functionality should work across all devices, |
|||
with richer experiences where supported. |
|||
### Code Organization |
|||
|
|||
4. **Voluntary Collaboration**: The system should enable but never coerce participation. |
|||
- **Platform Services**: Abstract platform-specific code behind interfaces |
|||
|
|||
5. **Trust Building**: Features should help build verifiable trust between users. |
|||
- **Service Factory**: Use `PlatformServiceFactory` for platform selection |
|||
|
|||
6. **Network Effects**: Consider how features scale as more users join the platform. |
|||
- **Type Safety**: Strict TypeScript, no `any` types, use type guards |
|||
|
|||
7. **Low Resource Requirements**: The system should be lightweight enough to run |
|||
on inexpensive devices users already own. |
|||
- **Modern Architecture**: Use current platform service patterns |
|||
|
|||
## Use Cases to Support |
|||
### Architecture Patterns |
|||
|
|||
LLM development should focus on enhancing these key use cases: |
|||
- **Dependency Injection**: Services injected via mixins and factory pattern |
|||
|
|||
1. **Community Building**: Tools that help people find others with shared |
|||
interests and values. |
|||
- **Interface Segregation**: Small, focused interfaces over large ones |
|||
|
|||
2. **Project Coordination**: Features that make it easy to propose collaborative |
|||
projects and to submit suggestions and offers to existing ones. |
|||
- **Composition over Inheritance**: Prefer mixins and composition |
|||
|
|||
3. **Reputation Building**: Methods for users to showcase their contributions |
|||
and reliability, in contexts where they explicitly reveal that information. |
|||
- **Single Responsibility**: Each component/service has one clear purpose |
|||
|
|||
4. **Governance Experimentation**: Features that facilitate decision-making and |
|||
collective governance. |
|||
### Testing Strategy |
|||
|
|||
## Constraints |
|||
- **E2E**: Playwright for critical user journeys |
|||
|
|||
When developing new features, be mindful of these constraints: |
|||
- **Unit**: Jest with F.I.R.S.T. principles |
|||
|
|||
1. **Privacy Preservation**: User identifiers must remain private except when |
|||
explicitly shared. |
|||
- **Platform Coverage**: Web + Capacitor (Pixel 5) in CI |
|||
|
|||
2. **Platform Limitations**: Features must work within the constraints of the target |
|||
app platforms, while aiming to leverage the best platform technology available. |
|||
- **Quality Assurance**: Comprehensive testing and validation |
|||
|
|||
3. **Endorser API Limitations**: Backend features are constrained by the endorser.ch |
|||
API capabilities. |
|||
## Current Development Focus |
|||
|
|||
4. **Performance on Low-End Devices**: The application should remain performant |
|||
on older/simpler devices. |
|||
### Active Development |
|||
|
|||
5. **Offline-First When Possible**: Key functionality should work offline when feasible. |
|||
- **Feature Development**: Build new functionality using modern platform |
|||
|
|||
services |
|||
|
|||
- **Performance Optimization**: Improve app performance and user experience |
|||
|
|||
- **Platform Enhancement**: Leverage platform-specific capabilities |
|||
|
|||
- **Code Quality**: Maintain high standards and best practices |
|||
|
|||
### Development Metrics |
|||
|
|||
- **Code Quality**: High standards maintained across all platforms |
|||
|
|||
- **Performance**: Optimized for all target devices |
|||
|
|||
- **Testing**: Comprehensive coverage maintained |
|||
|
|||
- **User Experience**: Focus on intuitive, accessible interfaces |
|||
|
|||
--- |
|||
|
|||
## Project Technologies |
|||
**See also**: |
|||
|
|||
- Typescript using ES6 classes using vue-facing-decorator |
|||
- TailwindCSS |
|||
- Vite Build Tool |
|||
- Playwright E2E testing |
|||
- IndexDB |
|||
- Camera, Image uploads, QR Code reader, ... |
|||
- `.cursor/rules/app/timesafari_platforms.mdc` for platform-specific details |
|||
|
|||
## Mobile Features |
|||
- `.cursor/rules/app/timesafari_development.mdc` for |
|||
|
|||
- Deep Linking |
|||
- Local Notifications via a custom Capacitor plugin |
|||
development workflow details |
|||
|
|||
## Project Architecture |
|||
**Status**: Active application context |
|||
**Priority**: Critical |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: None |
|||
**Stakeholders**: Development team, Product team |
|||
|
|||
- The application must work on web browser, PWA (Progressive Web Application), |
|||
desktop via Electron, and mobile via Capacitor |
|||
- Building for each platform is managed via Vite |
|||
- **Dependencies**: Vue 3, TypeScript, SQLite, Capacitor, Electron |
|||
|
|||
## Core Development Principles |
|||
- **Stakeholders**: Development team, Product team |
|||
|
|||
### DRY development |
|||
## Model Implementation Checklist |
|||
|
|||
- **Code Reuse** |
|||
- Extract common functionality into utility functions |
|||
- Create reusable components for UI patterns |
|||
- Implement service classes for shared business logic |
|||
- Use mixins for cross-cutting concerns |
|||
- Leverage TypeScript interfaces for shared type definitions |
|||
### Before TimeSafari Development |
|||
|
|||
- **Component Patterns** |
|||
- Create base components for common UI elements |
|||
- Implement higher-order components for shared behavior |
|||
- Use slot patterns for flexible component composition |
|||
- Create composable services for business logic |
|||
- Implement factory patterns for component creation |
|||
- [ ] **Application Context**: Understand TimeSafari's community-building purpose |
|||
- [ ] **Platform Analysis**: Identify target platforms (web, mobile, desktop) |
|||
- [ ] **Architecture Review**: Review current platform service patterns |
|||
- [ ] **Testing Strategy**: Plan testing approach for all platforms |
|||
|
|||
- **State Management** |
|||
- Centralize state in Pinia stores |
|||
- Use computed properties for derived state |
|||
- Implement shared state selectors |
|||
- Create reusable state mutations |
|||
- Use action creators for common operations |
|||
### During TimeSafari Development |
|||
|
|||
- **Error Handling** |
|||
- Implement centralized error handling |
|||
- Create reusable error components |
|||
- Use error boundary components |
|||
- Implement consistent error logging |
|||
- Create error type definitions |
|||
- [ ] **Platform Services**: Use abstracted platform services via interfaces |
|||
- [ ] **Type Safety**: Implement strict TypeScript with type guards |
|||
- **Modern Architecture**: Follow current platform service patterns |
|||
- [ ] **Performance Focus**: Ensure performance on all target devices |
|||
|
|||
- **Type Definitions** |
|||
- Create shared interfaces for common data structures |
|||
- Use type aliases for complex types |
|||
- Implement generic types for reusable components |
|||
- Create utility types for common patterns |
|||
- Use discriminated unions for state management |
|||
### After TimeSafari Development |
|||
|
|||
- **API Integration** |
|||
- Create reusable API client classes |
|||
- Implement request/response interceptors |
|||
- Use consistent error handling patterns |
|||
- Create type-safe API endpoints |
|||
- Implement caching strategies |
|||
|
|||
- **Platform Services** |
|||
- Abstract platform-specific code behind interfaces |
|||
- Create platform-agnostic service layers |
|||
- Implement feature detection |
|||
- Use dependency injection for services |
|||
- Create service factories |
|||
|
|||
- **Testing** |
|||
- Create reusable test utilities |
|||
- Implement test factories |
|||
- Use shared test configurations |
|||
- Create reusable test helpers |
|||
- Implement consistent test patterns |
|||
- F.I.R.S.T. (for Unit Tests) |
|||
F – Fast |
|||
I – Independent |
|||
R – Repeatable |
|||
S – Self-validating |
|||
T – Timely |
|||
|
|||
### SOLID Principles |
|||
|
|||
- **Single Responsibility**: Each class/component should have only one reason to |
|||
change |
|||
- Components should focus on one specific feature (e.g., QR scanning, DID management) |
|||
- Services should handle one type of functionality (e.g., platform services, |
|||
crypto services) |
|||
- Utilities should provide focused helper functions |
|||
|
|||
- **Open/Closed**: Software entities should be open for extension but closed for |
|||
modification |
|||
- Use interfaces for service definitions |
|||
- Implement plugin architecture for platform-specific features |
|||
- Allow component behavior extension through props and events |
|||
|
|||
- **Liskov Substitution**: Objects should be replaceable with their subtypes |
|||
- Platform services should work consistently across web/mobile |
|||
- Authentication providers should be interchangeable |
|||
- Storage implementations should be swappable |
|||
|
|||
- **Interface Segregation**: Clients shouldn't depend on interfaces they don't use |
|||
- Break down large service interfaces into smaller, focused ones |
|||
- Component props should be minimal and purposeful |
|||
- Event emissions should be specific and targeted |
|||
|
|||
- **Dependency Inversion**: High-level modules shouldn't depend on low-level modules |
|||
- Use dependency injection for services |
|||
- Abstract platform-specific code behind interfaces |
|||
- Implement factory patterns for component creation |
|||
|
|||
### Law of Demeter |
|||
|
|||
- Components should only communicate with immediate dependencies |
|||
- Avoid chaining method calls (e.g., `this.service.getUser().getProfile().getName()`) |
|||
- Use mediator patterns for complex component interactions |
|||
- Implement facade patterns for subsystem access |
|||
- Keep component communication through defined events and props |
|||
|
|||
### Composition over Inheritance |
|||
|
|||
- Prefer building components through composition |
|||
- Use mixins for shared functionality |
|||
- Implement feature toggles through props |
|||
- Create higher-order components for common patterns |
|||
- Use service composition for complex features |
|||
|
|||
### Interface Segregation |
|||
|
|||
- Define clear interfaces for services |
|||
- Keep component APIs minimal and focused |
|||
- Split large interfaces into smaller, specific ones |
|||
- Use TypeScript interfaces for type definitions |
|||
- Implement role-based interfaces for different use cases |
|||
|
|||
### Fail Fast |
|||
|
|||
- Validate inputs early in the process |
|||
- Use TypeScript strict mode |
|||
- Implement comprehensive error handling |
|||
- Add runtime checks for critical operations |
|||
- Use assertions for development-time validation |
|||
|
|||
### Principle of Least Astonishment |
|||
|
|||
- Follow Vue.js conventions consistently |
|||
- Use familiar naming patterns |
|||
- Implement predictable component behaviors |
|||
- Maintain consistent error handling |
|||
- Keep UI interactions intuitive |
|||
|
|||
### Information Hiding |
|||
|
|||
- Encapsulate implementation details |
|||
- Use private class members |
|||
- Implement proper access modifiers |
|||
- Hide complex logic behind simple interfaces |
|||
- Use TypeScript's access modifiers effectively |
|||
|
|||
### Single Source of Truth |
|||
|
|||
- Use Pinia for state management |
|||
- Maintain one source for user data |
|||
- Centralize configuration management |
|||
- Use computed properties for derived state |
|||
- Implement proper state synchronization |
|||
|
|||
### Principle of Least Privilege |
|||
|
|||
- Implement proper access control |
|||
- Use minimal required permissions |
|||
- Follow privacy-by-design principles |
|||
- Restrict component access to necessary data |
|||
- Implement proper authentication/authorization |
|||
- [ ] **Cross-Platform Testing**: Test functionality across all platforms |
|||
- [ ] **Performance Validation**: Verify performance meets requirements |
|||
- [ ] **Code Quality**: Ensure high standards maintained |
|||
- [ ] **Documentation Update**: Update relevant documentation |
|||
|
@ -0,0 +1,174 @@ |
|||
# Time Safari Development — Workflow and Processes |
|||
|
|||
> **Agent role**: Reference this file for development workflow details when |
|||
working with TimeSafari development processes. |
|||
|
|||
## Development Workflow |
|||
|
|||
### Build Commands |
|||
|
|||
```bash |
|||
|
|||
# Web (development) |
|||
|
|||
npm run build:web |
|||
|
|||
# Mobile |
|||
|
|||
npm run build:capacitor |
|||
npm run build:native |
|||
|
|||
# Desktop |
|||
|
|||
npm run build:electron |
|||
npm run build:electron:appimage |
|||
npm run build:electron:deb |
|||
npm run build:electron:dmg |
|||
|
|||
``` |
|||
|
|||
### Testing Commands |
|||
|
|||
```bash |
|||
|
|||
# Web E2E |
|||
|
|||
npm run test:web |
|||
|
|||
# Mobile |
|||
|
|||
npm run test:mobile |
|||
npm run test:android |
|||
npm run test:ios |
|||
|
|||
# Type checking |
|||
|
|||
npm run type-check |
|||
npm run lint-fix |
|||
|
|||
``` |
|||
|
|||
## Development Principles |
|||
|
|||
### Code Organization |
|||
|
|||
- **Platform Services**: Abstract platform-specific code behind interfaces |
|||
|
|||
- **Service Factory**: Use `PlatformServiceFactory` for platform selection |
|||
|
|||
- **Type Safety**: Strict TypeScript, no `any` types, use type guards |
|||
|
|||
- **Modern Architecture**: Use current platform service patterns |
|||
|
|||
### Architecture Patterns |
|||
|
|||
- **Dependency Injection**: Services injected via mixins and factory pattern |
|||
|
|||
- **Interface Segregation**: Small, focused interfaces over large ones |
|||
|
|||
- **Composition over Inheritance**: Prefer mixins and composition |
|||
|
|||
- **Single Responsibility**: Each component/service has one clear purpose |
|||
|
|||
### Testing Strategy |
|||
|
|||
- **E2E**: Playwright for critical user journeys |
|||
|
|||
- **Unit**: Jest with F.I.R.S.T. principles |
|||
|
|||
- **Platform Coverage**: Web + Capacitor (Pixel 5) in CI |
|||
|
|||
- **Quality Assurance**: Comprehensive testing and validation |
|||
|
|||
## Current Development Focus |
|||
|
|||
### Active Development |
|||
|
|||
- **Feature Development**: Build new functionality using modern platform |
|||
|
|||
services |
|||
|
|||
- **Performance Optimization**: Improve app performance and user experience |
|||
|
|||
- **Platform Enhancement**: Leverage platform-specific capabilities |
|||
|
|||
- **Code Quality**: Maintain high standards and best practices |
|||
|
|||
### Development Metrics |
|||
|
|||
- **Code Quality**: High standards maintained across all platforms |
|||
|
|||
- **Performance**: Optimized for all target devices |
|||
|
|||
- **Testing**: Comprehensive coverage maintained |
|||
|
|||
- **User Experience**: Focus on intuitive, accessible interfaces |
|||
|
|||
## Development Environment |
|||
|
|||
### Required Tools |
|||
|
|||
- **Node.js**: LTS version with npm |
|||
|
|||
- **Git**: Version control with proper branching strategy |
|||
|
|||
- **IDE**: VS Code with recommended extensions |
|||
|
|||
- **Platform Tools**: Android Studio, Xcode (for mobile development) |
|||
|
|||
### Environment Setup |
|||
|
|||
1. **Clone Repository**: `git clone <repository-url>` |
|||
|
|||
2. **Install Dependencies**: `npm install` |
|||
|
|||
3. **Environment Variables**: Copy `.env.example` to `.env.local` |
|||
|
|||
4. **Platform Setup**: Follow platform-specific setup guides |
|||
|
|||
### Quality Assurance |
|||
|
|||
- **Linting**: ESLint with TypeScript rules |
|||
|
|||
- **Formatting**: Prettier for consistent code style |
|||
|
|||
- **Type Checking**: TypeScript strict mode enabled |
|||
|
|||
- **Testing**: Comprehensive test coverage requirements |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/app/timesafari.mdc` for core application context |
|||
|
|||
- `.cursor/rules/app/timesafari_platforms.mdc` for platform-specific details |
|||
|
|||
**Status**: Active development workflow |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: timesafari.mdc, timesafari_platforms.mdc |
|||
**Stakeholders**: Development team, DevOps team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before TimeSafari Development |
|||
|
|||
- [ ] **Environment Setup**: Verify development environment is ready |
|||
- [ ] **Platform Tools**: Ensure platform-specific tools are available |
|||
- [ ] **Dependencies**: Check all required dependencies are installed |
|||
- [ ] **Environment Variables**: Configure local environment variables |
|||
|
|||
### During TimeSafari Development |
|||
|
|||
- [ ] **Platform Services**: Use modern platform service patterns |
|||
- [ ] **Code Quality**: Follow ESLint and TypeScript strict rules |
|||
- [ ] **Testing**: Implement comprehensive testing strategy |
|||
- [ ] **Performance**: Optimize for all target platforms |
|||
|
|||
### After TimeSafari Development |
|||
|
|||
- [ ] **Quality Checks**: Run linting, formatting, and type checking |
|||
- [ ] **Testing**: Execute comprehensive tests across platforms |
|||
- [ ] **Performance Validation**: Verify performance meets requirements |
|||
- [ ] **Documentation**: Update development documentation |
@ -0,0 +1,167 @@ |
|||
# Time Safari Platforms — Platform-Specific Considerations |
|||
|
|||
> **Agent role**: Reference this file for platform-specific details when working |
|||
with TimeSafari development across different platforms. |
|||
|
|||
## Platform-Specific Considerations |
|||
|
|||
### Web (PWA) |
|||
|
|||
- **QR Scanning**: WebInlineQRScanner |
|||
|
|||
- **Deep Linking**: URL parameters |
|||
|
|||
- **File System**: Limited browser APIs |
|||
|
|||
- **Build**: `npm run build:web` (development build) |
|||
|
|||
### Mobile (Capacitor) |
|||
|
|||
- **QR Scanning**: @capacitor-mlkit/barcode-scanning |
|||
|
|||
- **Deep Linking**: App URL open events |
|||
|
|||
- **File System**: Capacitor Filesystem |
|||
|
|||
- **Build**: `npm run build:capacitor` |
|||
|
|||
### Desktop (Electron) |
|||
|
|||
- **File System**: Node.js fs |
|||
|
|||
- **Build**: `npm run build:electron` |
|||
|
|||
- **Distribution**: AppImage, DEB, DMG packages |
|||
|
|||
## Platform Compatibility Requirements |
|||
|
|||
### Cross-Platform Features |
|||
|
|||
- **Core functionality** must work identically across all platforms |
|||
|
|||
- **Platform-specific enhancements** should be additive, not required |
|||
|
|||
- **Fallback behavior** must be graceful when platform features unavailable |
|||
|
|||
### Platform-Specific Capabilities |
|||
|
|||
- **Web**: Browser APIs, PWA features, responsive design |
|||
|
|||
- **Mobile**: Native device features, offline capability, app store compliance |
|||
|
|||
- **Desktop**: File system access, system integration, native performance |
|||
|
|||
## Build and Distribution |
|||
|
|||
### Build Commands |
|||
|
|||
```bash |
|||
|
|||
# Web (development) |
|||
|
|||
npm run build:web |
|||
|
|||
# Mobile |
|||
|
|||
npm run build:capacitor |
|||
npm run build:native |
|||
|
|||
# Desktop |
|||
|
|||
npm run build:electron |
|||
npm run build:electron:appimage |
|||
npm run build:electron:deb |
|||
npm run build:electron:dmg |
|||
|
|||
``` |
|||
|
|||
### Testing Commands |
|||
|
|||
```bash |
|||
|
|||
# Web E2E |
|||
|
|||
npm run test:web |
|||
|
|||
# Mobile |
|||
|
|||
npm run test:mobile |
|||
npm run test:android |
|||
npm run test:ios |
|||
|
|||
# Type checking |
|||
|
|||
npm run type-check |
|||
npm run lint-fix |
|||
|
|||
``` |
|||
|
|||
## Key Constraints |
|||
|
|||
1. **Privacy First**: User identifiers remain private except when explicitly |
|||
|
|||
shared |
|||
|
|||
2. **Platform Compatibility**: Features must work across all target platforms |
|||
|
|||
3. **Performance**: Must remain performant on older/simpler devices |
|||
|
|||
4. **Modern Architecture**: New features should use current platform services |
|||
|
|||
5. **Offline Capability**: Key functionality should work offline when feasible |
|||
|
|||
## Use Cases to Support |
|||
|
|||
1. **Community Building**: Tools for finding others with shared interests |
|||
|
|||
2. **Project Coordination**: Easy proposal and collaboration on projects |
|||
|
|||
3. **Reputation Building**: Showcasing contributions and reliability |
|||
|
|||
4. **Governance**: Facilitating decision-making and collective governance |
|||
|
|||
## Resources |
|||
|
|||
- **Testing**: `docs/migration-testing/` |
|||
|
|||
- **Architecture**: `docs/architecture-decisions.md` |
|||
|
|||
- **Build Context**: `docs/build-modernization-context.md` |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/app/timesafari.mdc` for core application context |
|||
- `.cursor/rules/app/timesafari_development.mdc` for |
|||
|
|||
development workflow details |
|||
|
|||
**Status**: Active platform guidelines |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: timesafari.mdc |
|||
**Stakeholders**: Development team, Platform teams |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Platform Development |
|||
|
|||
- [ ] **Platform Analysis**: Identify all target platforms (web, mobile, desktop) |
|||
- [ ] **Feature Requirements**: Understand feature requirements across platforms |
|||
- [ ] **Platform Constraints**: Review platform-specific limitations and capabilities |
|||
- [ ] **Testing Strategy**: Plan testing approach for all target platforms |
|||
|
|||
### During Platform Development |
|||
|
|||
- [ ] **Cross-Platform Implementation**: Implement features across all platforms |
|||
- [ ] **Platform Services**: Use current platform services for new features |
|||
- [ ] **Performance Optimization**: Ensure performance on older/simpler devices |
|||
- [ ] **Offline Capability**: Implement offline functionality where feasible |
|||
|
|||
### After Platform Development |
|||
|
|||
- [ ] **Cross-Platform Testing**: Test functionality across all target platforms |
|||
- [ ] **Performance Validation**: Verify performance meets requirements |
|||
- [ ] **Documentation Update**: Update platform-specific documentation |
|||
- [ ] **Team Communication**: Share platform implementation results with team |
@ -0,0 +1,75 @@ |
|||
# Architecture Rules Directory |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-20 |
|||
**Status**: 🎯 **ACTIVE** - Architecture protection guidelines |
|||
|
|||
## Overview |
|||
|
|||
This directory contains MDC (Model Directive Configuration) rules that protect |
|||
critical architectural components of the TimeSafari project. These rules ensure |
|||
that changes to system architecture follow proper review, testing, and |
|||
documentation procedures. |
|||
|
|||
## Available Rules |
|||
|
|||
### Build Architecture Guard (`build_architecture_guard.mdc`) |
|||
|
|||
Protects the multi-platform build system including: |
|||
|
|||
- Vite configuration files |
|||
- Build scripts and automation |
|||
- Platform-specific configurations (iOS, Android, Electron, Web) |
|||
- Docker and deployment infrastructure |
|||
- CI/CD pipeline components |
|||
|
|||
**When to use**: Any time you're modifying build scripts, configuration files, |
|||
or deployment processes. |
|||
|
|||
**Authorization levels**: |
|||
|
|||
- **Level 1**: Minor changes (review required) |
|||
- **Level 2**: Moderate changes (testing required) |
|||
- **Level 3**: Major changes (ADR required) |
|||
|
|||
## Usage Guidelines |
|||
|
|||
### For Developers |
|||
|
|||
1. **Check the rule**: Before making architectural changes, review the relevant |
|||
rule |
|||
2. **Follow the process**: Use the appropriate authorization level |
|||
3. **Complete validation**: Run through the required checklist |
|||
4. **Update documentation**: Keep BUILDING.md and related docs current |
|||
|
|||
### For Reviewers |
|||
|
|||
1. **Verify authorization**: Ensure changes match the required level |
|||
2. **Check testing**: Confirm appropriate testing has been completed |
|||
3. **Validate documentation**: Ensure BUILDING.md reflects changes |
|||
4. **Assess risk**: Consider impact on other platforms and systems |
|||
|
|||
## Integration with Other Rules |
|||
|
|||
- **Version Control**: Works with `workflow/version_control.mdc` |
|||
- **Research & Diagnostic**: Supports `research_diagnostic.mdc` for |
|||
investigations |
|||
- **Software Development**: Aligns with development best practices |
|||
- **Markdown Automation**: Integrates with `docs/markdown-automation.mdc` for |
|||
consistent documentation formatting |
|||
|
|||
## Emergency Procedures |
|||
|
|||
If architectural changes cause system failures: |
|||
|
|||
1. **Immediate rollback** to last known working state |
|||
2. **Document the failure** with full error details |
|||
3. **Investigate root cause** using diagnostic workflows |
|||
4. **Update procedures** to prevent future failures |
|||
|
|||
--- |
|||
|
|||
**Status**: Active architecture protection |
|||
**Priority**: Critical |
|||
**Maintainer**: Development team |
|||
**Next Review**: 2025-09-20 |
@ -0,0 +1,186 @@ |
|||
|
|||
# Build Architecture Guard Directive |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-22 |
|||
**Status**: 🎯 **ACTIVE** - Build system protection guidelines |
|||
|
|||
## Purpose |
|||
|
|||
Protect the TimeSafari building architecture from unauthorized changes that |
|||
could break the multi-platform build pipeline, deployment processes, or |
|||
development workflow. This directive ensures all build system modifications |
|||
follow proper review, testing, and documentation procedures. |
|||
|
|||
**Note**: Recent Android build system enhancements (2025-08-22) include |
|||
sophisticated asset validation, platform-specific API routing, and automatic |
|||
resource regeneration. These features require enhanced testing and validation |
|||
procedures. |
|||
|
|||
## Protected Architecture Components |
|||
|
|||
### Core Build Infrastructure |
|||
|
|||
- **Vite Configuration Files**: `vite.config.*.mts` files |
|||
|
|||
- **Build Scripts**: All scripts in `scripts/` directory |
|||
|
|||
- **Package Scripts**: `package.json` build-related scripts |
|||
|
|||
- **Platform Configs**: `capacitor.config.ts`, `electron/`, `android/`, |
|||
|
|||
`ios/` |
|||
|
|||
- **Docker Configuration**: `Dockerfile`, `docker-compose.yml` |
|||
|
|||
- **Environment Files**: `.env.*`, `.nvmrc`, `.node-version` |
|||
|
|||
### Android-Specific Build Validation |
|||
|
|||
- **Asset Validation Scripts**: |
|||
|
|||
`validate_android_assets()` function and resource checking |
|||
|
|||
- **Resource Generation**: `capacitor-assets` integration and verification |
|||
|
|||
- **Platform-Specific IP Handling**: |
|||
|
|||
Android emulator vs physical device API routing |
|||
|
|||
- **Build Mode Validation**: Development/test/production mode handling |
|||
|
|||
- **Resource Fallback Logic**: |
|||
|
|||
Automatic regeneration of missing Android resources |
|||
|
|||
### Critical Build Dependencies |
|||
|
|||
- **Build Tools**: Vite, Capacitor, Electron, Android SDK, Xcode |
|||
|
|||
- **Asset Management**: `capacitor-assets.config.json`, asset scripts |
|||
|
|||
- **Testing Infrastructure**: Playwright, Jest, mobile test scripts |
|||
|
|||
- **CI/CD Pipeline**: GitHub Actions, build validation scripts |
|||
|
|||
- **Service Worker Assembly**: `sw_scripts/`, `sw_combine.js`, WASM copy steps |
|||
|
|||
## Change Authorization Requirements |
|||
|
|||
### Level 1: Minor Changes (Requires Review) |
|||
|
|||
- Documentation updates to `BUILDING.md` |
|||
|
|||
- Non-breaking script improvements |
|||
|
|||
- Test additions or improvements |
|||
|
|||
- Asset configuration updates |
|||
|
|||
**Process**: Code review + basic testing |
|||
|
|||
### Level 2: Moderate Changes (Requires Testing) |
|||
|
|||
- New build script additions |
|||
|
|||
- Environment variable changes |
|||
|
|||
- Dependency version updates |
|||
|
|||
- Platform-specific optimizations |
|||
|
|||
- **Build script argument parsing**: |
|||
|
|||
New flag handling (--api-ip, --auto-run, --deploy) |
|||
|
|||
- **Platform-specific environment overrides**: |
|||
|
|||
Android API server IP customization |
|||
|
|||
- **Asset regeneration logic**: Automatic fallback for missing Android resources |
|||
|
|||
**Process**: Code review + platform testing + documentation update |
|||
|
|||
### Level 3: Major Changes (Requires ADR) |
|||
|
|||
- Build system architecture changes |
|||
|
|||
- New platform support |
|||
|
|||
- Breaking changes to build scripts |
|||
|
|||
- Major dependency migrations |
|||
|
|||
**Process**: ADR creation + comprehensive testing + team review |
|||
|
|||
## Prohibited Actions |
|||
|
|||
### ❌ Never Allow Without ADR |
|||
|
|||
- **Delete or rename** core build scripts |
|||
|
|||
- **Modify** `package.json` build script names |
|||
|
|||
- **Change** Vite configuration structure |
|||
|
|||
- **Remove** platform-specific build targets |
|||
|
|||
- **Alter** Docker build process |
|||
|
|||
- **Modify** CI/CD pipeline without testing |
|||
|
|||
### ❌ Never Allow Without Testing |
|||
|
|||
- **Update** build dependencies |
|||
|
|||
- **Change** environment configurations |
|||
|
|||
- **Modify** asset generation scripts |
|||
|
|||
- **Alter** test infrastructure |
|||
|
|||
- **Update** platform SDK versions |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/architecture/build_validation.mdc` for |
|||
|
|||
detailed validation procedures |
|||
|
|||
- `.cursor/rules/architecture/build_testing.mdc` for testing requirements |
|||
|
|||
**Status**: Active build protection guidelines |
|||
**Priority**: Critical |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: None |
|||
**Stakeholders**: Development team, DevOps team, Build team |
|||
|
|||
**Estimated Effort**: Ongoing vigilance |
|||
**Dependencies**: All build system components |
|||
**Stakeholders**: Development team, DevOps, Platform owners |
|||
**Next Review**: 2025-09-22 |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Build Changes |
|||
|
|||
- [ ] **Change Level**: Determine if change is L1, L2, or L3 |
|||
- [ ] **Impact Assessment**: Assess impact on build system architecture |
|||
- [ ] **ADR Requirement**: Check if ADR is required for major changes |
|||
- [ ] **Testing Planning**: Plan appropriate testing for change level |
|||
|
|||
### During Build Changes |
|||
|
|||
- [ ] **Guard Compliance**: Ensure changes comply with build architecture guard |
|||
- [ ] **Documentation**: Document changes according to level requirements |
|||
- [ ] **Testing**: Execute appropriate testing for change level |
|||
- [ ] **Review Process**: Follow required review process for change level |
|||
|
|||
### After Build Changes |
|||
|
|||
- [ ] **Validation**: Verify build system still functions correctly |
|||
- [ ] **Documentation Update**: Update relevant documentation |
|||
- [ ] **Team Communication**: Communicate changes to affected teams |
|||
- [ ] **Monitoring**: Monitor for any build system issues |
@ -0,0 +1,248 @@ |
|||
# Build Testing — Requirements and Emergency Procedures |
|||
|
|||
> **Agent role**: Reference this file for testing requirements and |
|||
emergency procedures when working with build architecture changes. |
|||
|
|||
## Emergency Procedures |
|||
|
|||
### Build System Broken |
|||
|
|||
1. **Immediate**: Revert to last known working commit |
|||
|
|||
2. **Investigation**: Create issue with full error details |
|||
|
|||
3. **Testing**: Verify all platforms work after revert |
|||
|
|||
4. **Documentation**: Update `BUILDING.md` with failure notes |
|||
|
|||
### Platform-Specific Failure |
|||
|
|||
1. **Isolate**: Identify which platform is affected |
|||
|
|||
2. **Test Others**: Verify other platforms still work |
|||
|
|||
3. **Rollback**: Revert platform-specific changes |
|||
|
|||
4. **Investigation**: Debug in isolated environment |
|||
|
|||
## Rollback Playbook |
|||
|
|||
### Immediate Rollback |
|||
|
|||
1. `git revert` or `git reset --hard <prev>`; restore prior `scripts/` or config |
|||
|
|||
files |
|||
|
|||
2. Rebuild affected targets; verify old behavior returns |
|||
|
|||
3. Post-mortem notes → update this guard and `BUILDING.md` if gaps found |
|||
|
|||
### Rollback Verification |
|||
|
|||
- **Web**: `npm run build:web:dev` and `npm run build:web:prod` |
|||
|
|||
- **Mobile**: `npm run build:android:test` and `npm run build:ios:test` |
|||
|
|||
- **Desktop**: `npm run build:electron:dev` and packaging commands |
|||
|
|||
- **Clean**: Run relevant `clean:*` scripts and verify re-build works |
|||
|
|||
### Android-Specific Rollback Verification |
|||
|
|||
- **Asset Generation**: `npm run build:android --assets` - |
|||
|
|||
verify resources regenerate |
|||
|
|||
- **API Routing**: Test both `--dev` and `--dev --api-ip <custom>` modes |
|||
|
|||
- **Resource Validation**: |
|||
|
|||
Check `android/app/src/main/res/` for all required assets |
|||
|
|||
- **Build Modes**: Verify development, test, and production modes all work |
|||
|
|||
- **Resource Fallback**: |
|||
|
|||
Confirm missing resources trigger automatic regeneration |
|||
|
|||
## Integration Points |
|||
|
|||
### With Version Control |
|||
|
|||
- **Branch Protection**: Require reviews for build script changes |
|||
|
|||
- **Commit Messages**: Must reference ADR for major changes |
|||
|
|||
- **Testing**: All build changes must pass CI/CD pipeline |
|||
|
|||
### With Documentation |
|||
|
|||
- **BUILDING.md**: Must be updated for any script changes |
|||
|
|||
- **README.md**: Must reflect new build requirements |
|||
|
|||
- **CHANGELOG.md**: Must document breaking build changes |
|||
|
|||
### With Testing |
|||
|
|||
- **Pre-commit**: Run basic build validation |
|||
|
|||
- **CI/CD**: Full platform build testing |
|||
|
|||
- **Manual Testing**: Human verification of critical paths |
|||
|
|||
## Competence Hooks |
|||
|
|||
### Why This Works |
|||
|
|||
- **Prevents Build Failures**: Catches issues before they reach production |
|||
|
|||
- **Maintains Consistency**: Ensures all platforms build identically |
|||
|
|||
- **Reduces Debugging Time**: Prevents build system regressions |
|||
|
|||
### Common Pitfalls |
|||
|
|||
- **Silent Failures**: Changes that work on one platform but break others |
|||
|
|||
- **Dependency Conflicts**: Updates that create version incompatibilities |
|||
|
|||
- **Documentation Drift**: Build scripts that don't match documentation |
|||
|
|||
### Next Skill Unlock |
|||
|
|||
- Learn to test build changes across all platforms simultaneously |
|||
|
|||
### Teach-back |
|||
|
|||
- "What three platforms must I test before committing a build script change?" |
|||
|
|||
## Collaboration Hooks |
|||
|
|||
### Team Review Requirements |
|||
|
|||
- **Platform Owners**: iOS, Android, Electron, Web specialists |
|||
|
|||
- **DevOps**: CI/CD pipeline maintainers |
|||
|
|||
- **QA**: Testing infrastructure owners |
|||
|
|||
### Discussion Prompts |
|||
|
|||
- "Which platforms will be affected by this build change?" |
|||
|
|||
- "How can we test this change without breaking existing builds?" |
|||
|
|||
- "What's our rollback plan if this change fails?" |
|||
|
|||
## Self-Check (Before Allowing Changes) |
|||
|
|||
- [ ] **Authorization Level**: Is this change appropriate for the level? |
|||
|
|||
- [ ] **Testing Plan**: Is there a comprehensive testing strategy? |
|||
|
|||
- [ ] **Documentation**: Will BUILDING.md be updated? |
|||
|
|||
- [ ] **Rollback**: Is there a safe rollback mechanism? |
|||
|
|||
- [ ] **Team Review**: Have appropriate stakeholders been consulted? |
|||
|
|||
- [ ] **CI/CD**: Will this pass the build pipeline? |
|||
|
|||
## Continuous Improvement & Feedback |
|||
|
|||
### Feedback Collection |
|||
|
|||
The Build Architecture Guard system includes feedback mechanisms to continuously |
|||
improve its effectiveness: |
|||
|
|||
- **User Feedback**: Script includes feedback prompts for guard improvements |
|||
|
|||
- **Pattern Analysis**: |
|||
|
|||
Monitor which file patterns trigger false positives/negatives |
|||
|
|||
- **Documentation Gaps**: Track which changes lack proper documentation |
|||
|
|||
- **Testing Effectiveness**: Measure how often guard catches actual issues |
|||
|
|||
### Feedback Integration Process |
|||
|
|||
1. **Collect Feedback**: Monitor guard execution logs and user reports |
|||
|
|||
2. **Analyze Patterns**: Identify common false positives or missed patterns |
|||
|
|||
3. **Update Rules**: Modify `build_architecture_guard.mdc` based on feedback |
|||
|
|||
4. **Enhance Script**: Update `build-arch-guard.sh` with new validations |
|||
|
|||
5. **Test Changes**: Verify guard improvements don't introduce new issues |
|||
|
|||
6. **Document Updates**: Update guard documentation with new patterns |
|||
|
|||
### Feedback Categories |
|||
|
|||
- **False Positives**: Files flagged as sensitive that shouldn't be |
|||
|
|||
- **False Negatives**: Sensitive files that weren't caught |
|||
|
|||
- **Missing Patterns**: New file types that should be protected |
|||
|
|||
- **Overly Strict**: Patterns that are too restrictive |
|||
|
|||
- **Documentation Gaps**: Missing guidance for specific change types |
|||
|
|||
- **Testing Improvements**: Better validation procedures |
|||
|
|||
### Feedback Reporting |
|||
|
|||
When reporting guard issues, include: |
|||
|
|||
- **File patterns** that triggered false positives/negatives |
|||
|
|||
- **Build system changes** that weren't properly caught |
|||
|
|||
- **Documentation gaps** in current guard rules |
|||
|
|||
- **Testing procedures** that could be improved |
|||
|
|||
- **User experience** issues with guard enforcement |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/architecture/build_architecture_guard.mdc` for |
|||
|
|||
core protection guidelines |
|||
|
|||
- `.cursor/rules/architecture/build_validation.mdc` for validation procedures |
|||
|
|||
**Status**: Active testing requirements |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: build_architecture_guard.mdc, build_validation.mdc |
|||
**Stakeholders**: Development team, DevOps team, Build team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Build Testing |
|||
|
|||
- [ ] **Test Planning**: Plan comprehensive testing strategy for build changes |
|||
- [ ] **Platform Coverage**: Identify all platforms that need testing |
|||
- [ ] **Risk Assessment**: Assess testing risks and mitigation strategies |
|||
- [ ] **Resource Planning**: Plan testing resources and time requirements |
|||
|
|||
### During Build Testing |
|||
|
|||
- [ ] **Test Execution**: Execute planned tests across all platforms |
|||
- [ ] **Issue Tracking**: Track and document any issues found |
|||
- [ ] **Feedback Collection**: Collect feedback on testing effectiveness |
|||
- [ ] **Documentation**: Document testing procedures and results |
|||
|
|||
### After Build Testing |
|||
|
|||
- [ ] **Result Analysis**: Analyze testing results and identify patterns |
|||
- [ ] **Feedback Integration**: Integrate feedback into testing procedures |
|||
- [ ] **Process Improvement**: Update testing procedures based on feedback |
|||
- [ ] **Team Communication**: Share testing results and improvements with team |
@ -0,0 +1,224 @@ |
|||
# Build Validation — Procedures and Requirements |
|||
|
|||
> **Agent role**: Reference this file for |
|||
detailed validation procedures when working with build architecture changes. |
|||
|
|||
## Required Validation Checklist |
|||
|
|||
### Before Any Build System Change |
|||
|
|||
- [ ] **Impact Assessment**: Which platforms are affected? |
|||
|
|||
- [ ] **Testing Plan**: How will this be tested across platforms? |
|||
|
|||
- [ ] **Rollback Plan**: How can this be reverted if it breaks? |
|||
|
|||
- [ ] **Documentation**: Will `BUILDING.md` need updates? |
|||
|
|||
- [ ] **Dependencies**: Are all required tools available? |
|||
|
|||
### After Build System Change |
|||
|
|||
- [ ] **Web Platform**: Does `npm run build:web:dev` work? |
|||
|
|||
- [ ] **Mobile Platforms**: Do iOS/Android builds succeed? |
|||
|
|||
- [ ] **Desktop Platform**: Does Electron build and run? |
|||
|
|||
- [ ] **Tests Pass**: Do all build-related tests pass? |
|||
|
|||
- [ ] **Documentation Updated**: Is `BUILDING.md` current? |
|||
|
|||
## Specific Test Commands (Minimum Required) |
|||
|
|||
### Web Platform |
|||
|
|||
- **Development**: `npm run build:web:dev` - serve and load app |
|||
|
|||
- **Production**: `npm run build:web:prod` - verify SW and WASM present |
|||
|
|||
### Mobile Platforms |
|||
|
|||
- **Android**: `npm run build:android:test` or `:prod` - confirm assets copied |
|||
|
|||
- **iOS**: `npm run build:ios:test` or `:prod` - verify build succeeds |
|||
|
|||
### Android Platform (Enhanced) |
|||
|
|||
- **Development Mode**: `npm run build:android --dev` - |
|||
|
|||
verify 10.0.2.2 API routing |
|||
|
|||
- **Custom IP Mode**: `npm run build:android --dev --api-ip 192.168.1.100` - |
|||
|
|||
verify custom IP |
|||
|
|||
- **Asset Validation**: `npm run build:android --assets` - |
|||
|
|||
verify resource generation |
|||
|
|||
- **Deploy Mode**: `npm run build:android --deploy` - verify device deployment |
|||
|
|||
### Desktop Platform |
|||
|
|||
- **Electron**: `npm run build:electron:dev` and packaging for target OS |
|||
|
|||
- **Verify**: Single-instance behavior and app boot |
|||
|
|||
### Auto-run (if affected) |
|||
|
|||
- **Test Mode**: `npm run auto-run:test` and platform variants |
|||
|
|||
- **Production Mode**: `npm run auto-run:prod` and platform variants |
|||
|
|||
### Clean and Rebuild |
|||
|
|||
- Run relevant `clean:*` scripts and ensure re-build works |
|||
|
|||
## Risk Matrix & Required Validation |
|||
|
|||
### Environment Handling |
|||
|
|||
- **Trigger**: Change to `.env.*` loading / variable names |
|||
|
|||
- **Validation**: Prove `dev/test/prod` builds; show environment echo in logs |
|||
|
|||
### Script Flow |
|||
|
|||
- **Trigger**: Reorder steps (prebuild → build → package), new flags |
|||
|
|||
- **Validation**: Dry-run + normal run, show exit codes & timing |
|||
|
|||
### Platform Packaging |
|||
|
|||
- **Trigger**: Electron NSIS/DMG/AppImage, Android/iOS bundle |
|||
|
|||
- **Validation**: Produce installer/artifact and open it; |
|||
|
|||
verify single-instance, |
|||
icons, signing |
|||
|
|||
### Service Worker / WASM |
|||
|
|||
- **Trigger**: `sw_combine.js`, WASM copy path |
|||
|
|||
- **Validation**: Verify combined SW exists and is injected; page loads offline; |
|||
|
|||
WASM present |
|||
|
|||
### Docker |
|||
|
|||
- **Trigger**: New base image, build args |
|||
|
|||
- **Validation**: Build image locally; run container; list produced `/dist` |
|||
|
|||
### Android Asset Management |
|||
|
|||
- **Trigger**: Changes to `validate_android_assets()` function or resource paths |
|||
|
|||
- **Validation**: |
|||
|
|||
Run `npm run build:android --assets` and verify all mipmap/drawable resources |
|||
|
|||
- **Risk**: Missing splash screens or app icons causing build failures |
|||
|
|||
### Android API Routing |
|||
|
|||
- **Trigger**: Changes to Android-specific API server IP logic |
|||
|
|||
- **Validation**: Test both emulator (10.0.2.2) and custom IP modes |
|||
|
|||
- **Risk**: API connectivity failures on different device types |
|||
|
|||
### Signing/Notarization |
|||
|
|||
- **Trigger**: Cert path/profiles |
|||
|
|||
- **Validation**: Show signing logs + verify on target OS |
|||
|
|||
## PR Template (Paste into Description) |
|||
|
|||
- [ ] **Level**: L1 / L2 / L3 + justification |
|||
|
|||
- [ ] **Files & platforms touched**: |
|||
|
|||
- [ ] **Risk triggers & mitigations**: |
|||
|
|||
- [ ] **Commands run (paste logs)**: |
|||
|
|||
- [ ] **Artifacts (names + sha256)**: |
|||
|
|||
- [ ] **Docs updated (sections/links)**: |
|||
|
|||
- [ ] **Rollback steps verified**: |
|||
|
|||
- [ ] **CI**: Jobs passing and artifacts uploaded |
|||
|
|||
## ADR Trigger List |
|||
|
|||
Raise an ADR when you propose any of: |
|||
|
|||
- **New build stage** or reorder of canonical stages |
|||
|
|||
- **Replacement of packager** / packaging format |
|||
|
|||
- **New environment model** or secure secret handling scheme |
|||
|
|||
- **New service worker assembly** strategy or cache policy |
|||
|
|||
- **New Docker base** or multi-stage pipeline |
|||
|
|||
- **Relocation of build outputs** or directory conventions |
|||
|
|||
- **New Android build modes** or argument parsing logic |
|||
|
|||
- **Changes to asset validation** or resource generation strategy |
|||
|
|||
- **Modifications to platform-specific API routing** ( |
|||
|
|||
Android emulator vs physical) |
|||
|
|||
- **New Android deployment strategies** or device management |
|||
|
|||
**ADR must include**: |
|||
motivation, alternatives, risks, validation plan, rollback, |
|||
doc diffs. |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/architecture/build_architecture_guard.mdc` for |
|||
|
|||
core protection guidelines |
|||
|
|||
- `.cursor/rules/architecture/build_testing.mdc` for testing requirements |
|||
|
|||
**Status**: Active validation procedures |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: build_architecture_guard.mdc |
|||
**Stakeholders**: Development team, DevOps team, Build team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Build Changes |
|||
|
|||
- [ ] **Level Assessment**: Determine build validation level (L1/L2/L3) |
|||
- [ ] **Platform Analysis**: Identify all platforms affected by changes |
|||
- [ ] **Risk Assessment**: Identify risk triggers and mitigation strategies |
|||
- [ ] **Rollback Planning**: Plan rollback steps for build failures |
|||
|
|||
### During Build Implementation |
|||
|
|||
- [ ] **Validation Commands**: Run appropriate validation commands for level |
|||
- [ ] **Platform Testing**: Test changes across all affected platforms |
|||
- [ ] **Risk Mitigation**: Implement identified risk mitigation strategies |
|||
- [ ] **Documentation**: Document all commands run and their outputs |
|||
|
|||
### After Build Implementation |
|||
|
|||
- [ ] **Artifact Validation**: Verify build artifacts are correct and accessible |
|||
- [ ] **CI Verification**: Ensure CI jobs pass and artifacts are uploaded |
|||
- [ ] **Documentation Update**: Update relevant documentation sections |
|||
- [ ] **Team Communication**: Share build validation results with team |
@ -1,32 +0,0 @@ |
|||
--- |
|||
alwaysApply: true |
|||
--- |
|||
# Asset Configuration Directive |
|||
*Scope: Assets Only (icons, splashes, image pipelines) — not overall build orchestration* |
|||
|
|||
## Intent |
|||
- Version **asset configuration files** (optionally dev-time generated). |
|||
- **Do not** version platform asset outputs (Android/iOS/Electron); generate them **at build-time** with standard tools. |
|||
- Keep existing per-platform build scripts unchanged. |
|||
|
|||
## Source of Truth |
|||
- **Preferred (Capacitor default):** `resources/` as the single master source. |
|||
- **Alternative:** `assets/` is acceptable **only** if `capacitor-assets` is explicitly configured to read from it. |
|||
- **Never** maintain both `resources/` and `assets/` as parallel sources. Migrate and delete the redundant folder. |
|||
|
|||
## Config Files |
|||
- Live under: `config/assets/` (committed). |
|||
- Examples: |
|||
- `config/assets/capacitor-assets.config.json` (or the path the tool expects) |
|||
- `config/assets/android.assets.json` |
|||
- `config/assets/ios.assets.json` |
|||
- `config/assets/common.assets.yaml` (optional shared layer) |
|||
- **Dev-time generation allowed** for these configs; **build-time generation is forbidden**. |
|||
|
|||
## Build-Time Behavior |
|||
- Build generates platform assets (not configs) using the standard chain: |
|||
```bash |
|||
npm run build:capacitor # web build via Vite (.mts) |
|||
npx cap sync |
|||
npx capacitor-assets generate # produces platform assets; not committed |
|||
# then platform-specific build steps |
@ -1,224 +0,0 @@ |
|||
--- |
|||
alwaysApply: true |
|||
--- |
|||
|
|||
```json |
|||
{ |
|||
"coaching_level": "standard", |
|||
"socratic_max_questions": 7, |
|||
"verbosity": "normal", |
|||
"timebox_minutes": null, |
|||
"format_enforcement": "strict" |
|||
} |
|||
``` |
|||
|
|||
# Base Context — Human Competence First |
|||
|
|||
## Purpose |
|||
All interactions must *increase the human's competence over time* while |
|||
completing the task efficiently. The model may handle menial work and memory |
|||
extension, but must also promote learning, autonomy, and healthy work habits. |
|||
The model should also **encourage human interaction and collaboration** rather |
|||
than replacing it — outputs should be designed to **facilitate human discussion, |
|||
decision-making, and creativity**, not to atomize tasks into isolated, purely |
|||
machine-driven steps. |
|||
|
|||
## Principles |
|||
|
|||
1) Competence over convenience: finish the task *and* leave the human more |
|||
capable next time. |
|||
2) Mentorship, not lectures: be concise, concrete, and immediately applicable. |
|||
3) Transparency: show assumptions, limits, and uncertainty; cite when non-obvious. |
|||
4) Optional scaffolding: include small, skimmable learning hooks that do not |
|||
bloat output. |
|||
5) Time respect: default to **lean output**; offer opt-in depth via toggles. |
|||
6) Psychological safety: encourage, never condescend; no medical/clinical advice. |
|||
No censorship! |
|||
7) Reusability: structure outputs so they can be saved, searched, reused, and repurposed. |
|||
8) **Collaborative Bias**: Favor solutions that invite human review, discussion, |
|||
and iteration. When in doubt, ask "Who should this be shown to?" or "Which human |
|||
input would improve this?" |
|||
|
|||
## Toggle Definitions |
|||
|
|||
### coaching_level |
|||
|
|||
Determines the depth of learning support: `light` (short hooks), `standard` |
|||
(balanced), `deep` (detailed). |
|||
|
|||
### socratic_max_questions |
|||
|
|||
The number of clarifying questions the model may ask before proceeding. |
|||
If >0, questions should be targeted, minimal, and followed by reasonable assumptions if unanswered. |
|||
|
|||
### verbosity |
|||
'terse' (just a sentence), `concise` (minimum commentary), `normal` (balanced explanation), or other project-defined levels. |
|||
|
|||
### timebox_minutes |
|||
*integer or null* — When set to a positive integer (e.g., `5`), this acts as a **time budget** guiding the model to prioritize delivering the most essential parts of the task within that constraint. |
|||
Behavior when set: |
|||
1. **Prioritize Core Output** — Deliver the minimum viable solution or result first. |
|||
2. **Limit Commentary** — Competence Hooks and Collaboration Hooks must be shorter than normal. |
|||
3. **Signal Skipped Depth** — Omitted details should be listed under *Deferred for depth*. |
|||
4. **Order by Value** — Start with blocking or high-value items, then proceed to nice-to-haves if budget allows. |
|||
If `null`, there is no timebox — the model can produce full-depth responses. |
|||
|
|||
### format_enforcement |
|||
`strict` (reject outputs with format drift) or `relaxed` (minor deviations acceptable). |
|||
|
|||
## Modes (select or combine) |
|||
- **Doer**: produce the artifact fast, minimal commentary. |
|||
- **Mentor**: add short "why/how" notes + next-step pointers. |
|||
- **Socratic**: ask up to N targeted questions when requirements are ambiguous. |
|||
- **Pair-Programmer/Pair-Writer**: explain tradeoffs as you implement. |
|||
- **Facilitator**: structure output to be reviewable, commentable, and ready for group discussion. |
|||
|
|||
Default: Doer + short Mentor notes. |
|||
|
|||
## Competence & Collaboration Levers (keep lightweight) |
|||
- "Why this works" (≤3 bullets) |
|||
- "Common pitfalls" (≤3 bullets) |
|||
- "Next skill unlock" (1 tiny action or reading) |
|||
- "Teach-back" (1 sentence prompt the human can answer to self-check) |
|||
- "Discussion prompts" (≤2 short questions for peers/stakeholders) |
|||
|
|||
## Output Contract (apply to every deliverable) |
|||
- Clear **Objective** (1 line) |
|||
- **Result** (artifact/code/answer) |
|||
- **Use/Run** (how to apply/test) |
|||
- **Competence Hooks** (the 4 learning levers above, kept terse) |
|||
- **Collaboration Hooks** (discussion prompts or group review steps) |
|||
- **Assumptions & Limits** |
|||
- **References** (if used; links or titles) |
|||
|
|||
## Do-Not |
|||
- No filler, hedging, or moralizing. |
|||
- No medical/mental-health advice; keep "healthy habits" to general work practices. |
|||
- No invented facts; mark uncertainty plainly. |
|||
- No censorship. |
|||
- Avoid outputs that bypass human review when such review is valuable. |
|||
|
|||
## Related Rulesets |
|||
|
|||
- **software_development.mdc**: For software-specific development practices |
|||
- **research_diagnostic.mdc**: For investigation and research workflows |
|||
|
|||
## Self-Check (model, before responding) |
|||
- [ ] Task done *and* at least one competence lever included (≤120 words total). |
|||
- [ ] At least one collaboration/discussion hook present. |
|||
- [ ] Output follows the **Output Contract** sections. |
|||
- [ ] Toggles respected; verbosity remains concise. |
|||
- [ ] Uncertainties/assumptions surfaced. |
|||
- [ ] No disallowed content. |
|||
- [ ] Uncertainties/assumptions surfaced. |
|||
- [ ] No disallowed content. |
|||
```json |
|||
{ |
|||
"coaching_level": "standard", |
|||
"socratic_max_questions": 7, |
|||
"verbosity": "normal", |
|||
"timebox_minutes": null, |
|||
"format_enforcement": "strict" |
|||
} |
|||
``` |
|||
|
|||
# Base Context — Human Competence First |
|||
|
|||
## Purpose |
|||
All interactions must *increase the human's competence over time* while |
|||
completing the task efficiently. The model may handle menial work and memory |
|||
extension, but must also promote learning, autonomy, and healthy work habits. |
|||
The model should also **encourage human interaction and collaboration** rather |
|||
than replacing it — outputs should be designed to **facilitate human discussion, |
|||
decision-making, and creativity**, not to atomize tasks into isolated, purely |
|||
machine-driven steps. |
|||
|
|||
## Principles |
|||
|
|||
1) Competence over convenience: finish the task *and* leave the human more |
|||
capable next time. |
|||
2) Mentorship, not lectures: be concise, concrete, and immediately applicable. |
|||
3) Transparency: show assumptions, limits, and uncertainty; cite when non-obvious. |
|||
4) Optional scaffolding: include small, skimmable learning hooks that do not |
|||
bloat output. |
|||
5) Time respect: default to **lean output**; offer opt-in depth via toggles. |
|||
6) Psychological safety: encourage, never condescend; no medical/clinical advice. |
|||
No censorship! |
|||
7) Reusability: structure outputs so they can be saved, searched, reused, and repurposed. |
|||
8) **Collaborative Bias**: Favor solutions that invite human review, discussion, |
|||
and iteration. When in doubt, ask "Who should this be shown to?" or "Which human |
|||
input would improve this?" |
|||
|
|||
## Toggle Definitions |
|||
|
|||
### coaching_level |
|||
|
|||
Determines the depth of learning support: `light` (short hooks), `standard` |
|||
(balanced), `deep` (detailed). |
|||
|
|||
### socratic_max_questions |
|||
|
|||
The number of clarifying questions the model may ask before proceeding. |
|||
If >0, questions should be targeted, minimal, and followed by reasonable assumptions if unanswered. |
|||
|
|||
### verbosity |
|||
'terse' (just a sentence), `concise` (minimum commentary), `normal` (balanced explanation), or other project-defined levels. |
|||
|
|||
### timebox_minutes |
|||
*integer or null* — When set to a positive integer (e.g., `5`), this acts as a **time budget** guiding the model to prioritize delivering the most essential parts of the task within that constraint. |
|||
Behavior when set: |
|||
1. **Prioritize Core Output** — Deliver the minimum viable solution or result first. |
|||
2. **Limit Commentary** — Competence Hooks and Collaboration Hooks must be shorter than normal. |
|||
3. **Signal Skipped Depth** — Omitted details should be listed under *Deferred for depth*. |
|||
4. **Order by Value** — Start with blocking or high-value items, then proceed to nice-to-haves if budget allows. |
|||
If `null`, there is no timebox — the model can produce full-depth responses. |
|||
|
|||
### format_enforcement |
|||
`strict` (reject outputs with format drift) or `relaxed` (minor deviations acceptable). |
|||
|
|||
## Modes (select or combine) |
|||
- **Doer**: produce the artifact fast, minimal commentary. |
|||
- **Mentor**: add short "why/how" notes + next-step pointers. |
|||
- **Socratic**: ask up to N targeted questions when requirements are ambiguous. |
|||
- **Pair-Programmer/Pair-Writer**: explain tradeoffs as you implement. |
|||
- **Facilitator**: structure output to be reviewable, commentable, and ready for group discussion. |
|||
|
|||
Default: Doer + short Mentor notes. |
|||
|
|||
## Competence & Collaboration Levers (keep lightweight) |
|||
- "Why this works" (≤3 bullets) |
|||
- "Common pitfalls" (≤3 bullets) |
|||
- "Next skill unlock" (1 tiny action or reading) |
|||
- "Teach-back" (1 sentence prompt the human can answer to self-check) |
|||
- "Discussion prompts" (≤2 short questions for peers/stakeholders) |
|||
|
|||
## Output Contract (apply to every deliverable) |
|||
- Clear **Objective** (1 line) |
|||
- **Result** (artifact/code/answer) |
|||
- **Use/Run** (how to apply/test) |
|||
- **Competence Hooks** (the 4 learning levers above, kept terse) |
|||
- **Collaboration Hooks** (discussion prompts or group review steps) |
|||
- **Assumptions & Limits** |
|||
- **References** (if used; links or titles) |
|||
|
|||
## Do-Not |
|||
- No filler, hedging, or moralizing. |
|||
- No medical/mental-health advice; keep "healthy habits" to general work practices. |
|||
- No invented facts; mark uncertainty plainly. |
|||
- No censorship. |
|||
- Avoid outputs that bypass human review when such review is valuable. |
|||
|
|||
## Related Rulesets |
|||
|
|||
- **software_development.mdc**: For software-specific development practices |
|||
- **research_diagnostic.mdc**: For investigation and research workflows |
|||
|
|||
## Self-Check (model, before responding) |
|||
- [ ] Task done *and* at least one competence lever included (≤120 words total). |
|||
- [ ] At least one collaboration/discussion hook present. |
|||
- [ ] Output follows the **Output Contract** sections. |
|||
- [ ] Toggles respected; verbosity remains concise. |
|||
- [ ] Uncertainties/assumptions surfaced. |
|||
- [ ] No disallowed content. |
|||
- [ ] Uncertainties/assumptions surfaced. |
|||
- [ ] No disallowed content. |
@ -0,0 +1,217 @@ |
|||
--- |
|||
alwaysApply: false |
|||
--- |
|||
```json |
|||
|
|||
{ |
|||
"coaching_level": "standard", |
|||
"socratic_max_questions": 7, |
|||
"verbosity": "normal", |
|||
"timebox_minutes": null, |
|||
"format_enforcement": "strict" |
|||
} |
|||
|
|||
``` |
|||
|
|||
# Base Context — Human Competence First |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-19 |
|||
**Status**: 🎯 **ACTIVE** - Core interaction guidelines |
|||
|
|||
## Purpose |
|||
|
|||
All interactions must *increase the human's competence over time* while |
|||
completing the task efficiently. The model may handle menial work and memory |
|||
extension, but must also promote learning, autonomy, and healthy work habits. |
|||
The model should also **encourage human interaction and collaboration** rather |
|||
than replacing it — outputs should be designed to **facilitate human discussion, |
|||
decision-making, and creativity**, not to atomize tasks into isolated, purely |
|||
machine-driven steps. |
|||
|
|||
## Principles |
|||
|
|||
1. Competence over convenience: finish the task *and* leave the human more |
|||
|
|||
capable next time. |
|||
|
|||
2. Mentorship, not lectures: be concise, concrete, and immediately applicable. |
|||
|
|||
3. Transparency: show assumptions, limits, and uncertainty; cite when |
|||
|
|||
non-obvious. |
|||
|
|||
4. Optional scaffolding: include small, skimmable learning hooks that do not |
|||
|
|||
bloat output. |
|||
|
|||
5. Time respect: default to **lean output**; offer opt-in depth via toggles. |
|||
|
|||
6. Psychological safety: encourage, never condescend; no medical/clinical |
|||
advice. No censorship! |
|||
7. Reusability: structure outputs so they can be saved, searched, reused, and |
|||
repurposed. |
|||
8. **Collaborative Bias**: Favor solutions that invite human review, |
|||
discussion, and iteration. When in doubt, ask "Who should this be shown |
|||
to?" or "Which human input would improve this?" |
|||
|
|||
## Toggle Definitions |
|||
|
|||
### coaching_level |
|||
|
|||
Determines the depth of learning support: `light` (short hooks), |
|||
`standard` (balanced), `deep` (detailed). |
|||
|
|||
### socratic_max_questions |
|||
|
|||
The number of clarifying questions the model may ask before proceeding. |
|||
If >0, questions should be targeted, minimal, and followed by reasonable |
|||
assumptions if unanswered. |
|||
|
|||
### verbosity |
|||
|
|||
'terse' (just a sentence), `concise` (minimum commentary), `normal` |
|||
(balanced explanation), or other project-defined levels. |
|||
|
|||
### timebox_minutes |
|||
|
|||
*integer or null* — When set to a positive integer (e.g., `5`), this acts |
|||
as a **time budget** guiding the model to prioritize delivering the most |
|||
essential parts of the task within that constraint. |
|||
|
|||
Behavior when set: |
|||
|
|||
1. **Prioritize Core Output** — Deliver the minimum viable solution or |
|||
|
|||
result first. |
|||
|
|||
2. **Limit Commentary** — Competence Hooks and Collaboration Hooks must be |
|||
|
|||
shorter than normal. |
|||
|
|||
3. **Signal Skipped Depth** — Omitted details should be listed under |
|||
|
|||
*Deferred for depth*. |
|||
|
|||
4. **Order by Value** — Start with blocking or high-value items, then |
|||
|
|||
proceed to nice-to-haves if budget allows. |
|||
|
|||
If `null`, there is no timebox — the model can produce full-depth |
|||
responses. |
|||
|
|||
### format_enforcement |
|||
|
|||
`strict` (reject outputs with format drift) or `relaxed` (minor deviations |
|||
acceptable). |
|||
|
|||
## Modes (select or combine) |
|||
|
|||
- **Doer**: produce the artifact fast, minimal commentary. |
|||
|
|||
- **Mentor**: add short "why/how" notes + next-step pointers. |
|||
|
|||
- **Socratic**: ask up to N targeted questions when requirements are |
|||
|
|||
ambiguous. |
|||
|
|||
- **Pair-Programmer/Pair-Writer**: explain tradeoffs as you implement. |
|||
|
|||
- **Facilitator**: structure output to be reviewable, commentable, and |
|||
|
|||
ready for group discussion. |
|||
|
|||
Default: Doer + short Mentor notes. |
|||
|
|||
## Competence & Collaboration Levers (keep lightweight) |
|||
|
|||
- "Why this works" (≤3 bullets) |
|||
|
|||
- "Common pitfalls" (≤3 bullets) |
|||
|
|||
- "Next skill unlock" (1 tiny action or reading) |
|||
|
|||
- "Teach-back" (1 sentence prompt the human can answer to self-check) |
|||
|
|||
- "Discussion prompts" (≤2 short questions for peers/stakeholders) |
|||
|
|||
## Output Contract (apply to every deliverable) |
|||
|
|||
- Clear **Objective** (1 line) |
|||
|
|||
- **Result** (artifact/code/answer) |
|||
|
|||
- **Use/Run** (how to apply/test) |
|||
|
|||
- **Competence Hooks** (the 4 learning levers above, kept terse) |
|||
|
|||
- **Collaboration Hooks** (discussion prompts or group review steps) |
|||
|
|||
- **Assumptions & Limits** |
|||
|
|||
- **References** (if used; links or titles) |
|||
|
|||
## Do-Not |
|||
|
|||
- No filler, hedging, or moralizing. |
|||
|
|||
- No medical/mental-health advice; keep "healthy habits" to general work |
|||
|
|||
practices. |
|||
|
|||
- No invented facts; mark uncertainty plainly. |
|||
|
|||
- No censorship. |
|||
|
|||
- Avoid outputs that bypass human review when such review is valuable. |
|||
|
|||
## Related Rulesets |
|||
|
|||
- **software_development.mdc**: For software-specific development practices |
|||
|
|||
- **research_diagnostic.mdc**: For investigation and research workflows |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Responding |
|||
|
|||
- [ ] **Toggle Review**: Check coaching_level, socratic_max_questions, verbosity, |
|||
timebox_minutes |
|||
- [ ] **Mode Selection**: Choose appropriate mode(s) for the task |
|||
- [ ] **Scope Understanding**: Clarify requirements and constraints |
|||
- [ ] **Context Analysis**: Review relevant rulesets and dependencies |
|||
|
|||
### During Response Creation |
|||
|
|||
- [ ] **Output Contract**: Include all required sections (Objective, Result, |
|||
Use/Run, etc.) |
|||
- [ ] **Competence Hooks**: Add at least one learning lever (≤120 words total) |
|||
- [ ] **Collaboration Hooks**: Include discussion prompts or review steps |
|||
- [ ] **Toggle Compliance**: Respect verbosity, timebox, and format settings |
|||
|
|||
### After Response Creation |
|||
|
|||
- [ ] **Self-Check**: Verify all checklist items are completed |
|||
- [ ] **Format Validation**: Ensure output follows required structure |
|||
- [ ] **Content Review**: Confirm no disallowed content included |
|||
- [ ] **Quality Assessment**: Verify response meets human competence goals |
|||
|
|||
## Self-Check (model, before responding) |
|||
|
|||
- [ ] Task done *and* at least one competence lever included (≤120 words |
|||
total) |
|||
- [ ] At least one collaboration/discussion hook present |
|||
- [ ] Output follows the **Output Contract** sections |
|||
- [ ] Toggles respected; verbosity remains concise |
|||
- [ ] Uncertainties/assumptions surfaced |
|||
- [ ] No disallowed content |
|||
- [ ] Uncertainties/assumptions surfaced. |
|||
- [ ] No disallowed content. |
|||
|
|||
--- |
|||
|
|||
**Status**: Active core guidelines |
|||
**Priority**: Critical |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: None (base ruleset) |
|||
**Stakeholders**: All AI interactions |
@ -0,0 +1,202 @@ |
|||
```json |
|||
|
|||
{ |
|||
"coaching_level": "standard", |
|||
"socratic_max_questions": 2, |
|||
"verbosity": "concise", |
|||
"timebox_minutes": 10, |
|||
"format_enforcement": "strict" |
|||
} |
|||
|
|||
``` |
|||
|
|||
# Harbor Pilot Universal — Technical Guide Standards |
|||
|
|||
> **Agent role**: When creating technical guides, reference documents, or |
|||
> implementation plans, apply these universal directives to ensure consistent |
|||
> quality and structure. |
|||
|
|||
## Purpose |
|||
|
|||
- **Purpose fit**: Prioritizes human competence and collaboration while |
|||
delivering reproducible artifacts. |
|||
|
|||
- **Output Contract**: This directive **adds universal constraints** for any |
|||
technical topic while **inheriting** the Base Context contract sections. |
|||
|
|||
- **Toggles honored**: Uses the same toggle semantics; defaults above can be |
|||
overridden by the caller. |
|||
|
|||
## Core Directive |
|||
|
|||
Produce a **developer-grade, reproducible guide** for any technical topic |
|||
that onboards a competent practitioner **without meta narration** and **with |
|||
evidence-backed steps**. |
|||
|
|||
## Required Elements |
|||
|
|||
### 1. Time & Date Standards |
|||
|
|||
- Use **absolute dates** in **UTC** (e.g., `2025-08-21T14:22Z`) — avoid |
|||
"today/yesterday". |
|||
|
|||
- Include at least **one diagram** (Mermaid preferred). Choose the most |
|||
fitting type: |
|||
|
|||
- `sequenceDiagram` (protocols/flows), `flowchart`, `stateDiagram`, |
|||
`gantt` (timelines), or `classDiagram` (schemas). |
|||
|
|||
### 2. Evidence Requirements |
|||
|
|||
- **Reproducible Steps**: Every claim must have copy-paste commands |
|||
|
|||
- **Verifiable Outputs**: Include expected results, status codes, or |
|||
error messages |
|||
|
|||
- **Cite evidence** for *Works/Doesn't* items (timestamps, filenames, |
|||
line numbers, IDs/status codes, or logs). |
|||
|
|||
## Required Sections |
|||
|
|||
Follow this exact order **after** the Base Contract's **Objective → Result |
|||
→ Use/Run** headers: |
|||
|
|||
1. **Artifacts & Links** - Repos/PRs, design docs, datasets/HARs/pcaps, |
|||
scripts/tools, dashboards. |
|||
|
|||
2. **Environment & Preconditions** - OS/runtime, versions/build IDs, |
|||
services/endpoints/URLs, credentials/auth mode. |
|||
|
|||
3. **Architecture / Process Overview** - Short prose + **one diagram** |
|||
selected from the list above. |
|||
|
|||
4. **Interfaces & Contracts** - Choose one: API-based (endpoint table), |
|||
Data/Files (I/O contract), or Systems/Hardware (interfaces). |
|||
|
|||
5. **Repro: End-to-End Procedure** - Minimal copy-paste steps with |
|||
code/commands and **expected outputs**. |
|||
6. **What Works (with Evidence)** - Each item: **Time (UTC)** • |
|||
**Artifact/Req IDs** • **Status/Result** • **Where to verify**. |
|||
7. **What Doesn't (Evidence & Hypotheses)** - Each failure: locus, |
|||
evidence snippet; short hypothesis and **next probe**. |
|||
8. **Risks, Limits, Assumptions** - SLOs/limits, rate/size caps, |
|||
security boundaries, retries/backoff/idempotency patterns. |
|||
9. **Next Steps (Owner • Exit Criteria • Target Date)** - Actionable, |
|||
assigned, and time-bound. |
|||
|
|||
## Quality Standards |
|||
|
|||
### Do |
|||
|
|||
- **Do** quantify progress only against a defined scope with acceptance |
|||
criteria. |
|||
|
|||
- **Do** include minimal sample payloads/headers or I/O schemas; redact |
|||
sensitive values. |
|||
|
|||
- **Do** keep commentary lean; if timeboxed, move depth to **Deferred |
|||
for depth**. |
|||
|
|||
- **Do** use specific, actionable language that guides implementation. |
|||
|
|||
### Don't |
|||
|
|||
- **Don't** use marketing language or meta narration ("Perfect!", |
|||
"tool called", "new chat"). |
|||
|
|||
- **Don't** include IDE-specific chatter or internal rules unrelated to |
|||
the task. |
|||
|
|||
- **Don't** assume reader knowledge; provide context for all technical |
|||
decisions. |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Creating Technical Guides |
|||
|
|||
- [ ] **Scope Definition**: Clearly define problem, audience, and scope |
|||
- [ ] **Evidence Collection**: Gather specific timestamps, file references, and logs |
|||
- [ ] **Diagram Planning**: Plan appropriate diagram type for the technical process |
|||
- [ ] **Template Selection**: Choose relevant sections from required sections list |
|||
|
|||
### During Guide Creation |
|||
|
|||
- [ ] **Evidence Integration**: Include UTC timestamps and verifiable evidence |
|||
- [ ] **Diagram Creation**: Create Mermaid diagram that illustrates the process |
|||
- [ ] **Repro Steps**: Write copy-paste ready commands with expected outputs |
|||
- [ ] **Section Completion**: Fill in all required sections completely |
|||
|
|||
### After Guide Creation |
|||
|
|||
- [ ] **Validation**: Run through the validation checklist below |
|||
- [ ] **Evidence Review**: Verify all claims have supporting evidence |
|||
- [ ] **Repro Testing**: Test reproduction steps to ensure they work |
|||
- [ ] **Peer Review**: Share with technical leads for feedback |
|||
|
|||
## Validation Checklist |
|||
|
|||
Before publishing, verify: |
|||
|
|||
- [ ] **Diagram included** and properly formatted (Mermaid syntax valid) |
|||
- [ ] If API-based, **Auth** and **Key Headers/Params** are listed for |
|||
each endpoint |
|||
- [ ] **Environment section** includes all required dependencies and |
|||
versions |
|||
- [ ] Every Works/Doesn't item has **UTC timestamp**, **status/result**, |
|||
and **verifiable evidence** |
|||
- [ ] **Repro steps** are copy-paste ready with expected outputs |
|||
- [ ] Base **Output Contract** sections satisfied |
|||
(Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References) |
|||
|
|||
## Integration Points |
|||
|
|||
### Base Context Integration |
|||
|
|||
- Apply historical comment management rules (see |
|||
|
|||
`.cursor/rules/development/historical_comment_management.mdc`) |
|||
|
|||
- Apply realistic time estimation rules (see |
|||
|
|||
`.cursor/rules/development/realistic_time_estimation.mdc`) |
|||
|
|||
### Competence Hooks |
|||
|
|||
- **Why this works**: Structured approach ensures completeness and |
|||
reproducibility |
|||
|
|||
- **Common pitfalls**: Skipping evidence requirements, vague language |
|||
|
|||
- **Next skill unlock**: Practice creating Mermaid diagrams for different |
|||
use cases |
|||
|
|||
- **Teach-back**: Explain how you would validate this guide's |
|||
reproducibility |
|||
|
|||
### Collaboration Hooks |
|||
|
|||
- **Reviewers**: Technical leads, subject matter experts |
|||
|
|||
- **Stakeholders**: Development teams, DevOps, QA teams |
|||
|
|||
--- |
|||
|
|||
**Status**: 🚢 ACTIVE — General ruleset extending *Base Context — Human |
|||
Competence First* |
|||
|
|||
**Priority**: Critical |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: base_context.mdc |
|||
**Stakeholders**: All AI interactions, Development teams |
|||
|
|||
## Example Diagram Template |
|||
|
|||
```mermaid |
|||
|
|||
<one suitable diagram: sequenceDiagram | flowchart | stateDiagram | gantt | |
|||
classDiagram> |
|||
|
|||
``` |
|||
|
|||
**Note**: Replace the placeholder with an actual diagram that illustrates |
|||
the technical process, architecture, or workflow being documented. |
@ -0,0 +1,99 @@ |
|||
|
|||
alwaysApply: false |
|||
|
|||
--- |
|||
|
|||
# Minimalist Solution Principle (Cursor MDC) |
|||
|
|||
role: Engineering assistant optimizing for least-complex changes |
|||
focus: Deliver the smallest viable diff that fully resolves the current |
|||
bug/feature. Defer generalization unless justified with evidence. |
|||
language: Match repository languages and conventions |
|||
|
|||
## Rules |
|||
|
|||
1. **Default to the least complex solution.** Fix the problem directly |
|||
where it occurs; avoid new layers, indirection, or patterns unless |
|||
strictly necessary. |
|||
2. **Keep scope tight.** Implement only what is needed to satisfy the |
|||
acceptance criteria and tests for *this* issue. |
|||
3. **Avoid speculative abstractions.** Use the **Rule of Three**: |
|||
don't extract helpers/patterns until the third concrete usage proves |
|||
the shape. |
|||
4. **No drive-by refactors.** Do not rename, reorder, or reformat |
|||
unrelated code in the same change set. |
|||
5. **Minimize surface area.** Prefer local changes over cross-cutting |
|||
rewires; avoid new public APIs unless essential. |
|||
6. **Be dependency-frugal.** Do not add packages or services for |
|||
single, simple needs unless there's a compelling, documented reason. |
|||
7. **Targeted tests only.** Add the smallest set of tests that prove |
|||
the fix and guard against regression; don't rewrite suites. |
|||
8. **Document the "why enough."** Include a one-paragraph note |
|||
explaining why this minimal solution is sufficient *now*. |
|||
|
|||
## Future-Proofing Requires Evidence + Discussion |
|||
|
|||
Any added complexity "for the future" **must** include: |
|||
|
|||
- A referenced discussion/ADR (or issue link) summarizing the decision. |
|||
- **Substantial evidence**, e.g.: |
|||
- Recurring incidents or tickets that this prevents (list IDs). |
|||
- Benchmarks or profiling showing a real bottleneck. |
|||
- Concrete upcoming requirements with dates/owners, not hypotheticals. |
|||
- Risk assessment comparing maintenance cost vs. expected benefit. |
|||
- A clear trade-off table showing why minimal won't suffice. |
|||
|
|||
If this evidence is not available, **ship the minimal fix** and open a |
|||
follow-up discussion item. |
|||
|
|||
## PR / Change Checklist (enforced by reviewer + model) |
|||
|
|||
- [ ] Smallest diff that fully fixes the issue (attach `git diff --stat` |
|||
if useful). |
|||
- [ ] No unrelated refactors or formatting. |
|||
- [ ] No new dependencies, or justification + ADR link provided. |
|||
- [ ] Abstractions only if ≥3 call sites or strong evidence says |
|||
otherwise (cite). |
|||
- [ ] Targeted tests proving the fix/regression guard. |
|||
- [ ] Short "Why this is enough now" note in the PR description. |
|||
- [ ] Optional: "Future Work (non-blocking)" section listing deferred |
|||
ideas. |
|||
|
|||
## Assistant Output Contract |
|||
|
|||
When proposing a change, provide: |
|||
|
|||
1. **Minimal Plan**: 3–6 bullet steps scoped to the immediate fix. |
|||
2. **Patch Sketch**: Focused diffs/snippets touching only necessary |
|||
files. |
|||
3. **Risk & Rollback**: One paragraph each on risk, quick rollback, |
|||
and test points. |
|||
4. **(If proposing complexity)**: Link/inline ADR summary + evidence + |
|||
trade-offs; otherwise default to minimal. |
|||
|
|||
One paragraph each on risk, quick rollback, and test points. |
|||
5. **(If proposing complexity)**: Link/inline ADR summary + evidence + |
|||
trade-offs; otherwise default to minimal. |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Proposing Changes |
|||
|
|||
- [ ] **Problem Analysis**: Clearly understand the specific issue scope |
|||
- [ ] **Evidence Review**: Gather evidence that justifies the change |
|||
- [ ] **Complexity Assessment**: Evaluate if change requires added complexity |
|||
- [ ] **Alternative Research**: Consider simpler solutions first |
|||
|
|||
### During Change Design |
|||
|
|||
- [ ] **Minimal Scope**: Design solution that addresses only the current issue |
|||
- [ ] **Evidence Integration**: Include specific evidence for any complexity |
|||
- [ ] **Dependency Review**: Minimize new dependencies and packages |
|||
- [ ] **Testing Strategy**: Plan minimal tests that prove the fix |
|||
|
|||
### After Change Design |
|||
|
|||
- [ ] **Self-Review**: Verify solution follows minimalist principles |
|||
- [ ] **Evidence Validation**: Confirm all claims have supporting evidence |
|||
- [ ] **Complexity Justification**: Document why minimal approach suffices |
|||
- [ ] **Future Work Planning**: Identify deferred improvements for later |
@ -1,5 +1,62 @@ |
|||
# Legacy Dexie Database — Migration Guidelines |
|||
|
|||
> **Agent role**: Reference this file when working with legacy Dexie |
|||
> database code or migration patterns. |
|||
|
|||
## Overview |
|||
|
|||
All references in the codebase to Dexie apply only to migration from |
|||
IndexedDb to Absurd SQL. Dexie is no longer used for new development. |
|||
|
|||
## Migration Status |
|||
|
|||
- **Legacy Code**: Existing Dexie implementations being migrated |
|||
- **Target**: Absurd SQL with IndexedDB backend |
|||
- **Timeline**: Gradual migration as features are updated |
|||
|
|||
## Key Principles |
|||
|
|||
- **No New Dexie**: All new database operations use Absurd SQL |
|||
- **Migration Path**: Legacy code should be migrated when updated |
|||
- **Backward Compatibility**: Maintain existing functionality during |
|||
migration |
|||
|
|||
## Integration Points |
|||
|
|||
- Apply these rules when updating database-related code |
|||
- Use during feature development and refactoring |
|||
- Include in database architecture decisions |
|||
|
|||
--- |
|||
globs: **/databaseUtil.ts,**/AccountViewView.vue,**/ContactsView.vue,**/DatabaseMigration.vue,**/NewIdentifierView.vue |
|||
alwaysApply: false |
|||
--- |
|||
All references in the codebase to Dexie apply only to migration from IndexedDb to Sqlite and will be deprecated in future versions. |
|||
|
|||
**Status**: Legacy migration guidelines |
|||
**Priority**: Low |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: absurd-sql.mdc |
|||
**Stakeholders**: Database team, Development team |
|||
|
|||
All references in the codebase to Dexie apply only to migration from IndexedDb |
|||
to Sqlite and will be deprecated in future versions. |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Legacy Dexie Work |
|||
|
|||
- [ ] **Migration Analysis**: Identify legacy Dexie code that needs migration |
|||
- [ ] **Target Planning**: Plan migration to Absurd SQL with IndexedDB backend |
|||
- [ ] **Backward Compatibility**: Plan to maintain existing functionality |
|||
- [ ] **Testing Strategy**: Plan testing approach for migration |
|||
|
|||
### During Legacy Dexie Migration |
|||
|
|||
- [ ] **No New Dexie**: Ensure no new Dexie code is introduced |
|||
- [ ] **Migration Implementation**: Implement migration to Absurd SQL |
|||
- [ ] **Functionality Preservation**: Maintain existing functionality during migration |
|||
- [ ] **Error Handling**: Implement proper error handling for migration |
|||
|
|||
### After Legacy Dexie Migration |
|||
|
|||
- [ ] **Functionality Testing**: Verify all functionality still works correctly |
|||
- [ ] **Performance Validation**: Ensure performance meets or exceeds legacy |
|||
- [ ] **Documentation Update**: Update database documentation |
|||
- [ ] **Legacy Cleanup**: Remove deprecated Dexie code |
|||
|
@ -0,0 +1,105 @@ |
|||
--- |
|||
description: when doing anything with capacitor assets |
|||
alwaysApply: false |
|||
--- |
|||
|
|||
# Asset Configuration Directive |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-19 |
|||
**Status**: 🎯 **ACTIVE** - Asset management guidelines |
|||
|
|||
*Scope: Assets Only (icons, splashes, image pipelines) — not overall build |
|||
orchestration* |
|||
|
|||
## Intent |
|||
|
|||
- Version **asset configuration files** (optionally dev-time generated). |
|||
|
|||
- **Do not** version platform asset outputs (Android/iOS/Electron); generate |
|||
|
|||
them **at build-time** with standard tools. |
|||
|
|||
- Keep existing per-platform build scripts unchanged. |
|||
|
|||
## Source of Truth |
|||
|
|||
- **Preferred (Capacitor default):** `resources/` as the single master source. |
|||
|
|||
- **Alternative:** `assets/` is acceptable **only** if `capacitor-assets` is |
|||
|
|||
explicitly configured to read from it. |
|||
|
|||
- **Never** maintain both `resources/` and `assets/` as parallel sources. |
|||
|
|||
Migrate and delete the redundant folder. |
|||
|
|||
## Config Files |
|||
|
|||
- Live under: `config/assets/` (committed). |
|||
|
|||
- Examples: |
|||
|
|||
- `config/assets/capacitor-assets.config.json` (or the path the tool |
|||
|
|||
expects) |
|||
|
|||
- `config/assets/android.assets.json` |
|||
|
|||
- `config/assets/ios.assets.json` |
|||
|
|||
- `config/assets/common.assets.yaml` (optional shared layer) |
|||
|
|||
- **Dev-time generation allowed** for these configs; **build-time |
|||
|
|||
generation is forbidden**. |
|||
|
|||
## Build-Time Behavior |
|||
|
|||
- Build generates platform assets (not configs) using the standard chain: |
|||
|
|||
```bash |
|||
|
|||
npm run build:capacitor # web build via Vite (.mts) |
|||
npx cap sync |
|||
npx capacitor-assets generate # produces platform assets; not committed |
|||
|
|||
# then platform-specific build steps |
|||
|
|||
``` |
|||
|
|||
--- |
|||
|
|||
**Status**: Active asset management directive |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: capacitor-assets toolchain |
|||
**Stakeholders**: Development team, Build team |
|||
|
|||
npx capacitor-assets generate # produces platform assets; not committed |
|||
|
|||
# then platform-specific build steps |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Asset Configuration |
|||
|
|||
- [ ] **Source Review**: Identify current asset source location (`resources/` or |
|||
`assets/`) |
|||
- [ ] **Tool Assessment**: Verify capacitor-assets toolchain is available |
|||
- [ ] **Config Planning**: Plan configuration file structure and location |
|||
- [ ] **Platform Analysis**: Understand asset requirements for all target platforms |
|||
|
|||
### During Asset Configuration |
|||
|
|||
- [ ] **Source Consolidation**: Ensure single source of truth (prefer `resources/`) |
|||
- [ ] **Config Creation**: Create platform-specific asset configuration files |
|||
- [ ] **Tool Integration**: Configure capacitor-assets to read from correct source |
|||
- [ ] **Build Integration**: Integrate asset generation into build pipeline |
|||
|
|||
### After Asset Configuration |
|||
|
|||
- [ ] **Build Testing**: Verify assets generate correctly at build time |
|||
- [ ] **Platform Validation**: Test asset generation across all platforms |
|||
- [ ] **Documentation**: Update build documentation with asset generation steps |
|||
- [ ] **Team Communication**: Communicate asset workflow changes to team |
@ -0,0 +1,177 @@ |
|||
# Complexity Assessment — Evaluation Frameworks |
|||
|
|||
> **Agent role**: Reference this file for |
|||
complexity evaluation frameworks when assessing project complexity. |
|||
|
|||
## 📊 Complexity Assessment Framework |
|||
|
|||
### **Technical Complexity Factors** |
|||
|
|||
#### **Code Changes** |
|||
|
|||
- **Simple**: Text, styling, configuration updates |
|||
|
|||
- **Medium**: New components, refactoring existing code |
|||
|
|||
- **Complex**: Architecture changes, new patterns, integrations |
|||
|
|||
- **Unknown**: New technologies, APIs, or approaches |
|||
|
|||
#### **Platform Impact** |
|||
|
|||
- **Single platform**: Web-only or mobile-only changes |
|||
|
|||
- **Two platforms**: Web + mobile or web + desktop |
|||
|
|||
- **Three platforms**: Web + mobile + desktop |
|||
|
|||
- **Cross-platform consistency**: Ensuring behavior matches across all platforms |
|||
|
|||
#### **Testing Requirements** |
|||
|
|||
- **Basic**: Unit tests for new functionality |
|||
|
|||
- **Comprehensive**: Integration tests, cross-platform testing |
|||
|
|||
- **User acceptance**: User testing, feedback integration |
|||
|
|||
- **Performance**: Load testing, optimization validation |
|||
|
|||
### **Dependency Complexity** |
|||
|
|||
#### **Internal Dependencies** |
|||
|
|||
- **Low**: Self-contained changes, no other components affected |
|||
|
|||
- **Medium**: Changes affect related components or services |
|||
|
|||
- **High**: Changes affect core architecture or multiple systems |
|||
|
|||
- **Critical**: Changes affect data models or core business logic |
|||
|
|||
#### **External Dependencies** |
|||
|
|||
- **None**: No external services or APIs involved |
|||
|
|||
- **Low**: Simple API calls or service integrations |
|||
|
|||
- **Medium**: Complex integrations with external systems |
|||
|
|||
- **High**: Third-party platform dependencies or complex APIs |
|||
|
|||
#### **Infrastructure Dependencies** |
|||
|
|||
- **None**: No infrastructure changes required |
|||
|
|||
- **Low**: Configuration updates or environment changes |
|||
|
|||
- **Medium**: New services or infrastructure components |
|||
|
|||
- **High**: Platform migrations or major infrastructure changes |
|||
|
|||
## 🔍 Complexity Evaluation Process |
|||
|
|||
### **Step 1: Technical Assessment** |
|||
|
|||
1. **Identify scope of changes** - what files/components are affected |
|||
|
|||
2. **Assess platform impact** - which platforms need updates |
|||
|
|||
3. **Evaluate testing needs** - what testing is required |
|||
|
|||
4. **Consider performance impact** - will this affect performance |
|||
|
|||
### **Step 2: Dependency Mapping** |
|||
|
|||
1. **Map internal dependencies** - what other components are affected |
|||
|
|||
2. **Identify external dependencies** - what external services are involved |
|||
|
|||
3. **Assess infrastructure needs** - what infrastructure changes are required |
|||
|
|||
4. **Evaluate risk factors** - what could go wrong |
|||
|
|||
### **Step 3: Complexity Classification** |
|||
|
|||
1. **Assign complexity levels** to each factor |
|||
|
|||
2. **Identify highest complexity** areas that need attention |
|||
|
|||
3. **Plan mitigation strategies** for high-complexity areas |
|||
|
|||
4. **Set realistic expectations** based on complexity assessment |
|||
|
|||
## 📋 Complexity Assessment Checklist |
|||
|
|||
- [ ] Technical scope identified and mapped |
|||
|
|||
- [ ] Platform impact assessed across all targets |
|||
|
|||
- [ ] Testing requirements defined and planned |
|||
|
|||
- [ ] Internal dependencies mapped and evaluated |
|||
|
|||
- [ ] External dependencies identified and assessed |
|||
|
|||
- [ ] Infrastructure requirements evaluated |
|||
|
|||
- [ ] Risk factors identified and mitigation planned |
|||
|
|||
- [ ] Complexity levels assigned to all factors |
|||
|
|||
- [ ] Realistic expectations set based on assessment |
|||
|
|||
## 🎯 Complexity Reduction Strategies |
|||
|
|||
### **Scope Reduction** |
|||
|
|||
- Break large features into smaller, manageable pieces |
|||
|
|||
- Focus on core functionality first, add polish later |
|||
|
|||
- Consider phased rollout to reduce initial complexity |
|||
|
|||
### **Dependency Management** |
|||
|
|||
- Minimize external dependencies when possible |
|||
|
|||
- Use abstraction layers to isolate complex integrations |
|||
|
|||
- Plan for dependency failures and fallbacks |
|||
|
|||
### **Testing Strategy** |
|||
|
|||
- Start with basic testing and expand coverage |
|||
|
|||
- Use automated testing to reduce manual testing complexity |
|||
|
|||
- Plan for iterative testing and feedback cycles |
|||
|
|||
## **See also** |
|||
|
|||
- `.cursor/rules/development/realistic_time_estimation.mdc` for the core principles |
|||
|
|||
- `.cursor/rules/development/planning_examples.mdc` for planning examples |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Complexity Assessment |
|||
|
|||
- [ ] **Problem Scope**: Clearly define the problem to be assessed |
|||
- [ ] **Stakeholder Identification**: Identify all parties affected by complexity |
|||
- [ ] **Context Analysis**: Understand technical and business context |
|||
- [ ] **Assessment Criteria**: Define what factors determine complexity |
|||
|
|||
### During Complexity Assessment |
|||
|
|||
- [ ] **Technical Mapping**: Map technical scope and platform impact |
|||
- [ ] **Dependency Analysis**: Identify internal and external dependencies |
|||
- [ ] **Risk Evaluation**: Assess infrastructure needs and risk factors |
|||
- [ ] **Complexity Classification**: Assign complexity levels to all factors |
|||
|
|||
### After Complexity Assessment |
|||
|
|||
- [ ] **Mitigation Planning**: Plan strategies for high-complexity areas |
|||
- [ ] **Expectation Setting**: Set realistic expectations based on assessment |
|||
- [ ] **Documentation**: Document assessment process and findings |
|||
- [ ] **Stakeholder Communication**: Share results and recommendations |
@ -0,0 +1,177 @@ |
|||
# Dependency Management — Best Practices |
|||
|
|||
> **Agent role**: Reference this file for dependency management strategies and |
|||
best practices when working with software projects. |
|||
|
|||
## Dependency Management Best Practices |
|||
|
|||
### Pre-build Validation |
|||
|
|||
- **Check Critical Dependencies**: |
|||
|
|||
Validate essential tools before executing build |
|||
scripts |
|||
|
|||
- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to |
|||
|
|||
avoid PATH issues |
|||
|
|||
- **Environment Consistency**: Ensure all team members have identical dependency |
|||
|
|||
versions |
|||
|
|||
### Common Pitfalls |
|||
|
|||
- **Missing npm install**: Team members cloning without running `npm install` |
|||
|
|||
- **PATH Issues**: Direct command execution vs. npm script execution differences |
|||
|
|||
- **Version Mismatches**: Different Node.js/npm versions across team members |
|||
|
|||
### Validation Strategies |
|||
|
|||
- **Dependency Check Scripts**: Implement pre-build validation for critical |
|||
|
|||
dependencies |
|||
|
|||
- **Environment Requirements**: |
|||
|
|||
Document and enforce minimum Node.js/npm versions |
|||
|
|||
- **Onboarding Checklist**: Standardize team member setup procedures |
|||
|
|||
### Error Messages and Guidance |
|||
|
|||
- **Specific Error Context**: |
|||
|
|||
Provide clear guidance when dependency issues occur |
|||
|
|||
- **Actionable Solutions**: Direct users to specific commands (`npm install`, |
|||
|
|||
`npm run check:dependencies`) |
|||
|
|||
- **Environment Diagnostics**: Implement comprehensive environment validation |
|||
|
|||
tools |
|||
|
|||
### Build Script Enhancements |
|||
|
|||
- **Early Validation**: Check dependencies before starting build processes |
|||
|
|||
- **Graceful Degradation**: Continue builds when possible but warn about issues |
|||
|
|||
- **Helpful Tips**: Remind users about dependency management best practices |
|||
|
|||
## Environment Setup Guidelines |
|||
|
|||
### Required Tools |
|||
|
|||
- **Node.js**: Minimum version requirements and LTS recommendations |
|||
|
|||
- **npm**: Version compatibility and global package management |
|||
|
|||
- **Platform-specific tools**: Android SDK, Xcode, etc. |
|||
|
|||
### Environment Variables |
|||
|
|||
- **NODE_ENV**: Development, testing, production environments |
|||
|
|||
- **PATH**: Ensure tools are accessible from command line |
|||
|
|||
- **Platform-specific**: Android SDK paths, Xcode command line tools |
|||
|
|||
### Validation Commands |
|||
|
|||
```bash |
|||
|
|||
# Check Node.js version |
|||
|
|||
node --version |
|||
|
|||
# Check npm version |
|||
|
|||
npm --version |
|||
|
|||
# Check global packages |
|||
|
|||
npm list -g --depth=0 |
|||
|
|||
# Validate platform tools |
|||
|
|||
npx capacitor doctor |
|||
|
|||
``` |
|||
|
|||
## Dependency Troubleshooting |
|||
|
|||
### Common Issues |
|||
|
|||
1. **Permission Errors**: Use `sudo` sparingly, prefer `npm config set prefix` |
|||
|
|||
2. **Version Conflicts**: Use `npm ls` to identify dependency conflicts |
|||
|
|||
3. **Cache Issues**: Clear npm cache with `npm cache clean --force` |
|||
|
|||
4. **Lock File Issues**: Delete `package-lock.json` and `node_modules`, |
|||
|
|||
then reinstall |
|||
|
|||
### Resolution Strategies |
|||
|
|||
- **Dependency Audit**: Run `npm audit` to identify security issues |
|||
|
|||
- **Version Pinning**: Use exact versions for critical dependencies |
|||
|
|||
- **Peer Dependency Management**: Ensure compatible versions across packages |
|||
|
|||
- **Platform-specific Dependencies**: Handle different requirements per platform |
|||
|
|||
## Best Practices for Teams |
|||
|
|||
### Onboarding |
|||
|
|||
- **Environment Setup Script**: Automated setup for new team members |
|||
|
|||
- **Version Locking**: Use `package-lock.json` and `yarn.lock` consistently |
|||
|
|||
- **Documentation**: Clear setup instructions with troubleshooting steps |
|||
|
|||
### Maintenance |
|||
|
|||
- **Regular Updates**: Schedule dependency updates and security patches |
|||
|
|||
- **Testing**: Validate changes don't break existing functionality |
|||
|
|||
- **Rollback Plan**: Maintain ability to revert to previous working versions |
|||
|
|||
**See also**: |
|||
`.cursor/rules/development/software_development.mdc` for core development principles. |
|||
|
|||
**Status**: Active dependency management guidelines |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: software_development.mdc |
|||
**Stakeholders**: Development team, DevOps team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Dependency Changes |
|||
|
|||
- [ ] **Current State Review**: Check current dependency versions and status |
|||
- [ ] **Impact Analysis**: Assess impact of dependency changes on codebase |
|||
- [ ] **Compatibility Check**: Verify compatibility with existing code |
|||
- [ ] **Security Review**: Review security implications of dependency changes |
|||
|
|||
### During Dependency Management |
|||
|
|||
- [ ] **Version Selection**: Choose appropriate dependency versions |
|||
- [ ] **Testing**: Test with new dependency versions |
|||
- [ ] **Documentation**: Update dependency documentation |
|||
- [ ] **Team Communication**: Communicate changes to team members |
|||
|
|||
### After Dependency Changes |
|||
|
|||
- [ ] **Comprehensive Testing**: Test all functionality with new dependencies |
|||
- [ ] **Documentation Update**: Update all relevant documentation |
|||
- [ ] **Deployment Planning**: Plan and execute deployment strategy |
|||
- [ ] **Monitoring**: Monitor for issues after deployment |
@ -0,0 +1,119 @@ |
|||
# Historical Comment Management — Code Clarity Guidelines |
|||
|
|||
> **Agent role**: When encountering historical comments about removed |
|||
> methods, deprecated patterns, or architectural changes, apply these |
|||
> guidelines to maintain code clarity and developer guidance. |
|||
|
|||
## Overview |
|||
|
|||
Historical comments should either be **removed entirely** or **transformed |
|||
into actionable guidance** for future developers. Avoid keeping comments |
|||
that merely state what was removed without explaining why or what to do |
|||
instead. |
|||
|
|||
## Decision Framework |
|||
|
|||
### When to Remove Comments |
|||
|
|||
- **Obsolete Information**: Comment describes functionality that no |
|||
longer exists |
|||
- **Outdated Context**: Comment refers to old patterns that are no |
|||
longer relevant |
|||
- **No Actionable Value**: Comment doesn't help future developers |
|||
make decisions |
|||
|
|||
### When to Transform Comments |
|||
|
|||
- **Migration Guidance**: Future developers might need to understand |
|||
the evolution |
|||
- **Alternative Approaches**: The comment can guide future |
|||
implementation choices |
|||
- **Historical Context**: Understanding the change helps with |
|||
current decisions |
|||
|
|||
## Transformation Patterns |
|||
|
|||
### 1. **Removed Method** → **Alternative Approach** |
|||
|
|||
```typescript |
|||
// Before: Historical comment |
|||
// turnOffNotifyingFlags method removed - notification state is now |
|||
// managed by NotificationSection component |
|||
|
|||
// After: Actionable guidance |
|||
// Note: Notification state management has been migrated to |
|||
// NotificationSection component |
|||
``` |
|||
|
|||
### 2. **Deprecated Pattern** → **Current Best Practice** |
|||
|
|||
```typescript |
|||
// Before: Historical comment |
|||
// Database access has been migrated from direct IndexedDB calls to |
|||
// PlatformServiceMixin |
|||
|
|||
// After: Actionable guidance |
|||
// This provides better platform abstraction and consistent error |
|||
// handling across web/mobile/desktop |
|||
|
|||
// When adding new database operations, use this.$getContact(), |
|||
// this.$saveSettings(), etc. |
|||
``` |
|||
|
|||
## Best Practices |
|||
|
|||
### 1. **Use Actionable Language**: Guide future decisions, not just |
|||
|
|||
document history |
|||
|
|||
### 2. **Provide Alternatives**: Always suggest what to use instead |
|||
|
|||
### 3. **Update Related Docs**: If removing from code, consider |
|||
|
|||
adding to documentation |
|||
|
|||
### 4. **Keep Context**: Include enough information to understand |
|||
|
|||
why the change was made |
|||
|
|||
## Integration Points |
|||
|
|||
- Apply these rules when reviewing code changes |
|||
- Use during code cleanup and refactoring |
|||
- Include in code review checklists |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/development/historical_comment_patterns.mdc` for detailed |
|||
transformation examples and patterns |
|||
|
|||
**Status**: Active comment management guidelines |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: None |
|||
**Stakeholders**: Development team, Code reviewers |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Comment Review |
|||
|
|||
- [ ] **Code Analysis**: Review code for historical or outdated comments |
|||
- [ ] **Context Understanding**: Understand the current state of the codebase |
|||
- [ ] **Pattern Identification**: Identify comments that need transformation or removal |
|||
- [ ] **Documentation Planning**: Plan where to move important historical context |
|||
|
|||
### During Comment Management |
|||
|
|||
- [ ] **Transformation**: Convert historical comments to actionable guidance |
|||
- [ ] **Alternative Provision**: Suggest current best practices and alternatives |
|||
- [ ] **Context Preservation**: Maintain enough information to understand changes |
|||
- [ ] **Documentation Update**: Move important context to appropriate documentation |
|||
|
|||
### After Comment Management |
|||
|
|||
- [ ] **Code Review**: Ensure transformed comments provide actionable value |
|||
- [ ] **Documentation Sync**: Verify related documentation is updated |
|||
- [ ] **Team Communication**: Share comment transformation patterns with team |
|||
- [ ] **Process Integration**: Include comment management in code review checklists |
@ -0,0 +1,139 @@ |
|||
# Historical Comment Patterns — Transformation Examples |
|||
|
|||
> **Agent role**: Reference this file for specific patterns and |
|||
examples when transforming historical comments into actionable guidance. |
|||
|
|||
## 🔄 Transformation Patterns |
|||
|
|||
### 1. From Removal Notice to Migration Note |
|||
|
|||
```typescript |
|||
|
|||
// ❌ REMOVE THIS |
|||
// turnOffNotifyingFlags method removed - |
|||
notification state is now managed by NotificationSection component |
|||
|
|||
// ✅ TRANSFORM TO THIS |
|||
// Note: Notification state management has been migrated to NotificationSection |
|||
component |
|||
// which handles its own lifecycle and persistence via PlatformServiceMixin |
|||
|
|||
``` |
|||
|
|||
### 2. From Deprecation Notice to Implementation Guide |
|||
|
|||
```typescript |
|||
|
|||
// ❌ REMOVE THIS |
|||
// This will be handled by the NewComponent now |
|||
// No need to call oldMethod() as it's no longer needed |
|||
|
|||
// ✅ TRANSFORM TO THIS |
|||
// Note: This functionality has been migrated to NewComponent |
|||
// which provides better separation of concerns and testability |
|||
|
|||
``` |
|||
|
|||
### 3. From Historical Note to Architectural Context |
|||
|
|||
```typescript |
|||
|
|||
// ❌ REMOVE THIS |
|||
// Old approach: used direct database calls |
|||
// New approach: uses service layer |
|||
|
|||
// ✅ TRANSFORM TO THIS |
|||
// Note: Database access has been abstracted through service layer |
|||
// for better testability and platform independence |
|||
|
|||
``` |
|||
|
|||
## 🚫 Anti-Patterns to Remove |
|||
|
|||
- Comments that only state what was removed |
|||
|
|||
- Comments that don't explain the current approach |
|||
|
|||
- Comments that reference non-existent methods |
|||
|
|||
- Comments that are self-evident from the code |
|||
|
|||
- Comments that don't help future decision-making |
|||
|
|||
## 📚 Examples |
|||
|
|||
### Good Historical Comment (Keep & Transform) |
|||
|
|||
```typescript |
|||
|
|||
// Note: Database access has been migrated from direct IndexedDB calls to |
|||
PlatformServiceMixin |
|||
// This provides better platform abstraction and |
|||
consistent error handling across web/mobile/desktop |
|||
// When adding new database operations, use this.$getContact(), |
|||
this.$saveSettings(), etc. |
|||
|
|||
``` |
|||
|
|||
### Bad Historical Comment (Remove) |
|||
|
|||
```typescript |
|||
|
|||
// Old method getContactFromDB() removed - now handled by PlatformServiceMixin |
|||
// No need to call the old method anymore |
|||
|
|||
``` |
|||
|
|||
## 🎯 When to Use Each Pattern |
|||
|
|||
### Migration Notes |
|||
|
|||
- Use when functionality has moved to a different component/service |
|||
|
|||
- Explain the new location and why it's better |
|||
|
|||
- Provide guidance on how to use the new approach |
|||
|
|||
### Implementation Guides |
|||
|
|||
- Use when patterns have changed significantly |
|||
|
|||
- Explain the architectural benefits |
|||
|
|||
- Show how to implement the new pattern |
|||
|
|||
### Architectural Context |
|||
|
|||
- Use when the change represents a system-wide improvement |
|||
|
|||
- Explain the reasoning behind the change |
|||
|
|||
- Help future developers understand the evolution |
|||
|
|||
--- |
|||
|
|||
**See also**: `.cursor/rules/development/historical_comment_management.mdc` for |
|||
the core decision framework and best practices. |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Comment Review |
|||
|
|||
- [ ] **Code Analysis**: Review code for historical or outdated comments |
|||
- [ ] **Pattern Identification**: Identify comments that need transformation or removal |
|||
- [ ] **Context Understanding**: Understand the current state of the codebase |
|||
- [ ] **Transformation Planning**: Plan how to transform or remove comments |
|||
|
|||
### During Comment Transformation |
|||
|
|||
- [ ] **Pattern Selection**: Choose appropriate transformation pattern |
|||
- [ ] **Content Creation**: Create actionable guidance for future developers |
|||
- [ ] **Alternative Provision**: Suggest current best practices and approaches |
|||
- [ ] **Context Preservation**: Maintain enough information to understand changes |
|||
|
|||
### After Comment Transformation |
|||
|
|||
- [ ] **Code Review**: Ensure transformed comments provide actionable value |
|||
- [ ] **Pattern Documentation**: Document transformation patterns for team use |
|||
- [ ] **Team Communication**: Share comment transformation patterns with team |
|||
- [ ] **Process Integration**: Include comment patterns in code review checklists |
@ -1,76 +1,178 @@ |
|||
# Investigation Report Example |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-19 |
|||
**Status**: 🎯 **ACTIVE** - Investigation methodology example |
|||
|
|||
## Investigation — Registration Dialog Test Flakiness |
|||
|
|||
## Objective |
|||
Identify root cause of flaky tests related to registration dialogs in contact import scenarios. |
|||
|
|||
Identify root cause of flaky tests related to registration dialogs in contact |
|||
import scenarios. |
|||
|
|||
## System Map |
|||
- User action → ContactInputForm → ContactsView.addContact() → handleRegistrationPrompt() |
|||
|
|||
- User action → ContactInputForm → ContactsView.addContact() → |
|||
|
|||
handleRegistrationPrompt() |
|||
|
|||
- setTimeout(1000ms) → Modal dialog → User response → Registration API call |
|||
- Test execution → Wait for dialog → Assert dialog content → Click response button |
|||
|
|||
- Test execution → Wait for dialog → Assert dialog content → Click response |
|||
|
|||
button |
|||
|
|||
## Findings (Evidence) |
|||
- **1-second timeout causes flakiness** — evidence: `src/views/ContactsView.vue:971-1000`; setTimeout(..., 1000) in handleRegistrationPrompt() |
|||
- **Import flow bypasses dialogs** — evidence: `src/views/ContactImportView.vue:500-520`; importContacts() calls $insertContact() directly, no handleRegistrationPrompt() |
|||
- **Dialog only appears in direct add flow** — evidence: `src/views/ContactsView.vue:774-800`; addContact() calls handleRegistrationPrompt() after database insert |
|||
|
|||
- **1-second timeout causes flakiness** — evidence: |
|||
|
|||
`src/views/ContactsView.vue:971-1000`; setTimeout(..., 1000) in |
|||
handleRegistrationPrompt() |
|||
|
|||
- **Import flow bypasses dialogs** — evidence: |
|||
|
|||
`src/views/ContactImportView.vue:500-520`; importContacts() calls |
|||
$insertContact() directly, no handleRegistrationPrompt() |
|||
|
|||
- **Dialog only appears in direct add flow** — evidence: |
|||
|
|||
`src/views/ContactsView.vue:774-800`; addContact() calls |
|||
handleRegistrationPrompt() after database insert |
|||
|
|||
## Hypotheses & Failure Modes |
|||
- H1: 1-second timeout makes dialog appearance unpredictable; would fail when tests run faster than 1000ms |
|||
- H2: Test environment timing differs from development; watch for CI vs local test differences |
|||
|
|||
- H1: 1-second timeout makes dialog appearance unpredictable; would fail when |
|||
|
|||
tests run faster than 1000ms |
|||
|
|||
- H2: Test environment timing differs from development; watch for CI vs local |
|||
|
|||
test differences |
|||
|
|||
## Corrections |
|||
- Updated: "Multiple dialogs interfere with imports" → "Import flow never triggers dialogs - they only appear in direct contact addition" |
|||
- Updated: "Complex batch registration needed" → "Simple timeout removal and test mode flag sufficient" |
|||
|
|||
- Updated: "Multiple dialogs interfere with imports" → "Import flow never |
|||
|
|||
triggers dialogs - they only appear in direct contact addition" |
|||
|
|||
- Updated: "Complex batch registration needed" → "Simple timeout removal and |
|||
|
|||
test mode flag sufficient" |
|||
|
|||
## Diagnostics (Next Checks) |
|||
|
|||
- [ ] Repro on CI environment vs local |
|||
|
|||
- [ ] Measure actual dialog appearance timing |
|||
|
|||
- [ ] Test with setTimeout removed |
|||
|
|||
- [ ] Verify import flow doesn't call handleRegistrationPrompt |
|||
|
|||
## Risks & Scope |
|||
- Impacted: Contact addition tests, registration workflow tests; Data: None; Users: Test suite reliability |
|||
|
|||
- Impacted: Contact addition tests, registration workflow tests; Data: None; |
|||
|
|||
Users: Test suite reliability |
|||
|
|||
## Decision / Next Steps |
|||
|
|||
- Owner: Development Team; By: 2025-01-28 |
|||
- Action: Remove 1-second timeout + add test mode flag; Exit criteria: Tests pass consistently |
|||
|
|||
- Action: Remove 1-second timeout + add test mode flag; Exit criteria: Tests |
|||
|
|||
pass consistently |
|||
|
|||
## References |
|||
|
|||
- `src/views/ContactsView.vue:971-1000` |
|||
|
|||
- `src/views/ContactImportView.vue:500-520` |
|||
|
|||
- `src/views/ContactsView.vue:774-800` |
|||
|
|||
## Competence Hooks |
|||
- Why this works: Code path tracing revealed separate execution flows, evidence disproved initial assumptions |
|||
- Common pitfalls: Assuming related functionality without tracing execution paths, over-engineering solutions to imaginary problems |
|||
- Next skill: Learn to trace code execution before proposing architectural changes |
|||
- Teach-back: "What evidence shows that contact imports bypass registration dialogs?" |
|||
|
|||
--- |
|||
- Why this works: Code path tracing revealed separate execution flows, |
|||
|
|||
evidence disproved initial assumptions |
|||
|
|||
- Common pitfalls: Assuming related functionality without tracing execution |
|||
|
|||
paths, over-engineering solutions to imaginary problems |
|||
|
|||
- Next skill: Learn to trace code execution before proposing architectural |
|||
|
|||
changes |
|||
|
|||
- Teach-back: "What evidence shows that contact imports bypass registration |
|||
|
|||
dialogs?" |
|||
|
|||
## Key Learning Points |
|||
|
|||
### Evidence-First Approach |
|||
|
|||
This investigation demonstrates the importance of: |
|||
|
|||
1. **Tracing actual code execution** rather than making assumptions |
|||
|
|||
2. **Citing specific evidence** with file:line references |
|||
|
|||
3. **Validating problem scope** before proposing solutions |
|||
|
|||
4. **Considering simpler alternatives** before complex architectural changes |
|||
|
|||
### Code Path Tracing Value |
|||
|
|||
By tracing the execution paths, we discovered: |
|||
|
|||
- Import flow and direct add flow are completely separate |
|||
|
|||
- The "multiple dialog interference" problem didn't exist |
|||
|
|||
- A simple timeout removal would solve the actual issue |
|||
|
|||
### Prevention of Over-Engineering |
|||
|
|||
The investigation prevented: |
|||
|
|||
- Unnecessary database schema changes |
|||
|
|||
- Complex batch registration systems |
|||
|
|||
- Migration scripts for non-existent problems |
|||
|
|||
- Architectural changes based on assumptions |
|||
description: |
|||
globs: |
|||
alwaysApply: false |
|||
|
|||
--- |
|||
|
|||
**Status**: Active investigation methodology |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: software_development.mdc |
|||
**Stakeholders**: Development team, QA team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Investigation |
|||
|
|||
- [ ] **Problem Definition**: Clearly define the problem to investigate |
|||
- [ ] **Scope Definition**: Determine investigation scope and boundaries |
|||
- [ ] **Methodology Planning**: Plan investigation approach and methods |
|||
- [ ] **Resource Assessment**: Identify required resources and tools |
|||
|
|||
### During Investigation |
|||
|
|||
- [ ] **Evidence Collection**: Gather relevant evidence and data systematically |
|||
- [ ] **Code Path Tracing**: Map execution flow for software investigations |
|||
- [ ] **Analysis**: Analyze evidence using appropriate methods |
|||
- [ ] **Documentation**: Document investigation process and findings |
|||
|
|||
### After Investigation |
|||
|
|||
- [ ] **Synthesis**: Synthesize findings into actionable insights |
|||
- [ ] **Report Creation**: Create comprehensive investigation report |
|||
- [ ] **Recommendations**: Provide clear, actionable recommendations |
|||
- [ ] **Team Communication**: Share findings and next steps with team |
@ -0,0 +1,358 @@ |
|||
--- |
|||
alwaysApply: false |
|||
--- |
|||
|
|||
# Logging Migration — Patterns and Examples |
|||
|
|||
> **Agent role**: Reference this file for specific migration patterns and |
|||
examples when converting console.* calls to logger usage. |
|||
|
|||
## Migration — Auto‑Rewrites (Apply Every Time) |
|||
|
|||
### Exact Transforms |
|||
|
|||
- `console.debug(...)` → `logger.debug(...)` |
|||
|
|||
- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when |
|||
|
|||
clearly stateful) |
|||
|
|||
- `console.info(...)` → `logger.info(...)` |
|||
|
|||
- `console.warn(...)` → `logger.warn(...)` |
|||
|
|||
- `console.error(...)` → `logger.error(...)` |
|||
|
|||
### Multi-arg Handling |
|||
|
|||
- First arg becomes `message` (stringify safely if non-string). |
|||
|
|||
- Remaining args map 1:1 to `...args`: |
|||
|
|||
`console.info(msg, a, b)` → `logger.info(String(msg), a, b)` |
|||
|
|||
### Sole `Error` |
|||
|
|||
- `console.error(err)` → `logger.error(err.message, err)` |
|||
|
|||
### Object-wrapping Cleanup |
|||
|
|||
Replace `{{ userId, meta }}` wrappers with separate args: |
|||
`logger.info('User signed in', userId, meta)` |
|||
|
|||
## Level Guidelines with Examples |
|||
|
|||
### DEBUG Examples |
|||
|
|||
```typescript |
|||
|
|||
logger.debug('[HomeView] reloadFeedOnChange() called'); |
|||
logger.debug('[HomeView] Current filter settings', |
|||
settings.filterFeedByVisible, |
|||
settings.filterFeedByNearby, |
|||
settings.searchBoxes?.length ?? 0); |
|||
logger.debug('[FeedFilters] Toggling nearby filter', |
|||
this.isNearby, this.settingChanged, this.activeDid); |
|||
|
|||
``` |
|||
|
|||
**Avoid**: Vague messages (`'Processing data'`). |
|||
|
|||
### INFO Examples |
|||
|
|||
```typescript |
|||
|
|||
logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM); |
|||
logger.info('[StartView] User selected new seed generation'); |
|||
logger.info('[SearchAreaView] Search box stored', |
|||
searchBox.name, searchBox.bbox); |
|||
logger.info('[ContactQRScanShowView] Contact registration OK', |
|||
contact.did); |
|||
|
|||
``` |
|||
|
|||
**Avoid**: Diagnostic details that belong in `debug`. |
|||
|
|||
### WARN Examples |
|||
|
|||
```typescript |
|||
|
|||
logger.warn('[ContactQRScanShowView] Invalid scan result – no value', |
|||
resultType); |
|||
logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL'); |
|||
logger.warn('[ContactQRScanShowView] JWT missing "own" field'); |
|||
|
|||
``` |
|||
|
|||
**Avoid**: Hard failures (those are `error`). |
|||
|
|||
### ERROR Examples |
|||
|
|||
```typescript |
|||
|
|||
logger.error('[HomeView Settings] initializeIdentity() failed', err); |
|||
logger.error('[StartView] Failed to load initialization data', error); |
|||
logger.error('[ContactQRScanShowView] Error processing contact QR', |
|||
error, rawValue); |
|||
|
|||
``` |
|||
|
|||
**Avoid**: Expected user cancels (use `info`/`debug`). |
|||
|
|||
## Context Hygiene Examples |
|||
|
|||
### Component Context |
|||
|
|||
```typescript |
|||
|
|||
const log = logger.withContext('UserService'); |
|||
log.info('User created', userId); |
|||
log.error('Failed to create user', error); |
|||
|
|||
``` |
|||
|
|||
If not using `withContext`, prefix message with `[ComponentName]`. |
|||
|
|||
### Emoji Guidelines |
|||
|
|||
Recommended set for visual scanning: |
|||
|
|||
- Start/finish: 🚀 / ✅ |
|||
|
|||
- Retry/loop: 🔄 |
|||
|
|||
- External call: 📡 |
|||
|
|||
- Data/metrics: 📊 |
|||
|
|||
- Inspection: 🔍 |
|||
|
|||
## Quick Before/After |
|||
|
|||
### **Before** |
|||
|
|||
```typescript |
|||
|
|||
console.log('User signed in', user.id, meta); |
|||
console.error('Failed to update profile', err); |
|||
console.info('Filter toggled', this.hasVisibleDid); |
|||
|
|||
``` |
|||
|
|||
### **After** |
|||
|
|||
```typescript |
|||
|
|||
import { logger } from '@/utils/logger'; |
|||
|
|||
logger.info('User signed in', user.id, meta); |
|||
logger.error('Failed to update profile', err); |
|||
logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid); |
|||
|
|||
``` |
|||
|
|||
## Checklist (for every PR) |
|||
|
|||
- [ ] No `console.*` (or properly pragma'd in the allowed locations) |
|||
|
|||
- [ ] Correct import path for `logger` |
|||
|
|||
- [ ] Rest-parameter call shape (`message, ...args`) |
|||
|
|||
- [ ] Right level chosen (debug/info/warn/error) |
|||
|
|||
- [ ] No secrets / oversized payloads / throwaway context objects |
|||
|
|||
- [ ] Component context provided (scoped logger or `[Component]` prefix) |
|||
|
|||
**See also**: |
|||
`.cursor/rules/development/logging_standards.mdc` for the core standards and rules. |
|||
|
|||
# Logging Migration — Patterns and Examples |
|||
|
|||
> **Agent role**: Reference this file for specific migration patterns and |
|||
examples when converting console.* calls to logger usage. |
|||
|
|||
## Migration — Auto‑Rewrites (Apply Every Time) |
|||
|
|||
### Exact Transforms |
|||
|
|||
- `console.debug(...)` → `logger.debug(...)` |
|||
|
|||
- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when |
|||
|
|||
clearly stateful) |
|||
|
|||
- `console.info(...)` → `logger.info(...)` |
|||
|
|||
- `console.warn(...)` → `logger.warn(...)` |
|||
|
|||
- `console.error(...)` → `logger.error(...)` |
|||
|
|||
### Multi-arg Handling |
|||
|
|||
- First arg becomes `message` (stringify safely if non-string). |
|||
|
|||
- Remaining args map 1:1 to `...args`: |
|||
|
|||
`console.info(msg, a, b)` → `logger.info(String(msg), a, b)` |
|||
|
|||
### Sole `Error` |
|||
|
|||
- `console.error(err)` → `logger.error(err.message, err)` |
|||
|
|||
### Object-wrapping Cleanup |
|||
|
|||
Replace `{{ userId, meta }}` wrappers with separate args: |
|||
`logger.info('User signed in', userId, meta)` |
|||
|
|||
## Level Guidelines with Examples |
|||
|
|||
### DEBUG Examples |
|||
|
|||
```typescript |
|||
|
|||
logger.debug('[HomeView] reloadFeedOnChange() called'); |
|||
logger.debug('[HomeView] Current filter settings', |
|||
settings.filterFeedByVisible, |
|||
settings.filterFeedByNearby, |
|||
settings.searchBoxes?.length ?? 0); |
|||
logger.debug('[FeedFilters] Toggling nearby filter', |
|||
this.isNearby, this.settingChanged, this.activeDid); |
|||
|
|||
``` |
|||
|
|||
**Avoid**: Vague messages (`'Processing data'`). |
|||
|
|||
### INFO Examples |
|||
|
|||
```typescript |
|||
|
|||
logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM); |
|||
logger.info('[StartView] User selected new seed generation'); |
|||
logger.info('[SearchAreaView] Search box stored', |
|||
searchBox.name, searchBox.bbox); |
|||
logger.info('[ContactQRScanShowView] Contact registration OK', |
|||
contact.did); |
|||
|
|||
``` |
|||
|
|||
**Avoid**: Diagnostic details that belong in `debug`. |
|||
|
|||
### WARN Examples |
|||
|
|||
```typescript |
|||
|
|||
logger.warn('[ContactQRScanShowView] Invalid scan result – no value', |
|||
resultType); |
|||
logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL'); |
|||
logger.warn('[ContactQRScanShowView] JWT missing "own" field'); |
|||
|
|||
``` |
|||
|
|||
**Avoid**: Hard failures (those are `error`). |
|||
|
|||
### ERROR Examples |
|||
|
|||
```typescript |
|||
|
|||
logger.error('[HomeView Settings] initializeIdentity() failed', err); |
|||
logger.error('[StartView] Failed to load initialization data', error); |
|||
logger.error('[ContactQRScanShowView] Error processing contact QR', |
|||
error, rawValue); |
|||
|
|||
``` |
|||
|
|||
**Avoid**: Expected user cancels (use `info`/`debug`). |
|||
|
|||
## Context Hygiene Examples |
|||
|
|||
### Component Context |
|||
|
|||
```typescript |
|||
|
|||
const log = logger.withContext('UserService'); |
|||
log.info('User created', userId); |
|||
log.error('Failed to create user', error); |
|||
|
|||
``` |
|||
|
|||
If not using `withContext`, prefix message with `[ComponentName]`. |
|||
|
|||
### Emoji Guidelines |
|||
|
|||
Recommended set for visual scanning: |
|||
|
|||
- Start/finish: 🚀 / ✅ |
|||
|
|||
- Retry/loop: 🔄 |
|||
|
|||
- External call: 📡 |
|||
|
|||
- Data/metrics: 📊 |
|||
|
|||
- Inspection: 🔍 |
|||
|
|||
## Quick Before/After |
|||
|
|||
### **Before** |
|||
|
|||
```typescript |
|||
|
|||
console.log('User signed in', user.id, meta); |
|||
console.error('Failed to update profile', err); |
|||
console.info('Filter toggled', this.hasVisibleDid); |
|||
|
|||
``` |
|||
|
|||
### **After** |
|||
|
|||
```typescript |
|||
|
|||
import { logger } from '@/utils/logger'; |
|||
|
|||
logger.info('User signed in', user.id, meta); |
|||
logger.error('Failed to update profile', err); |
|||
logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid); |
|||
|
|||
``` |
|||
|
|||
## Checklist (for every PR) |
|||
|
|||
- [ ] No `console.*` (or properly pragma'd in the allowed locations) |
|||
|
|||
- [ ] Correct import path for `logger` |
|||
|
|||
- [ ] Rest-parameter call shape (`message, ...args`) |
|||
|
|||
- [ ] Right level chosen (debug/info/warn/error) |
|||
|
|||
- [ ] No secrets / oversized payloads / throwaway context objects |
|||
|
|||
- [ ] Component context provided (scoped logger or `[Component]` prefix) |
|||
|
|||
**See also**: |
|||
`.cursor/rules/development/logging_standards.mdc` for the core standards and rules. |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Logging Migration |
|||
|
|||
- [ ] **Code Review**: Identify all `console.*` calls in the codebase |
|||
- [ ] **Logger Import**: Verify logger utility is available and accessible |
|||
- [ ] **Context Planning**: Plan component context for each logging call |
|||
- [ ] **Level Assessment**: Determine appropriate log levels for each call |
|||
|
|||
### During Logging Migration |
|||
|
|||
- [ ] **Import Replacement**: Replace `console.*` with `logger.*` calls |
|||
- [ ] **Context Addition**: Add component context using scoped logger or prefix |
|||
- [ ] **Level Selection**: Choose appropriate log level (debug/info/warn/error) |
|||
- [ ] **Parameter Format**: Use rest-parameter call shape (`message, ...args`) |
|||
|
|||
### After Logging Migration |
|||
|
|||
- [ ] **Console Check**: Ensure no `console.*` methods remain (unless pragma'd) |
|||
- [ ] **Context Validation**: Verify all logging calls have proper context |
|||
- [ ] **Level Review**: Confirm log levels are appropriate for each situation |
|||
- [ ] **Testing**: Test logging functionality across all platforms |
@ -0,0 +1,176 @@ |
|||
# Agent Contract — TimeSafari Logging (Unified, MANDATORY) |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-19 |
|||
**Status**: 🎯 **ACTIVE** - Mandatory logging standards |
|||
|
|||
## Overview |
|||
|
|||
This document defines unified logging standards for the TimeSafari project, |
|||
ensuring consistent, rest-parameter logging style using the project logger. |
|||
No `console.*` methods are allowed in production code. |
|||
|
|||
## Scope and Goals |
|||
|
|||
**Scope**: Applies to all diffs and generated code in this workspace unless |
|||
explicitly exempted below. |
|||
|
|||
**Goal**: One consistent, rest-parameter logging style using the project |
|||
logger; no `console.*` in production code. |
|||
|
|||
## Non‑Negotiables (DO THIS) |
|||
|
|||
- You **MUST** use the project logger; **DO NOT** use any `console.*` |
|||
|
|||
methods. |
|||
|
|||
- Import exactly as: |
|||
|
|||
- `import { logger } from '@/utils/logger'` |
|||
|
|||
- If `@` alias is unavailable, compute the correct relative path (do not |
|||
|
|||
fail). |
|||
|
|||
- Call signatures use **rest parameters**: `logger.info(message, ...args)` |
|||
|
|||
- Prefer primitives/IDs and small objects in `...args`; **never build a |
|||
|
|||
throwaway object** just to "wrap context". |
|||
|
|||
- Production defaults: Web = `warn+`, Electron = `error`, Dev/Capacitor = |
|||
|
|||
`info+` (override via `VITE_LOG_LEVEL`). |
|||
|
|||
- **Database persistence**: `info|warn|error` are persisted; `debug` is not. |
|||
|
|||
Use `logger.toDb(msg, level?)` for DB-only. |
|||
|
|||
## Available Logger API (Authoritative) |
|||
|
|||
- `logger.debug(message, ...args)` — verbose internals, timings, input/output |
|||
|
|||
shapes |
|||
|
|||
- `logger.log(message, ...args)` — synonym of `info` for general info |
|||
|
|||
- `logger.info(message, ...args)` — lifecycle, state changes, success paths |
|||
|
|||
- `logger.warn(message, ...args)` — recoverable issues, retries, degraded mode |
|||
|
|||
- `logger.error(message, ...args)` — failures, thrown exceptions, aborts |
|||
|
|||
- `logger.toDb(message, level?)` — DB-only entry (default level = `info`) |
|||
|
|||
- `logger.toConsoleAndDb(message, isError)` — console + DB (use sparingly) |
|||
|
|||
- `logger.withContext(componentName)` — returns a scoped logger |
|||
|
|||
## Level Guidelines (Use These Heuristics) |
|||
|
|||
### DEBUG |
|||
|
|||
Use for method entry/exit, computed values, filters, loops, retries, and |
|||
external call payload sizes. |
|||
|
|||
### INFO |
|||
|
|||
Use for user-visible lifecycle and completed operations. |
|||
|
|||
### WARN |
|||
|
|||
Use for recoverable issues, fallbacks, unexpected-but-handled conditions. |
|||
|
|||
### ERROR |
|||
|
|||
Use for unrecoverable failures, data integrity issues, and thrown |
|||
exceptions. |
|||
|
|||
## Context Hygiene (Consistent, Minimal, Helpful) |
|||
|
|||
- **Component context**: Prefer scoped logger. |
|||
|
|||
- **Emojis**: Optional and minimal for visual scanning. |
|||
|
|||
- **Sensitive data**: Never log secrets (tokens, keys, passwords) or |
|||
payloads >10KB. Prefer IDs over objects; redact/hash when needed. |
|||
|
|||
## DB Logging Rules |
|||
|
|||
- `debug` **never** persists automatically. |
|||
|
|||
- `info|warn|error` persist automatically. |
|||
|
|||
- For DB-only events (no console), call `logger.toDb('Message', |
|||
'info'|'warn'|'error')`. |
|||
|
|||
## Exceptions (Tightly Scoped) |
|||
|
|||
Allowed paths (still prefer logger): |
|||
|
|||
- `**/*.test.*`, `**/*.spec.*` |
|||
|
|||
- `scripts/dev/**`, `scripts/migrate/**` |
|||
|
|||
To intentionally keep `console.*`, add a pragma on the previous line: |
|||
|
|||
```typescript |
|||
|
|||
// cursor:allow-console reason="short justification" |
|||
console.log('temporary output'); |
|||
|
|||
``` |
|||
|
|||
## CI & Diff Enforcement |
|||
|
|||
- Do not introduce `console.*` anywhere outside allowed, pragma'd spots. |
|||
|
|||
- If an import is missing, insert it and resolve alias/relative path |
|||
correctly. |
|||
|
|||
- Enforce rest-parameter call shape in reviews; replace object-wrapped |
|||
context. |
|||
|
|||
- Ensure environment log level rules remain intact (`VITE_LOG_LEVEL` |
|||
respected). |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
`.cursor/rules/development/logging_migration.mdc` for migration patterns and examples. |
|||
|
|||
**Status**: Active and enforced |
|||
**Priority**: Critical |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: TimeSafari logger utility |
|||
**Stakeholders**: Development team, Code review team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Adding Logging |
|||
|
|||
- [ ] **Logger Import**: Import logger as `import { logger } from |
|||
'@/utils/logger'` |
|||
- [ ] **Log Level Selection**: Determine appropriate log level |
|||
(debug/info/warn/error) |
|||
- [ ] **Context Planning**: Plan what context information to include |
|||
- [ ] **Sensitive Data Review**: Identify any sensitive data that needs redaction |
|||
|
|||
### During Logging Implementation |
|||
|
|||
- [ ] **Rest Parameters**: Use `logger.info(message, ...args)` format, not object |
|||
wrapping |
|||
- [ ] **Context Addition**: Include relevant IDs, primitives, or small objects in |
|||
args |
|||
- [ ] **Level Appropriateness**: Use correct log level for the situation |
|||
- [ ] **Scoped Logger**: Use `logger.withContext(componentName)` for |
|||
component-specific logging |
|||
|
|||
### After Logging Implementation |
|||
|
|||
- [ ] **Console Check**: Ensure no `console.*` methods are used (unless in |
|||
allowed paths) |
|||
- [ ] **Performance Review**: Verify logging doesn't impact performance |
|||
- [ ] **DB Persistence**: Use `logger.toDb()` for database-only logging if needed |
|||
- [ ] **Environment Compliance**: Respect `VITE_LOG_LEVEL` environment |
|||
variable |
@ -0,0 +1,160 @@ |
|||
# Planning Examples — No Time Estimates |
|||
|
|||
> **Agent role**: Reference this file for detailed planning examples and |
|||
anti-patterns when creating project plans. |
|||
|
|||
## 🎯 Example Planning (No Time Estimates) |
|||
|
|||
### **Example 1: Simple Feature** |
|||
|
|||
``` |
|||
|
|||
Phase 1: Core implementation |
|||
|
|||
- Basic functionality |
|||
|
|||
- Single platform support |
|||
|
|||
- Unit tests |
|||
|
|||
Phase 2: Platform expansion |
|||
|
|||
- Multi-platform support |
|||
|
|||
- Integration tests |
|||
|
|||
Phase 3: Polish |
|||
|
|||
- User testing |
|||
|
|||
- Edge case handling |
|||
|
|||
``` |
|||
|
|||
### **Example 2: Complex Cross-Platform Feature** |
|||
|
|||
``` |
|||
|
|||
Phase 1: Foundation |
|||
|
|||
- Architecture design |
|||
|
|||
- Core service implementation |
|||
|
|||
- Basic web platform support |
|||
|
|||
Phase 2: Platform Integration |
|||
|
|||
- Mobile platform support |
|||
|
|||
- Desktop platform support |
|||
|
|||
- Cross-platform consistency |
|||
|
|||
Phase 3: Testing & Polish |
|||
|
|||
- Comprehensive testing |
|||
|
|||
- Error handling |
|||
|
|||
- User experience refinement |
|||
|
|||
``` |
|||
|
|||
## 🚫 Anti-Patterns to Avoid |
|||
|
|||
- **"This should take X days"** - Red flag for time estimation |
|||
|
|||
- **"Just a few hours"** - Ignores complexity and testing |
|||
|
|||
- **"Similar to X"** - Without considering differences |
|||
|
|||
- **"Quick fix"** - Nothing is ever quick in software |
|||
|
|||
- **"No testing needed"** - Testing always takes effort |
|||
|
|||
## ✅ Best Practices |
|||
|
|||
### **When Planning:** |
|||
|
|||
1. **Break down everything** - no work is too small to plan |
|||
|
|||
2. **Consider all platforms** - web, mobile, desktop differences |
|||
|
|||
3. **Include testing strategy** - unit, integration, and user testing |
|||
|
|||
4. **Account for unknowns** - there are always surprises |
|||
|
|||
5. **Focus on dependencies** - what blocks what |
|||
|
|||
### **When Presenting Plans:** |
|||
|
|||
1. **Show the phases** - explain the logical progression |
|||
|
|||
2. **Highlight dependencies** - what could block progress |
|||
|
|||
3. **Define milestones** - clear success criteria |
|||
|
|||
4. **Identify risks** - what could go wrong |
|||
|
|||
5. **Suggest alternatives** - ways to reduce scope or complexity |
|||
|
|||
## 🔄 Continuous Improvement |
|||
|
|||
### **Track Progress** |
|||
|
|||
- Record planned vs. actual phases completed |
|||
|
|||
- Identify what took longer than expected |
|||
|
|||
- Learn from complexity misjudgments |
|||
|
|||
- Adjust planning process based on experience |
|||
|
|||
### **Learn from Experience** |
|||
|
|||
- **Underestimated complexity**: Increase complexity categories |
|||
|
|||
- **Missed dependencies**: Improve dependency mapping |
|||
|
|||
- **Platform surprises**: Better platform research upfront |
|||
|
|||
## 🎯 Integration with Harbor Pilot |
|||
|
|||
This rule works in conjunction with: |
|||
|
|||
- **Project Planning**: Focuses on phases and milestones |
|||
|
|||
- **Resource Allocation**: Based on complexity, not time |
|||
|
|||
- **Risk Management**: Identifies blockers and dependencies |
|||
|
|||
- **Stakeholder Communication**: Sets progress-based expectations |
|||
|
|||
--- |
|||
|
|||
**See also**: `.cursor/rules/development/realistic_time_estimation.mdc` for |
|||
the core principles and framework. |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Planning |
|||
|
|||
- [ ] **Requirements Review**: Understand all requirements completely |
|||
- [ ] **Stakeholder Input**: Gather input from all stakeholders |
|||
- [ ] **Complexity Assessment**: Evaluate technical and business complexity |
|||
- [ ] **Platform Analysis**: Consider requirements across all target platforms |
|||
|
|||
### During Planning |
|||
|
|||
- [ ] **Phase Definition**: Define clear phases and milestones |
|||
- [ ] **Dependency Mapping**: Map dependencies between tasks |
|||
- [ ] **Risk Identification**: Identify potential risks and challenges |
|||
- [ ] **Testing Strategy**: Plan comprehensive testing approach |
|||
|
|||
### After Planning |
|||
|
|||
- [ ] **Stakeholder Review**: Review plan with stakeholders |
|||
- [ ] **Documentation**: Document plan clearly with phases and milestones |
|||
- [ ] **Team Communication**: Communicate plan to team |
|||
- [ ] **Progress Tracking**: Set up monitoring and tracking mechanisms |
@ -0,0 +1,128 @@ |
|||
# Realistic Time Estimation — Development Guidelines |
|||
|
|||
> **Agent role**: **DO NOT MAKE TIME ESTIMATES**. Instead, use phases, |
|||
> milestones, and complexity levels. Time estimates are consistently wrong |
|||
> and create unrealistic expectations. |
|||
|
|||
## Purpose |
|||
|
|||
Development time estimates are consistently wrong and create unrealistic |
|||
expectations. This rule ensures we focus on phases, milestones, and |
|||
complexity rather than trying to predict specific timeframes. |
|||
|
|||
## Critical Rule |
|||
|
|||
**NEVER provide specific time estimates** (hours, days, weeks) for |
|||
development tasks. Instead, use: |
|||
|
|||
- **Complexity levels** (Low, Medium, High, Critical) |
|||
|
|||
- **Phases and milestones** with clear acceptance criteria |
|||
|
|||
- **Platform-specific considerations** (Web, Mobile, Desktop) |
|||
|
|||
- **Testing requirements** and validation steps |
|||
|
|||
## Planning Framework |
|||
|
|||
### Complexity Assessment |
|||
|
|||
- **Low**: Simple changes, existing patterns, minimal testing |
|||
|
|||
- **Medium**: New features, moderate testing, some integration |
|||
|
|||
- **High**: Complex features, extensive testing, multiple platforms |
|||
|
|||
- **Critical**: Core architecture changes, full regression testing |
|||
|
|||
### Platform Categories |
|||
|
|||
- **Web**: Browser compatibility, responsive design, accessibility |
|||
|
|||
- **Mobile**: Native APIs, platform-specific testing, deployment |
|||
|
|||
- **Desktop**: Electron integration, system APIs, distribution |
|||
|
|||
### Testing Strategy |
|||
|
|||
- **Unit tests**: Core functionality validation |
|||
|
|||
- **Integration tests**: Component interaction testing |
|||
|
|||
- **E2E tests**: User workflow validation |
|||
|
|||
- **Platform tests**: Cross-platform compatibility |
|||
|
|||
## Process Guidelines |
|||
|
|||
### Planning Phase |
|||
|
|||
1. **Scope Definition**: Clear requirements and acceptance criteria |
|||
|
|||
2. **Complexity Assessment**: Evaluate technical and business complexity |
|||
|
|||
3. **Phase Breakdown**: Divide into logical, testable phases |
|||
|
|||
4. **Milestone Definition**: Define success criteria for each phase |
|||
|
|||
### Execution Phase |
|||
|
|||
1. **Phase 1**: Foundation and core implementation |
|||
|
|||
2. **Phase 2**: Feature completion and integration |
|||
|
|||
3. **Phase 3**: Testing, refinement, and documentation |
|||
|
|||
4. **Phase 4**: Deployment and validation |
|||
|
|||
### Validation Phase |
|||
|
|||
1. **Acceptance Testing**: Verify against defined criteria |
|||
|
|||
2. **Platform Testing**: Validate across target platforms |
|||
|
|||
3. **Performance Testing**: Ensure performance requirements met |
|||
|
|||
4. **Documentation**: Update relevant documentation |
|||
|
|||
## Remember |
|||
|
|||
**Your first estimate is wrong. Your second estimate is probably still |
|||
wrong. Focus on progress, not deadlines.** |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/development/planning_examples.mdc` for detailed planning examples |
|||
|
|||
- `.cursor/rules/development/complexity_assessment.mdc` for complexity evaluation |
|||
|
|||
**Status**: Active development guidelines |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: None |
|||
**Stakeholders**: Development team, Project managers |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Time Estimation |
|||
|
|||
- [ ] **Requirements Analysis**: Understand all requirements and acceptance criteria |
|||
- [ ] **Complexity Assessment**: Evaluate technical and business complexity |
|||
- [ ] **Platform Review**: Identify requirements across all target platforms |
|||
- [ ] **Stakeholder Input**: Gather input from all affected parties |
|||
|
|||
### During Time Estimation |
|||
|
|||
- [ ] **Phase Breakdown**: Divide work into logical, testable phases |
|||
- [ ] **Complexity Classification**: Assign complexity levels (Low/Medium/High/Critical) |
|||
- [ ] **Platform Considerations**: Account for platform-specific requirements |
|||
- [ ] **Testing Strategy**: Plan comprehensive testing approach |
|||
|
|||
### After Time Estimation |
|||
|
|||
- [ ] **Milestone Definition**: Define success criteria for each phase |
|||
- [ ] **Progress Tracking**: Set up monitoring and tracking mechanisms |
|||
- [ ] **Documentation**: Document estimation process and assumptions |
|||
- [ ] **Stakeholder Communication**: Share estimation approach and progress focus |
@ -1,144 +1,227 @@ |
|||
|
|||
--- |
|||
|
|||
alwaysApply: false |
|||
--- |
|||
|
|||
# Software Development Ruleset |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-19 |
|||
**Status**: 🎯 **ACTIVE** - Core development guidelines |
|||
|
|||
## Purpose |
|||
Specialized guidelines for software development tasks including code review, debugging, architecture decisions, and testing. |
|||
|
|||
Specialized guidelines for software development tasks including code review, |
|||
debugging, architecture decisions, and testing. |
|||
|
|||
## Core Principles |
|||
|
|||
### 1. Evidence-First Development |
|||
- **Code Citations Required**: Always cite specific file:line references when making claims |
|||
- **Execution Path Tracing**: Trace actual code execution before proposing architectural changes |
|||
|
|||
- **Code Citations Required**: Always cite specific file:line references when |
|||
|
|||
making claims |
|||
|
|||
- **Execution Path Tracing**: Trace actual code execution before proposing |
|||
|
|||
architectural changes |
|||
|
|||
- **Assumption Validation**: Flag assumptions as "assumed" vs "evidence-based" |
|||
|
|||
### 2. Code Review Standards |
|||
- **Trace Before Proposing**: Always trace execution paths before suggesting changes |
|||
|
|||
- **Trace Before Proposing**: Always trace execution paths before suggesting |
|||
|
|||
changes |
|||
|
|||
- **Evidence Over Inference**: Prefer code citations over logical deductions |
|||
- **Scope Validation**: Confirm the actual scope of problems before proposing solutions |
|||
|
|||
- **Scope Validation**: Confirm the actual scope of problems before proposing |
|||
|
|||
solutions |
|||
|
|||
### 3. Problem-Solution Validation |
|||
|
|||
- **Problem Scope**: Does the solution address the actual problem? |
|||
|
|||
- **Evidence Alignment**: Does the solution match the evidence? |
|||
|
|||
- **Complexity Justification**: Is added complexity justified by real needs? |
|||
|
|||
- **Alternative Analysis**: What simpler solutions were considered? |
|||
|
|||
### 4. Dependency Management & Environment Validation |
|||
|
|||
- **Pre-build Validation**: |
|||
|
|||
Always validate critical dependencies before executing |
|||
build scripts |
|||
|
|||
- **Environment Consistency**: Ensure team members have identical development |
|||
|
|||
environments |
|||
|
|||
- **Dependency Verification**: Check that required packages are installed and |
|||
|
|||
accessible |
|||
|
|||
- **Path Resolution**: Use `npx` for local dependencies to avoid PATH issues |
|||
|
|||
## Required Workflows |
|||
|
|||
### Before Proposing Changes |
|||
|
|||
- [ ] **Code Path Tracing**: Map execution flow from entry to exit |
|||
|
|||
- [ ] **Evidence Collection**: Gather specific code citations and logs |
|||
|
|||
- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred |
|||
|
|||
- [ ] **Scope Validation**: Confirm the actual extent of the problem |
|||
|
|||
- [ ] **Dependency Validation**: Verify all required dependencies are available |
|||
|
|||
and accessible |
|||
|
|||
### During Solution Design |
|||
|
|||
- [ ] **Evidence Alignment**: Ensure solution addresses proven problems |
|||
|
|||
- [ ] **Complexity Assessment**: Justify any added complexity |
|||
|
|||
- [ ] **Alternative Evaluation**: Consider simpler approaches first |
|||
|
|||
- [ ] **Impact Analysis**: Assess effects on existing systems |
|||
|
|||
- [ ] **Environment Impact**: Assess how changes affect team member setups |
|||
|
|||
## Software-Specific Competence Hooks |
|||
|
|||
### Evidence Validation |
|||
|
|||
- **"What code path proves this claim?"** |
|||
|
|||
- **"How does data actually flow through the system?"** |
|||
|
|||
- **"What am I assuming vs. what can I prove?"** |
|||
|
|||
### Code Tracing |
|||
|
|||
- **"What's the execution path from user action to system response?"** |
|||
|
|||
- **"Which components actually interact in this scenario?"** |
|||
|
|||
- **"Where does the data originate and where does it end up?"** |
|||
|
|||
### Architecture Decisions |
|||
|
|||
- **"What evidence shows this change is necessary?"** |
|||
|
|||
- **"What simpler solution could achieve the same goal?"** |
|||
|
|||
- **"How does this change affect the existing system architecture?"** |
|||
|
|||
### Dependency & Environment Management |
|||
|
|||
- **"What dependencies does this feature require and are they properly |
|||
|
|||
declared?"** |
|||
|
|||
- **"How will this change affect team member development environments?"** |
|||
|
|||
- **"What validation can we add to catch dependency issues early?"** |
|||
|
|||
## Integration with Other Rulesets |
|||
|
|||
### With base_context.mdc |
|||
|
|||
- Inherits generic competence principles |
|||
|
|||
- Adds software-specific evidence requirements |
|||
|
|||
- Maintains collaboration and learning focus |
|||
|
|||
### With research_diagnostic.mdc |
|||
|
|||
- Enhances investigation with code path tracing |
|||
|
|||
- Adds evidence validation to diagnostic workflow |
|||
|
|||
- Strengthens problem identification accuracy |
|||
|
|||
## Usage Guidelines |
|||
|
|||
### When to Use This Ruleset |
|||
|
|||
- Code reviews and architectural decisions |
|||
|
|||
- Bug investigation and debugging |
|||
|
|||
- Performance optimization |
|||
|
|||
- Feature implementation planning |
|||
|
|||
- Testing strategy development |
|||
|
|||
### When to Combine with Others |
|||
|
|||
- **base_context + software_development**: General development tasks |
|||
|
|||
- **research_diagnostic + software_development**: Technical investigations |
|||
|
|||
- **All three**: Complex architectural decisions or major refactoring |
|||
|
|||
## Self-Check (model, before responding) |
|||
|
|||
- [ ] Code path traced and documented |
|||
|
|||
- [ ] Evidence cited with specific file:line references |
|||
|
|||
- [ ] Assumptions clearly flagged as proven vs. inferred |
|||
|
|||
- [ ] Solution complexity justified by evidence |
|||
|
|||
- [ ] Simpler alternatives considered and documented |
|||
- [ ] Impact on existing systems assessed |
|||
- [ ] Dependencies validated and accessible |
|||
- [ ] Environment impact assessed for team members |
|||
- [ ] Pre-build validation implemented where appropriate |
|||
|
|||
## Additional Core Principles |
|||
- [ ] Impact on existing systems assessed |
|||
|
|||
### 4. Dependency Management & Environment Validation |
|||
- **Pre-build Validation**: Always validate critical dependencies before executing build scripts |
|||
- **Environment Consistency**: Ensure team members have identical development environments |
|||
- **Dependency Verification**: Check that required packages are installed and accessible |
|||
- **Path Resolution**: Use `npx` for local dependencies to avoid PATH issues |
|||
- [ ] Dependencies validated and accessible |
|||
|
|||
## Additional Required Workflows |
|||
- [ ] Environment impact assessed for team members |
|||
|
|||
### Dependency Validation (Before Proposing Changes) |
|||
- [ ] **Dependency Validation**: Verify all required dependencies are available and accessible |
|||
- [ ] Pre-build validation implemented where appropriate |
|||
|
|||
### Environment Impact Assessment (During Solution Design) |
|||
- [ ] **Environment Impact**: Assess how changes affect team member setups |
|||
--- |
|||
|
|||
## Additional Competence Hooks |
|||
**See also**: `.cursor/rules/development/dependency_management.mdc` for |
|||
detailed dependency management practices. |
|||
|
|||
### Dependency & Environment Management |
|||
- **"What dependencies does this feature require and are they properly declared?"** |
|||
- **"How will this change affect team member development environments?"** |
|||
- **"What validation can we add to catch dependency issues early?"** |
|||
**Status**: Active development guidelines |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: base_context.mdc, research_diagnostic.mdc |
|||
**Stakeholders**: Development team, Code review team |
|||
|
|||
## Dependency Management Best Practices |
|||
## Model Implementation Checklist |
|||
|
|||
### Pre-build Validation |
|||
- **Check Critical Dependencies**: Validate essential tools before executing build scripts |
|||
- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to avoid PATH issues |
|||
- **Environment Consistency**: Ensure all team members have identical dependency versions |
|||
### Before Development Work |
|||
|
|||
### Common Pitfalls |
|||
- **Missing npm install**: Team members cloning without running `npm install` |
|||
- **PATH Issues**: Direct command execution vs. npm script execution differences |
|||
- **Version Mismatches**: Different Node.js/npm versions across team members |
|||
- [ ] **Code Path Tracing**: Map execution flow from entry to exit |
|||
- [ ] **Evidence Collection**: Gather specific code citations and logs |
|||
- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred |
|||
- [ ] **Scope Validation**: Confirm the actual extent of the problem |
|||
|
|||
### Validation Strategies |
|||
- **Dependency Check Scripts**: Implement pre-build validation for critical dependencies |
|||
- **Environment Requirements**: Document and enforce minimum Node.js/npm versions |
|||
- **Onboarding Checklist**: Standardize team member setup procedures |
|||
### During Development |
|||
|
|||
### Error Messages and Guidance |
|||
- **Specific Error Context**: Provide clear guidance when dependency issues occur |
|||
- **Actionable Solutions**: Direct users to specific commands (`npm install`, `npm run check:dependencies`) |
|||
- **Environment Diagnostics**: Implement comprehensive environment validation tools |
|||
- [ ] **Evidence Alignment**: Ensure solution addresses proven problems |
|||
- [ ] **Complexity Assessment**: Justify any added complexity |
|||
- [ ] **Alternative Evaluation**: Consider simpler approaches first |
|||
- [ ] **Impact Analysis**: Assess effects on existing systems |
|||
|
|||
### Build Script Enhancements |
|||
- **Early Validation**: Check dependencies before starting build processes |
|||
- **Graceful Degradation**: Continue builds when possible but warn about issues |
|||
- **Helpful Tips**: Remind users about dependency management best practices |
|||
### After Development |
|||
|
|||
- **Narrow Types Properly**: Use type guards to narrow `unknown` types safely |
|||
- **Document Type Decisions**: Explain complex type structures and their purpose |
|||
- [ ] **Code Path Validation**: Verify execution paths are correct |
|||
- [ ] **Evidence Documentation**: Document all code citations and evidence |
|||
- [ ] **Assumption Review**: Confirm all assumptions are documented |
|||
- [ ] **Environment Impact**: Assess how changes affect team member setups |
@ -0,0 +1,146 @@ |
|||
# Time Handling in Development Workflow |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-17 |
|||
**Status**: 🎯 **ACTIVE** - Production Ready |
|||
|
|||
## Overview |
|||
|
|||
This guide establishes **how time should be referenced and used** across the |
|||
development workflow. It is not tied to any one project, but applies to **all |
|||
feature development, issue investigations, ADRs, and documentation**. |
|||
|
|||
## General Principles |
|||
|
|||
- **Explicit over relative**: Always prefer absolute dates (`2025-08-17`) over |
|||
|
|||
relative references like "last week." |
|||
|
|||
- **ISO 8601 Standard**: Use `YYYY-MM-DD` format for all date references in |
|||
|
|||
docs, issues, ADRs, and commits. |
|||
|
|||
- **Time zones**: Default to **UTC** unless explicitly tied to user-facing |
|||
|
|||
behavior. |
|||
|
|||
- **Precision**: Only specify as much precision as needed (date vs. datetime vs. |
|||
|
|||
timestamp). |
|||
|
|||
- **Consistency**: Align time references across ADRs, commits, and investigation |
|||
|
|||
reports. |
|||
|
|||
## In Documentation & ADRs |
|||
|
|||
- Record decision dates using **absolute ISO dates**. |
|||
|
|||
- For ongoing timelines, state start and end explicitly (e.g., `2025-08-01` → |
|||
|
|||
`2025-08-17`). |
|||
|
|||
- Avoid ambiguous terms like *recently*, *last month*, or *soon*. |
|||
|
|||
- For time-based experiments (e.g., A/B tests), always include: |
|||
|
|||
- Start date |
|||
|
|||
- Expected duration |
|||
|
|||
- Review date checkpoint |
|||
|
|||
## In Code & Commits |
|||
|
|||
- Use **UTC timestamps** in logs, DB migrations, and serialized formats. |
|||
|
|||
- In commits, link changes to **date-bound ADRs or investigation docs**. |
|||
|
|||
- For migrations, include both **applied date** and **intended version window**. |
|||
|
|||
- Use constants for known fixed dates; avoid hardcoding arbitrary strings. |
|||
|
|||
## In Investigations & Research |
|||
|
|||
- Capture **when** an issue occurred (absolute time or version tag). |
|||
|
|||
- When describing failures: note whether they are **time-sensitive** (e.g., |
|||
|
|||
after |
|||
migrations, cache expirations). |
|||
|
|||
- Record diagnostic timelines in ISO format (not relative). |
|||
|
|||
- For performance regressions, annotate both **baseline timeframe** and |
|||
|
|||
**measurement timeframe**. |
|||
|
|||
## Collaboration Hooks |
|||
|
|||
- During reviews, verify **time references are clear, absolute, and |
|||
|
|||
standardized**. |
|||
|
|||
- In syncs, reframe relative terms ("this week") into shared absolute |
|||
|
|||
references. |
|||
|
|||
- Tag ADRs with both **date created** and **review by** checkpoints. |
|||
|
|||
## Self-Check Before Submitting |
|||
|
|||
- [ ] Did I check the time using the **developer's actual system time and |
|||
|
|||
timezone**? |
|||
|
|||
- [ ] Am I using absolute ISO dates? |
|||
|
|||
- [ ] Is UTC assumed unless specified otherwise? |
|||
|
|||
- [ ] Did I avoid ambiguous relative terms? |
|||
|
|||
- [ ] If duration matters, did I specify both start and end? |
|||
|
|||
- [ ] For future work, did I include a review/revisit date? |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/development/time_implementation.mdc` for |
|||
|
|||
detailed implementation instructions |
|||
|
|||
- `.cursor/rules/development/time_examples.mdc` for practical examples and patterns |
|||
|
|||
**Status**: Active time handling guidelines |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: None |
|||
**Stakeholders**: Development team, Documentation team |
|||
|
|||
**Maintainer**: Matthew Raymer |
|||
**Next Review**: 2025-09-17 |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Time-Related Work |
|||
|
|||
- [ ] **Time Context**: Understand what time information is needed |
|||
- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601) |
|||
- [ ] **Platform Check**: Identify platform-specific time requirements |
|||
- [ ] **User Context**: Consider user's timezone and preferences |
|||
|
|||
### During Time Implementation |
|||
|
|||
- [ ] **UTC Usage**: Use UTC for all system and log timestamps |
|||
- [ ] **Format Consistency**: Apply consistent time formatting patterns |
|||
- [ ] **Timezone Handling**: Properly handle timezone conversions |
|||
- [ ] **User Display**: Format times appropriately for user display |
|||
|
|||
### After Time Implementation |
|||
|
|||
- [ ] **Validation**: Verify time formats are correct and consistent |
|||
- [ ] **Testing**: Test time handling across different scenarios |
|||
- [ ] **Documentation**: Update relevant documentation with time patterns |
|||
- [ ] **Review**: Confirm implementation follows time standards |
@ -0,0 +1,243 @@ |
|||
# Time Examples — Practical Patterns |
|||
|
|||
> **Agent role**: Reference this file for practical examples and |
|||
patterns when working with time handling in development. |
|||
|
|||
## Examples |
|||
|
|||
### Good |
|||
|
|||
- "Feature flag rollout started on `2025-08-01` and will be reviewed on |
|||
|
|||
`2025-08-21`." |
|||
|
|||
- "Migration applied on `2025-07-15T14:00Z`." |
|||
|
|||
- "Issue reproduced on `2025-08-17T09:00-05:00 (local)` / |
|||
|
|||
`2025-08-17T14:00Z (UTC)`." |
|||
|
|||
### Bad |
|||
|
|||
- "Feature flag rolled out last week." |
|||
|
|||
- "Migration applied recently." |
|||
|
|||
- "Now is August, so we assume this was last month." |
|||
|
|||
### More Examples |
|||
|
|||
#### Issue Reports |
|||
|
|||
- ✅ **Good**: "User reported login failure at `2025-08-17T14:30:00Z`. Issue |
|||
|
|||
persisted until `2025-08-17T15:45:00Z`." |
|||
|
|||
- ❌ **Bad**: "User reported login failure earlier today. Issue lasted for a |
|||
|
|||
while." |
|||
|
|||
#### Release Planning |
|||
|
|||
- ✅ **Good**: "Feature X scheduled for release on `2025-08-25`. Testing |
|||
|
|||
window: `2025-08-20` to `2025-08-24`." |
|||
|
|||
- ❌ **Bad**: "Feature X will be released next week after testing." |
|||
|
|||
#### Performance Monitoring |
|||
|
|||
- ✅ **Good**: "Baseline performance measured on `2025-08-10T09:00:00Z`. |
|||
|
|||
Regression detected on `2025-08-15T14:00:00Z`." |
|||
|
|||
- ❌ **Bad**: "Performance was good last week but got worse this week." |
|||
|
|||
## Technical Implementation Examples |
|||
|
|||
### Database Storage |
|||
|
|||
```sql |
|||
|
|||
-- ✅ Good: Store in UTC |
|||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, |
|||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP |
|||
|
|||
-- ❌ Bad: Store in local time |
|||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, |
|||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP |
|||
|
|||
``` |
|||
|
|||
### API Responses |
|||
|
|||
```json |
|||
|
|||
// ✅ Good: Include both UTC and local time |
|||
{ |
|||
"eventTime": "2025-08-17T14:00:00Z", |
|||
"localTime": "2025-08-17T10:00:00-04:00", |
|||
"timezone": "America/New_York" |
|||
} |
|||
|
|||
// ❌ Bad: Only local time |
|||
{ |
|||
"eventTime": "2025-08-17T10:00:00-04:00" |
|||
} |
|||
|
|||
``` |
|||
|
|||
### Logging |
|||
|
|||
```python |
|||
|
|||
# ✅ Good: Log in UTC with timezone info |
|||
|
|||
logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)") |
|||
|
|||
# ❌ Bad: Log in local time |
|||
|
|||
logger.info(f"User action at {datetime.now()}") |
|||
|
|||
``` |
|||
|
|||
## Timezone Handling Examples |
|||
|
|||
### Good Timezone Usage |
|||
|
|||
```typescript |
|||
|
|||
// ✅ Good: Store UTC, convert for display |
|||
const eventTime = new Date().toISOString(); // Store in UTC |
|||
const localTime = new Date().toLocaleString('en-US', { |
|||
timeZone: 'America/New_York' |
|||
}); // Convert for display |
|||
|
|||
// ✅ Good: Include timezone context |
|||
const timestamp = { |
|||
utc: "2025-08-17T14:00:00Z", |
|||
local: "2025-08-17T10:00:00-04:00", |
|||
timezone: "America/New_York" |
|||
}; |
|||
|
|||
``` |
|||
|
|||
### Bad Timezone Usage |
|||
|
|||
```typescript |
|||
|
|||
// ❌ Bad: Assume timezone |
|||
const now = new Date(); // Assumes system timezone |
|||
|
|||
// ❌ Bad: Mix formats |
|||
const timestamp = "2025-08-17 10:00 AM"; // Ambiguous format |
|||
|
|||
``` |
|||
|
|||
## Common Patterns |
|||
|
|||
### Date Range References |
|||
|
|||
```typescript |
|||
|
|||
// ✅ Good: Explicit date ranges |
|||
const dateRange = { |
|||
start: "2025-08-01T00:00:00Z", |
|||
end: "2025-08-31T23:59:59Z" |
|||
}; |
|||
|
|||
// ❌ Bad: Relative ranges |
|||
const dateRange = { |
|||
start: "beginning of month", |
|||
end: "end of month" |
|||
}; |
|||
|
|||
``` |
|||
|
|||
### Duration References |
|||
|
|||
```typescript |
|||
|
|||
// ✅ Good: Specific durations |
|||
const duration = { |
|||
value: 30, |
|||
unit: "days", |
|||
startDate: "2025-08-01T00:00:00Z" |
|||
}; |
|||
|
|||
// ❌ Bad: Vague durations |
|||
const duration = "about a month"; |
|||
|
|||
``` |
|||
|
|||
### Version References |
|||
|
|||
```typescript |
|||
|
|||
// ✅ Good: Version with date |
|||
const version = { |
|||
number: "1.2.3", |
|||
releaseDate: "2025-08-17T10:00:00Z", |
|||
buildDate: "2025-08-17T09:30:00Z" |
|||
}; |
|||
|
|||
// ❌ Bad: Version without context |
|||
const version = "latest"; |
|||
|
|||
``` |
|||
|
|||
## References |
|||
|
|||
- [ISO 8601 Date and Time Standard](https://en.wikipedia.org/wiki/ISO_8601) |
|||
|
|||
- [IANA Timezone Database](https://www.iana.org/time-zones) |
|||
|
|||
- [ADR Template](./adr_template.md) |
|||
|
|||
- [Research & Diagnostic Workflow](./research_diagnostic.mdc) |
|||
|
|||
--- |
|||
|
|||
**Rule of Thumb**: Every time reference in development artifacts should be |
|||
**clear in 6 months without context**, and aligned to the **developer's actual |
|||
current time**. |
|||
|
|||
**Technical Rule of Thumb**: **Store in UTC, display in local time, always |
|||
include timezone context.** |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/development/time.mdc` for core principles |
|||
|
|||
- `.cursor/rules/development/time_implementation.mdc` for implementation instructions |
|||
|
|||
**Status**: Active examples and patterns |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: time.mdc, time_implementation.mdc |
|||
**Stakeholders**: Development team, Documentation team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Time Implementation |
|||
|
|||
- [ ] **Time Context**: Understand what time information needs to be implemented |
|||
- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601) |
|||
- [ ] **Platform Check**: Identify platform-specific time requirements |
|||
- [ ] **User Context**: Consider user's timezone and display preferences |
|||
|
|||
### During Time Implementation |
|||
|
|||
- [ ] **UTC Storage**: Use UTC for all system and log timestamps |
|||
- [ ] **Format Consistency**: Apply consistent time formatting patterns |
|||
- [ ] **Timezone Handling**: Properly handle timezone conversions |
|||
- [ ] **User Display**: Format times appropriately for user display |
|||
|
|||
### After Time Implementation |
|||
|
|||
- [ ] **Format Validation**: Verify time formats are correct and consistent |
|||
- [ ] **Cross-Platform Testing**: Test time handling across different platforms |
|||
- [ ] **Documentation**: Update relevant documentation with time patterns |
|||
- [ ] **User Experience**: Confirm time display is clear and user-friendly |
@ -0,0 +1,285 @@ |
|||
# Time Implementation — Technical Instructions |
|||
|
|||
> **Agent role**: Reference this file for detailed implementation instructions |
|||
when working with time handling in development. |
|||
|
|||
## Real-Time Context in Developer Interactions |
|||
|
|||
- The model must always resolve **"current time"** using the **developer's |
|||
|
|||
actual system time and timezone**. |
|||
|
|||
- When generating timestamps (e.g., in investigation logs, ADRs, or examples), |
|||
|
|||
the model should: |
|||
|
|||
- Use the **developer's current local time** by default. |
|||
|
|||
- Indicate the timezone explicitly (e.g., `2025-08-17T10:32-05:00`). |
|||
|
|||
- Optionally provide UTC alongside if context requires cross-team clarity. |
|||
|
|||
- When interpreting relative terms like *now*, *today*, *last week*: |
|||
|
|||
- Resolve them against the **developer's current time**. |
|||
|
|||
- Convert them into **absolute ISO-8601 values** in the output. |
|||
|
|||
## LLM Time Checking Instructions |
|||
|
|||
**CRITICAL**: The LLM must actively query the system for current time rather |
|||
than assuming or inventing times. |
|||
|
|||
### How to Check Current Time |
|||
|
|||
#### 1. **Query System Time (Required)** |
|||
|
|||
- **Always start** by querying the current system time using available tools |
|||
|
|||
- **Never assume** what the current time is |
|||
|
|||
- **Never use** placeholder values like "current time" or "now" |
|||
|
|||
#### 2. **Available Time Query Methods** |
|||
|
|||
- **System Clock**: Use `date` command or equivalent system time function |
|||
|
|||
- **Programming Language**: Use language-specific time functions (e.g., |
|||
|
|||
`Date.now()`, `datetime.now()`) |
|||
|
|||
- **Environment Variables**: Check for time-related environment variables |
|||
|
|||
- **API Calls**: Use time service APIs if available |
|||
|
|||
#### 3. **Required Time Information** |
|||
|
|||
When querying time, always obtain: |
|||
|
|||
- **Current Date**: YYYY-MM-DD format |
|||
|
|||
- **Current Time**: HH:MM:SS format (24-hour) |
|||
|
|||
- **Timezone**: Current system timezone or UTC offset |
|||
|
|||
- **UTC Equivalent**: Convert local time to UTC for cross-team clarity |
|||
|
|||
#### 4. **Time Query Examples** |
|||
|
|||
```bash |
|||
|
|||
# Example: Query system time |
|||
|
|||
$ date |
|||
|
|||
# Expected output: Mon Aug 17 10:32:45 EDT 2025 |
|||
|
|||
# Example: Query UTC time |
|||
|
|||
$ date -u |
|||
|
|||
# Expected output: Mon Aug 17 14:32:45 UTC 2025 |
|||
|
|||
``` |
|||
|
|||
```python |
|||
|
|||
# Example: Python time query |
|||
|
|||
import datetime |
|||
current_time = datetime.datetime.now() |
|||
utc_time = datetime.datetime.utcnow() |
|||
print(f"Local: {current_time}") |
|||
print(f"UTC: {utc_time}") |
|||
|
|||
``` |
|||
|
|||
```javascript |
|||
|
|||
// Example: JavaScript time query |
|||
const now = new Date(); |
|||
const utc = new Date().toISOString(); |
|||
console.log(`Local: ${now}`); |
|||
console.log(`UTC: ${utc}`); |
|||
|
|||
``` |
|||
|
|||
#### 5. **LLM Time Checking Workflow** |
|||
|
|||
1. **Query**: Actively query system for current time |
|||
|
|||
2. **Validate**: Confirm time data is reasonable and current |
|||
|
|||
3. **Format**: Convert to ISO 8601 format |
|||
|
|||
4. **Context**: Provide both local and UTC times when helpful |
|||
|
|||
5. **Document**: Show the source of time information |
|||
|
|||
#### 6. **Error Handling for Time Queries** |
|||
|
|||
- **If time query fails**: Ask user for current time or use "unknown time" |
|||
|
|||
with explanation |
|||
|
|||
- **If timezone unclear**: Default to UTC and ask for clarification |
|||
|
|||
- **If time seems wrong**: Verify with user before proceeding |
|||
|
|||
- **Always log**: Record when and how time was obtained |
|||
|
|||
#### 7. **Time Query Verification** |
|||
|
|||
Before using queried time, verify: |
|||
|
|||
- [ ] Time is recent (within last few minutes) |
|||
|
|||
- [ ] Timezone information is available |
|||
|
|||
- [ ] UTC conversion is accurate |
|||
|
|||
- [ ] Format follows ISO 8601 standard |
|||
|
|||
## Model Behavior Rules |
|||
|
|||
- **Never invent a "fake now"**: All "current time" references must come from |
|||
|
|||
the real system clock available at runtime. |
|||
|
|||
- **Check developer time zone**: If ambiguous, ask for clarification (e.g., |
|||
|
|||
"Should I use UTC or your local timezone?"). |
|||
|
|||
- **Format for clarity**: |
|||
|
|||
- Local time: `YYYY-MM-DDTHH:mm±hh:mm` |
|||
|
|||
- UTC equivalent (if needed): `YYYY-MM-DDTHH:mmZ` |
|||
|
|||
## Technical Implementation Notes |
|||
|
|||
### UTC Storage Principle |
|||
|
|||
- **Store all timestamps in UTC** in databases, logs, and serialized formats |
|||
|
|||
- **Convert to local time only for user display** |
|||
|
|||
- **Use ISO 8601 format** for all storage: `YYYY-MM-DDTHH:mm:ss.sssZ` |
|||
|
|||
### Common Implementation Patterns |
|||
|
|||
#### Database Storage |
|||
|
|||
```sql |
|||
|
|||
-- ✅ Good: Store in UTC |
|||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, |
|||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP |
|||
|
|||
``` |
|||
|
|||
#### API Responses |
|||
|
|||
```json |
|||
|
|||
// ✅ Good: Include both UTC and local time |
|||
{ |
|||
"eventTime": "2025-08-17T14:00:00Z", |
|||
"localTime": "2025-08-17T10:00:00-04:00", |
|||
"timezone": "America/New_York" |
|||
} |
|||
|
|||
``` |
|||
|
|||
#### Logging |
|||
|
|||
```python |
|||
|
|||
# ✅ Good: Log in UTC with timezone info |
|||
|
|||
logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)") |
|||
|
|||
``` |
|||
|
|||
### Timezone Handling Best Practices |
|||
|
|||
#### 1. Always Store Timezone Information |
|||
|
|||
- Include IANA timezone identifier (e.g., `America/New_York`) |
|||
|
|||
- Store UTC offset at time of creation |
|||
|
|||
- Handle daylight saving time transitions automatically |
|||
|
|||
#### 2. User Display Considerations |
|||
|
|||
- Convert UTC to user's preferred timezone |
|||
|
|||
- Show timezone abbreviation when helpful |
|||
|
|||
- Use relative time for recent events ("2 hours ago") |
|||
|
|||
#### 3. Edge Case Handling |
|||
|
|||
- **Daylight Saving Time**: Use timezone-aware libraries |
|||
|
|||
- **Leap Seconds**: Handle gracefully (rare but important) |
|||
|
|||
- **Invalid Times**: Validate before processing |
|||
|
|||
### Common Mistakes to Avoid |
|||
|
|||
#### 1. Timezone Confusion |
|||
|
|||
- ❌ **Don't**: Assume server timezone is user timezone |
|||
|
|||
- ✅ **Do**: Always convert UTC to user's local time for display |
|||
|
|||
#### 2. Format Inconsistency |
|||
|
|||
- ❌ **Don't**: Mix different time formats in the same system |
|||
|
|||
- ✅ **Do**: Standardize on ISO 8601 for all storage |
|||
|
|||
#### 3. Relative Time References |
|||
|
|||
- ❌ **Don't**: Use relative terms in persistent storage |
|||
|
|||
- ✅ **Do**: Convert relative terms to absolute timestamps immediately |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/development/time.mdc` for core principles |
|||
|
|||
- `.cursor/rules/development/time_examples.mdc` for practical examples |
|||
|
|||
**Status**: Active implementation guidelines |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: time.mdc |
|||
**Stakeholders**: Development team, DevOps team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Time Implementation |
|||
|
|||
- [ ] **Time Context**: Understand what time information needs to be implemented |
|||
- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601) |
|||
- [ ] **Platform Check**: Identify platform-specific time requirements |
|||
- [ ] **User Context**: Consider user's timezone and display preferences |
|||
|
|||
### During Time Implementation |
|||
|
|||
- [ ] **UTC Storage**: Use UTC for all system and log timestamps |
|||
- [ ] **Format Consistency**: Apply consistent time formatting patterns |
|||
- [ ] **Timezone Handling**: Properly handle timezone conversions |
|||
- [ ] **User Display**: Format times appropriately for user display |
|||
|
|||
### After Time Implementation |
|||
|
|||
- [ ] **Format Validation**: Verify time formats are correct and consistent |
|||
- [ ] **Cross-Platform Testing**: Test time handling across different platforms |
|||
- [ ] **Documentation**: Update relevant documentation with time patterns |
|||
- [ ] **User Experience**: Confirm time display is clear and user-friendly |
@ -1,14 +1,37 @@ |
|||
--- |
|||
alwaysApply: true |
|||
alwaysApply: false |
|||
--- |
|||
# Directive for Documentation Generation |
|||
|
|||
1. Produce a **small, focused set of documents** rather than an overwhelming volume. |
|||
2. Ensure the content is **maintainable and worth preserving**, so that humans |
|||
are motivated to keep it up to date. |
|||
are motivated to keep it up to date. |
|||
3. Prioritize **educational value**: the documents must clearly explain the |
|||
workings of the system. |
|||
4. Avoid **shallow, generic, or filler explanations** often found in |
|||
AI-generated documentation. |
|||
workings of the system. |
|||
4. Avoid **shallow, generic, or filler explanations** often found in AI-generated |
|||
documentation. |
|||
5. Aim for **clarity, depth, and usefulness**, so readers gain genuine understanding. |
|||
6. Always check the local system date to determine current date. |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Documentation Creation |
|||
|
|||
- [ ] **Scope Definition**: Define what needs to be documented |
|||
- [ ] **Audience Analysis**: Identify target readers and their needs |
|||
- [ ] **Content Planning**: Plan focused, educational content structure |
|||
- [ ] **Maintenance Planning**: Ensure content will be worth preserving |
|||
|
|||
### During Documentation Creation |
|||
|
|||
- [ ] **Educational Focus**: Clearly explain how the system works |
|||
- [ ] **Depth and Clarity**: Provide genuine understanding, not surface explanations |
|||
- [ ] **Focused Content**: Keep documents small and focused on specific topics |
|||
- [ ] **Current Date**: Check local system date for time-sensitive content |
|||
|
|||
### After Documentation Creation |
|||
|
|||
- [ ] **Quality Review**: Ensure content is clear, deep, and useful |
|||
- [ ] **Maintainability Check**: Verify content motivates humans to keep it updated |
|||
- [ ] **Audience Validation**: Confirm content meets target reader needs |
|||
- [ ] **Integration**: Integrate with existing documentation structure |
|||
|
@ -1,332 +0,0 @@ |
|||
--- |
|||
globs: *.md |
|||
alwaysApply: false |
|||
--- |
|||
# Cursor Markdown Ruleset for TimeSafari Documentation |
|||
|
|||
## Overview |
|||
|
|||
This ruleset enforces consistent markdown formatting standards across all project |
|||
documentation, ensuring readability, maintainability, and compliance with |
|||
markdownlint best practices. |
|||
|
|||
## General Formatting Standards |
|||
|
|||
### Line Length |
|||
|
|||
- **Maximum line length**: 80 characters |
|||
- **Exception**: Code blocks (JSON, shell, TypeScript, etc.) - no line length |
|||
enforcement |
|||
- **Rationale**: Ensures readability across different screen sizes and terminal |
|||
widths |
|||
|
|||
### Blank Lines |
|||
|
|||
- **Headings**: Must be surrounded by blank lines above and below |
|||
- **Lists**: Must be surrounded by blank lines above and below |
|||
- **Code blocks**: Must be surrounded by blank lines above and below |
|||
- **Maximum consecutive blank lines**: 1 (no multiple blank lines) |
|||
- **File start**: No blank lines at the beginning of the file |
|||
- **File end**: Single newline character at the end |
|||
|
|||
### Whitespace |
|||
|
|||
- **No trailing spaces**: Remove all trailing whitespace from lines |
|||
- **No tabs**: Use spaces for indentation |
|||
- **Consistent indentation**: 2 spaces for list items and nested content |
|||
|
|||
## Heading Standards |
|||
|
|||
### Format |
|||
|
|||
- **Style**: ATX-style headings (`#`, `##`, `###`, etc.) |
|||
- **Case**: Title case for general headings |
|||
- **Code references**: Use backticks for file names and technical terms |
|||
- ✅ `### Current package.json Scripts` |
|||
- ❌ `### Current Package.json Scripts` |
|||
|
|||
### Hierarchy |
|||
|
|||
- **H1 (#)**: Document title only |
|||
- **H2 (##)**: Major sections |
|||
- **H3 (###)**: Subsections |
|||
- **H4 (####)**: Sub-subsections |
|||
- **H5+**: Avoid deeper nesting |
|||
|
|||
## List Standards |
|||
|
|||
### Unordered Lists |
|||
|
|||
- **Marker**: Use `-` (hyphen) consistently |
|||
- **Indentation**: 2 spaces for nested items |
|||
- **Blank lines**: Surround lists with blank lines |
|||
|
|||
### Ordered Lists |
|||
|
|||
- **Format**: `1.`, `2.`, `3.` (sequential numbering) |
|||
- **Indentation**: 2 spaces for nested items |
|||
- **Blank lines**: Surround lists with blank lines |
|||
|
|||
### Task Lists |
|||
|
|||
- **Format**: `- [ ]` for incomplete, `- [x]` for complete |
|||
- **Use case**: Project planning, checklists, implementation tracking |
|||
|
|||
## Code Block Standards |
|||
|
|||
### Fenced Code Blocks |
|||
|
|||
- **Syntax**: Triple backticks with language specification |
|||
- **Languages**: `json`, `bash`, `typescript`, `javascript`, `yaml`, `markdown` |
|||
- **Blank lines**: Must be surrounded by blank lines above and below |
|||
- **Line length**: No enforcement within code blocks |
|||
|
|||
### Inline Code |
|||
|
|||
- **Format**: Single backticks for inline code references |
|||
- **Use case**: File names, commands, variables, properties |
|||
|
|||
## Special Content Standards |
|||
|
|||
### JSON Examples |
|||
|
|||
```json |
|||
{ |
|||
"property": "value", |
|||
"nested": { |
|||
"property": "value" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Shell Commands |
|||
|
|||
```bash |
|||
# Command with comment |
|||
npm run build:web |
|||
|
|||
# Multi-line command |
|||
VITE_GIT_HASH=`git log -1 --pretty=format:%h` \ |
|||
vite build --config vite.config.web.mts |
|||
``` |
|||
|
|||
### TypeScript Examples |
|||
|
|||
```typescript |
|||
// Function with JSDoc |
|||
/** |
|||
* Get environment configuration |
|||
* @param env - Environment name |
|||
* @returns Environment config object |
|||
*/ |
|||
const getEnvironmentConfig = (env: string) => { |
|||
switch (env) { |
|||
case 'prod': |
|||
return { /* production settings */ }; |
|||
default: |
|||
return { /* development settings */ }; |
|||
} |
|||
}; |
|||
``` |
|||
|
|||
## File Structure Standards |
|||
|
|||
### Document Header |
|||
|
|||
```markdown |
|||
# Document Title |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: YYYY-MM-DD |
|||
**Status**: 🎯 **STATUS** - Brief description |
|||
|
|||
## Overview |
|||
|
|||
Brief description of the document's purpose and scope. |
|||
``` |
|||
|
|||
### Section Organization |
|||
|
|||
1. **Overview/Introduction** |
|||
2. **Current State Analysis** |
|||
3. **Implementation Plan** |
|||
4. **Technical Details** |
|||
5. **Testing & Validation** |
|||
6. **Next Steps** |
|||
|
|||
## Markdownlint Configuration |
|||
|
|||
### Required Rules |
|||
|
|||
```json |
|||
{ |
|||
"MD013": { "code_blocks": false }, |
|||
"MD012": true, |
|||
"MD022": true, |
|||
"MD031": true, |
|||
"MD032": true, |
|||
"MD047": true, |
|||
"MD009": true |
|||
} |
|||
``` |
|||
|
|||
### Rule Explanations |
|||
|
|||
- **MD013**: Line length (disabled for code blocks) |
|||
- **MD012**: No multiple consecutive blank lines |
|||
- **MD022**: Headings should be surrounded by blank lines |
|||
- **MD031**: Fenced code blocks should be surrounded by blank lines |
|||
- **MD032**: Lists should be surrounded by blank lines |
|||
- **MD047**: Files should end with a single newline |
|||
- **MD009**: No trailing spaces |
|||
|
|||
## Validation Commands |
|||
|
|||
### Check Single File |
|||
|
|||
```bash |
|||
npx markdownlint docs/filename.md |
|||
``` |
|||
|
|||
### Check All Documentation |
|||
|
|||
```bash |
|||
npx markdownlint docs/ |
|||
``` |
|||
|
|||
### Auto-fix Common Issues |
|||
|
|||
```bash |
|||
# Remove trailing spaces |
|||
sed -i 's/[[:space:]]*$//' docs/filename.md |
|||
|
|||
# Remove multiple blank lines |
|||
sed -i '/^$/N;/^\n$/D' docs/filename.md |
|||
|
|||
# Add newline at end if missing |
|||
echo "" >> docs/filename.md |
|||
``` |
|||
|
|||
## Common Patterns |
|||
|
|||
### Implementation Plans |
|||
|
|||
```markdown |
|||
## Implementation Plan |
|||
|
|||
### Phase 1: Foundation (Day 1) |
|||
|
|||
#### 1.1 Component Setup |
|||
|
|||
- [ ] Create new component file |
|||
- [ ] Add basic structure |
|||
- [ ] Implement core functionality |
|||
|
|||
#### 1.2 Configuration |
|||
|
|||
- [ ] Update configuration files |
|||
- [ ] Add environment variables |
|||
- [ ] Test configuration loading |
|||
``` |
|||
|
|||
### Status Tracking |
|||
|
|||
```markdown |
|||
**Status**: ✅ **COMPLETE** - All phases finished |
|||
**Progress**: 75% (15/20 components) |
|||
**Next**: Ready for testing phase |
|||
``` |
|||
|
|||
### Performance Metrics |
|||
|
|||
```markdown |
|||
#### 📊 Performance Metrics |
|||
- **Build Time**: 2.3 seconds (50% faster than baseline) |
|||
- **Bundle Size**: 1.2MB (30% reduction) |
|||
- **Success Rate**: 100% (no failures in 50 builds) |
|||
``` |
|||
|
|||
## Enforcement |
|||
|
|||
### Pre-commit Hooks |
|||
|
|||
- Run markdownlint on all changed markdown files |
|||
- Block commits with linting violations |
|||
- Auto-fix common issues when possible |
|||
|
|||
### CI/CD Integration |
|||
|
|||
- Include markdownlint in build pipeline |
|||
- Generate reports for documentation quality |
|||
- Fail builds with critical violations |
|||
|
|||
### Team Guidelines |
|||
|
|||
- All documentation PRs must pass markdownlint |
|||
- Use provided templates for new documents |
|||
- Follow established patterns for consistency |
|||
|
|||
## Templates |
|||
|
|||
### New Document Template |
|||
|
|||
```markdown |
|||
# Document Title |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: YYYY-MM-DD |
|||
**Status**: 🎯 **PLANNING** - Ready for Implementation |
|||
|
|||
## Overview |
|||
|
|||
Brief description of the document's purpose and scope. |
|||
|
|||
## Current State |
|||
|
|||
Description of current situation or problem. |
|||
|
|||
## Implementation Plan |
|||
|
|||
### Phase 1: Foundation |
|||
|
|||
- [ ] Task 1 |
|||
- [ ] Task 2 |
|||
|
|||
## Next Steps |
|||
|
|||
1. **Review and approve plan** |
|||
2. **Begin implementation** |
|||
3. **Test and validate** |
|||
|
|||
--- |
|||
|
|||
**Status**: Ready for implementation |
|||
**Priority**: Medium |
|||
**Estimated Effort**: X days |
|||
**Dependencies**: None |
|||
**Stakeholders**: Development team |
|||
``` |
|||
|
|||
--- |
|||
|
|||
**Last Updated**: 2025-07-09 |
|||
**Version**: 1.0 |
|||
**Maintainer**: Matthew Raymer |
|||
|
|||
|
|||
### Heading Uniqueness |
|||
|
|||
- **Rule**: No duplicate heading content at the same level |
|||
- **Scope**: Within a single document |
|||
- **Rationale**: Maintains clear document structure and navigation |
|||
- **Example**: |
|||
|
|||
```markdown |
|||
## Features ✅ |
|||
### Authentication |
|||
### Authorization |
|||
|
|||
## Features ❌ (Duplicate heading) |
|||
### Security |
|||
### Performance |
|||
``` |
@ -0,0 +1,210 @@ |
|||
# Markdown Core Standards & Automation |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-21 |
|||
**Status**: 🎯 **ACTIVE** - Core markdown standards and automation |
|||
|
|||
## Overview |
|||
|
|||
This file combines core markdown formatting standards with automation |
|||
guidelines. AI agents must follow these rules DURING content generation, |
|||
not apply them after the fact. |
|||
|
|||
**Primary Focus**: Create educational content that increases human |
|||
competence, not just technical descriptions. |
|||
|
|||
## AI Generation Guidelines |
|||
|
|||
### **MANDATORY**: Follow These Rules While Writing |
|||
|
|||
When generating markdown content, you MUST: |
|||
|
|||
1. **Line Length**: Never exceed 80 characters per line |
|||
2. **Blank Lines**: Always add blank lines around headings, lists, and |
|||
code blocks |
|||
3. **Structure**: Use proper heading hierarchy and document templates |
|||
4. **Formatting**: Apply consistent formatting patterns immediately |
|||
5. **Educational Value**: Focus on increasing reader competence and |
|||
understanding |
|||
|
|||
### **DO NOT**: Generate content that violates these rules |
|||
|
|||
- ❌ Generate long lines that need breaking |
|||
- ❌ Create content without proper blank line spacing |
|||
- ❌ Use inconsistent formatting patterns |
|||
- ❌ Assume post-processing will fix violations |
|||
- ❌ Focus only on technical details without educational context |
|||
- ❌ Assume reader has extensive prior knowledge |
|||
|
|||
### **DO**: Generate compliant content from the start |
|||
|
|||
- ✅ Write within 80-character limits |
|||
- ✅ Add blank lines around all structural elements |
|||
- ✅ Use established templates and patterns |
|||
- ✅ Apply formatting standards immediately |
|||
- ✅ Explain concepts before implementation details |
|||
- ✅ Provide context and motivation for technical choices |
|||
- ✅ Include examples that illustrate key concepts |
|||
|
|||
## Core Formatting Standards |
|||
|
|||
### Line Length |
|||
|
|||
- **Maximum line length**: 80 characters |
|||
- **Exception**: Code blocks (JSON, shell, TypeScript, etc.) - no line |
|||
length enforcement |
|||
- **Rationale**: Ensures readability across different screen sizes and |
|||
terminal widths |
|||
|
|||
### Blank Lines |
|||
|
|||
- **Headings**: Must be surrounded by blank lines above and below |
|||
- **Lists**: Must be surrounded by blank lines above and below |
|||
- **Code blocks**: Must be surrounded by blank lines above and below |
|||
- **Maximum consecutive blank lines**: 1 (no multiple blank lines) |
|||
- **File start**: No blank lines at the beginning of the file |
|||
- **File end**: Single newline character at the end |
|||
|
|||
### Whitespace |
|||
|
|||
- **No trailing spaces**: Remove all trailing whitespace from lines |
|||
- **No tabs**: Use spaces for indentation |
|||
- **Consistent indentation**: 2 spaces for list items and nested content |
|||
|
|||
## Heading Standards |
|||
|
|||
### Format |
|||
|
|||
- **Style**: ATX-style headings (`#`, `##`, `###`, etc.) |
|||
- **Case**: Title case for general headings |
|||
- **Code references**: Use backticks for file names and technical terms |
|||
- ✅ `### Current package.json Scripts` |
|||
- ❌ `### Current Package.json Scripts` |
|||
|
|||
### Hierarchy |
|||
|
|||
- **H1 (#)**: Document title only |
|||
- **H2 (##)**: Major sections |
|||
- **H3 (###)**: Subsections |
|||
- **H4 (####)**: Sub-subsections |
|||
- **H5+**: Avoid deeper nesting |
|||
|
|||
## List Standards |
|||
|
|||
### Unordered Lists |
|||
|
|||
- **Marker**: Use `-` (hyphen) consistently |
|||
- **Indentation**: 2 spaces for nested items |
|||
- **Blank lines**: Surround lists with blank lines |
|||
|
|||
### Ordered Lists |
|||
|
|||
- **Format**: `1.`, `2.`, `3.` (sequential numbering) |
|||
- **Indentation**: 2 spaces for nested items |
|||
- **Blank lines**: Surround lists with blank lines |
|||
|
|||
### Task Lists |
|||
|
|||
- **Format**: `- [ ]` for incomplete, `- [x]` for complete |
|||
- **Indentation**: 2 spaces for nested items |
|||
- **Blank lines**: Surround lists with blank lines |
|||
|
|||
## Educational Content Standards |
|||
|
|||
### **Content Structure for Learning** |
|||
|
|||
- **Concept First**: Explain what something is before how to use it |
|||
- **Context Matters**: Explain why and when to use a feature |
|||
- **Progressive Disclosure**: Start simple, add complexity gradually |
|||
- **Real Examples**: Use concrete, relatable scenarios |
|||
- **Common Questions**: Anticipate and answer reader questions |
|||
|
|||
### **Writing for Understanding** |
|||
|
|||
- **Conversational Tone**: Write as if explaining to a colleague |
|||
- **Active Voice**: "You can do this" not "This can be done" |
|||
- **Question Format**: "What happens when..." to engage thinking |
|||
- **Analogies**: Use familiar concepts to explain complex ideas |
|||
- **Limitations**: Clearly state what solutions don't do |
|||
|
|||
## Code Block Standards |
|||
|
|||
### Inline Code |
|||
|
|||
- **Format**: Single backticks for inline code |
|||
- **Use cases**: File names, commands, variables, technical terms |
|||
- **Examples**: `package.json`, `npm run build`, `VITE_PLATFORM` |
|||
|
|||
### Code Blocks |
|||
|
|||
- **Format**: Triple backticks with language specification |
|||
- **Language**: Always specify the language for syntax highlighting |
|||
- **Blank lines**: Surround with blank lines above and below |
|||
|
|||
## Automation System |
|||
|
|||
### Available Commands |
|||
|
|||
- **`npm run markdown:fix`** - Fix formatting in all markdown files |
|||
using markdownlint-cli2 --fix |
|||
- **`npm run markdown:check`** - Validate formatting without fixing |
|||
using markdownlint-cli2 |
|||
|
|||
### How It Works |
|||
|
|||
1. **AI Agent Compliance** (Primary): AI follows markdown rules during |
|||
generation |
|||
2. **Pre-commit Hooks** (Backup): Catches any remaining formatting |
|||
issues |
|||
3. **GitHub Actions** (Pre-merge): Validates formatting before merge |
|||
|
|||
### Benefits |
|||
|
|||
- **No more manual fixes** - AI generates compliant content from start |
|||
- **Consistent style** - All files follow same standards |
|||
- **Faster development** - No need to fix formatting manually |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Generating Markdown Content |
|||
|
|||
- [ ] **Line Length**: Ensure no line exceeds 80 characters |
|||
- [ ] **Blank Lines**: Add blank lines around headings, lists, and code blocks |
|||
- [ ] **Whitespace**: Remove all trailing spaces, use 2-space indentation |
|||
- [ ] **Headings**: Use ATX-style with proper hierarchy (H1 for title only) |
|||
- [ ] **Lists**: Use consistent markers (- for unordered, 1. for ordered) |
|||
- [ ] **Code**: Specify language for fenced blocks, use backticks for inline |
|||
- [ ] **Educational Focus**: Plan content structure for learning progression |
|||
- [ ] **Audience Consideration**: Identify target reader knowledge level |
|||
|
|||
### After Generating Markdown Content |
|||
|
|||
- [ ] **Validation**: Run `npm run markdown:check` to verify compliance |
|||
- [ ] **Auto-fix**: Use `npm run markdown:fix` if any issues found |
|||
- [ ] **Review**: Confirm content follows established templates and patterns |
|||
- [ ] **Cross-reference**: Link to related documentation and templates |
|||
- [ ] **Educational Review**: Verify content increases reader competence |
|||
- [ ] **Example Validation**: Ensure examples illustrate key concepts clearly |
|||
|
|||
### Quality Assurance |
|||
|
|||
- [ ] **Readability**: Content is clear and follows project conventions |
|||
- [ ] **Consistency**: Formatting matches existing documentation style |
|||
- [ ] **Completeness**: All required sections and information included |
|||
- [ ] **Accuracy**: Technical details are correct and up-to-date |
|||
- [ ] **Educational Value**: Content increases reader understanding and competence |
|||
- [ ] **Context Clarity**: Reader understands when and why to use the information |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow |
|||
- `.cursor/rules/docs/markdown_templates.mdc` for document templates |
|||
- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows |
|||
|
|||
**Status**: Active core standards and automation |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: None |
|||
**Stakeholders**: Documentation team, Development team |
@ -0,0 +1,314 @@ |
|||
# Markdown Templates & Examples |
|||
|
|||
> **Agent role**: Reference this file for document templates, structure, |
|||
> and examples when creating new documentation. |
|||
> |
|||
> **Focus**: Create educational content that increases human competence, |
|||
> not just technical descriptions. |
|||
|
|||
## Document Templates |
|||
|
|||
### Standard Document Template |
|||
|
|||
```markdown |
|||
# Document Title |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: YYYY-MM-DD |
|||
**Status**: 🎯 **STATUS** - Brief description |
|||
|
|||
## Overview |
|||
|
|||
Brief description of the document's purpose and scope. |
|||
|
|||
**Educational Goal**: What will the reader learn and how will it increase |
|||
their competence? |
|||
|
|||
## Current State |
|||
|
|||
Description of current situation or problem. |
|||
|
|||
**Why This Matters**: Explain the business value and user benefit of |
|||
addressing this situation. |
|||
|
|||
## Implementation Plan |
|||
|
|||
### Phase 1: Foundation |
|||
|
|||
- [ ] Task 1 |
|||
- [ ] Task 2 |
|||
|
|||
**Learning Context**: What concepts should the reader understand before |
|||
proceeding with implementation? |
|||
|
|||
## Next Steps |
|||
|
|||
1. **Review and approve plan** |
|||
2. **Begin implementation** |
|||
3. **Test and validate** |
|||
|
|||
**Continued Learning**: Where can the reader go next to deepen their |
|||
understanding? |
|||
|
|||
--- |
|||
|
|||
**Status**: Ready for implementation |
|||
**Priority**: Medium |
|||
**Estimated Effort**: X days |
|||
**Dependencies**: None |
|||
**Stakeholders**: Development team |
|||
``` |
|||
|
|||
### Technical Specification Template |
|||
|
|||
```markdown |
|||
# Technical Specification: [Feature Name] |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: YYYY-MM-DD |
|||
**Status**: 🎯 **DRAFT** - Under Review |
|||
|
|||
## Overview |
|||
|
|||
Brief description of the technical specification. |
|||
|
|||
**Business Context**: Why is this specification needed and what problem |
|||
does it solve for users? |
|||
|
|||
## Requirements |
|||
|
|||
### Functional Requirements |
|||
|
|||
- [ ] Requirement 1 |
|||
- [ ] Requirement 2 |
|||
|
|||
### Non-Functional Requirements |
|||
|
|||
- [ ] Performance requirement |
|||
- [ ] Security requirement |
|||
|
|||
## Technical Design |
|||
|
|||
### Architecture |
|||
|
|||
Description of the technical architecture. |
|||
|
|||
**Design Rationale**: Why was this architecture chosen over alternatives? |
|||
What are the trade-offs and benefits? |
|||
|
|||
### Data Models |
|||
|
|||
```typescript |
|||
interface ExampleModel { |
|||
id: string; |
|||
name: string; |
|||
createdAt: Date; |
|||
} |
|||
``` |
|||
|
|||
### API Design |
|||
|
|||
```typescript |
|||
interface APIResponse<T> { |
|||
success: boolean; |
|||
data: T; |
|||
error?: string; |
|||
} |
|||
``` |
|||
|
|||
## Testing Strategy |
|||
|
|||
- [ ] Unit tests |
|||
|
|||
**Learning from Testing**: What insights does testing provide about the |
|||
system's behavior and design? |
|||
|
|||
--- |
|||
|
|||
## Educational Documentation Template |
|||
|
|||
### **Concept Explanation Template** |
|||
|
|||
```markdown |
|||
## What is [Concept Name]? |
|||
|
|||
Brief, clear definition of the concept. |
|||
|
|||
## Why Does [Concept Name] Matter? |
|||
|
|||
Explain the business value and user benefit. |
|||
|
|||
## How Does [Concept Name] Work? |
|||
|
|||
High-level explanation of the mechanism. |
|||
|
|||
## When Would You Use [Concept Name]? |
|||
|
|||
Real-world scenarios and use cases. |
|||
|
|||
## Common Misconceptions |
|||
|
|||
Address typical misunderstandings. |
|||
|
|||
## Examples |
|||
|
|||
Concrete examples that illustrate the concept. |
|||
|
|||
## Next Steps |
|||
|
|||
Where to learn more about related concepts. |
|||
``` |
|||
|
|||
### **Tutorial Template** |
|||
|
|||
```markdown |
|||
## Learning Objective |
|||
|
|||
What the reader will accomplish by the end. |
|||
|
|||
## Prerequisites |
|||
|
|||
What the reader should know before starting. |
|||
|
|||
## Step-by-Step Guide |
|||
|
|||
1. **Step 1**: What to do and why |
|||
2. **Step 2**: What to do and why |
|||
3. **Step 3**: What to do and why |
|||
|
|||
## Verification |
|||
|
|||
How to confirm the tutorial was successful. |
|||
|
|||
## Troubleshooting |
|||
|
|||
Common issues and how to resolve them. |
|||
|
|||
## What You've Learned |
|||
|
|||
Summary of key concepts and skills. |
|||
|
|||
## Next Steps |
|||
|
|||
Where to apply this knowledge next. |
|||
``` |
|||
- [ ] Integration tests |
|||
- [ ] E2E tests |
|||
|
|||
--- |
|||
|
|||
**Status**: Draft |
|||
**Priority**: High |
|||
**Estimated Effort**: X days |
|||
**Dependencies**: None |
|||
**Stakeholders**: Development team |
|||
|
|||
``` |
|||
|
|||
## Content Examples |
|||
|
|||
### JSON Examples |
|||
|
|||
```json |
|||
{ |
|||
"property": "value", |
|||
"nested": { |
|||
"property": "value" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Shell Commands |
|||
|
|||
```bash |
|||
# Command with comment |
|||
npm run build:web |
|||
|
|||
# Multi-line command |
|||
VITE_GIT_HASH=`git log -1 --pretty=format:%h` \ |
|||
vite build --config vite.config.web.mts |
|||
``` |
|||
|
|||
### TypeScript Examples |
|||
|
|||
```typescript |
|||
// Function with JSDoc |
|||
const getEnvironmentConfig = (env: string) => { |
|||
switch (env) { |
|||
case 'prod': |
|||
return { /* production settings */ }; |
|||
default: |
|||
return { /* development settings */ }; |
|||
} |
|||
}; |
|||
``` |
|||
|
|||
## File Structure Standards |
|||
|
|||
### Document Header |
|||
|
|||
```markdown |
|||
# Document Title |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: YYYY-MM-DD |
|||
**Status**: 🎯 **STATUS** - Brief description |
|||
|
|||
## Overview |
|||
|
|||
Brief description of the document's purpose and scope. |
|||
``` |
|||
|
|||
### Section Organization |
|||
|
|||
Standard sections: Overview, Current State, Implementation Plan, |
|||
Technical Details, Testing & Validation, Next Steps |
|||
|
|||
## Common Patterns |
|||
|
|||
Standard implementation plans follow Phase 1 (Foundation), Phase 2 |
|||
(Features), Phase 3 (Testing & Polish) structure. |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Using Templates |
|||
|
|||
- [ ] **Template Selection**: Choose appropriate template for document type |
|||
- [ ] **Structure Review**: Understand required sections and organization |
|||
- [ ] **Content Planning**: Plan what information goes in each section |
|||
- [ ] **Audience Analysis**: Ensure template matches target audience needs |
|||
|
|||
### During Template Usage |
|||
|
|||
- [ ] **Section Completion**: Fill in all required sections completely |
|||
- [ ] **Example Integration**: Include relevant code examples and patterns |
|||
- [ ] **Formatting Consistency**: Apply markdown standards from core rules |
|||
- [ ] **Cross-references**: Link to related documentation and resources |
|||
|
|||
### After Template Usage |
|||
|
|||
- [ ] **Content Review**: Verify all sections contain appropriate content |
|||
- [ ] **Formatting Check**: Run `npm run markdown:check` for compliance |
|||
- [ ] **Template Validation**: Confirm document follows template structure |
|||
- [ ] **Quality Assessment**: Ensure content meets project standards |
|||
|
|||
### Template-Specific Requirements |
|||
|
|||
- [ ] **Standard Documents**: Include all required metadata and sections |
|||
- [ ] **Technical Specs**: Complete all requirement and design sections |
|||
- [ ] **Implementation Plans**: Define clear phases and milestones |
|||
- [ ] **Examples**: Provide relevant, working code examples |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow |
|||
- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards |
|||
- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows |
|||
|
|||
**Status**: Active templates and examples |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: markdown_core.mdc |
|||
**Stakeholders**: Documentation team, Development team |
@ -0,0 +1,168 @@ |
|||
# Markdown Workflow & Validation |
|||
|
|||
> **Agent role**: Reference this file for markdown validation rules, |
|||
> enforcement procedures, and workflow management. |
|||
|
|||
## Markdownlint Configuration |
|||
|
|||
### Core Rules |
|||
|
|||
```json |
|||
{ |
|||
"MD013": { "line_length": 80, "code_blocks": false }, |
|||
"MD012": true, |
|||
"MD022": true, |
|||
"MD031": true, |
|||
"MD032": true, |
|||
"MD047": true, |
|||
"MD009": true, |
|||
"MD004": { "style": "dash" } |
|||
} |
|||
``` |
|||
|
|||
### Rule Explanations |
|||
|
|||
- **MD013**: Line length (80 chars, disabled for code blocks) |
|||
- **MD012**: No multiple consecutive blank lines |
|||
- **MD022**: Headings should be surrounded by blank lines |
|||
- **MD031**: Fenced code blocks should be surrounded by blank lines |
|||
- **MD032**: Lists should be surrounded by blank lines |
|||
- **MD047**: Files should end with a single newline |
|||
- **MD009**: No trailing spaces |
|||
- **MD004**: Consistent list markers (dash style) |
|||
|
|||
## Validation Commands |
|||
|
|||
### Check All MDC Files |
|||
|
|||
```bash |
|||
npm run markdown:check |
|||
``` |
|||
|
|||
### Auto-fix Formatting Issues |
|||
|
|||
```bash |
|||
npm run markdown:fix |
|||
``` |
|||
|
|||
### Check Single File |
|||
|
|||
```bash |
|||
npx markdownlint-cli2 .cursor/rules/filename.mdc |
|||
``` |
|||
|
|||
## Enforcement Workflow |
|||
|
|||
### Pre-commit Hooks |
|||
|
|||
- **Automatic**: `lint-staged` runs `markdownlint-cli2 --fix` on all |
|||
staged `.mdc` files |
|||
- **Result**: Files are automatically formatted before commit |
|||
- **Blocking**: Commits with unfixable violations are blocked |
|||
|
|||
### CI/CD Integration |
|||
|
|||
- **Build Pipeline**: Include markdownlint in automated builds |
|||
- **Quality Reports**: Generate documentation quality metrics |
|||
- **Build Failure**: Fail builds with critical violations |
|||
|
|||
### Team Guidelines |
|||
|
|||
- **PR Requirements**: All documentation PRs must pass markdownlint |
|||
- **Templates**: Use provided templates for new documents |
|||
- **Patterns**: Follow established patterns for consistency |
|||
- **Auto-fixing**: Let automation handle formatting, focus on content |
|||
|
|||
## Quality Assurance |
|||
|
|||
### Validation Checklist |
|||
|
|||
- [ ] All files pass `npm run markdown:check` |
|||
- [ ] Line length under 80 characters |
|||
- [ ] Proper blank line spacing around elements |
|||
- [ ] No trailing spaces |
|||
- [ ] Consistent list markers |
|||
- [ ] Proper heading hierarchy |
|||
- [ ] Code blocks have language specification |
|||
|
|||
### Common Issues & Fixes |
|||
|
|||
#### Trailing Spaces |
|||
|
|||
```bash |
|||
# Remove trailing spaces |
|||
sed -i 's/[[:space:]]*$//' .cursor/rules/**/*.mdc |
|||
``` |
|||
|
|||
#### Multiple Blank Lines |
|||
|
|||
```bash |
|||
# Remove multiple blank lines |
|||
sed -i '/^$/N;/^\n$/D' .cursor/rules/**/*.mdc |
|||
``` |
|||
|
|||
#### Missing Newlines |
|||
|
|||
```bash |
|||
# Add newline at end if missing |
|||
find .cursor/rules -name "*.mdc" -exec sed -i -e '$a\' {} \; |
|||
``` |
|||
|
|||
## Integration Points |
|||
|
|||
### Git Workflow |
|||
|
|||
1. **Edit**: Make changes to MDC files |
|||
2. **Stage**: `git add .cursor/rules/filename.mdc` |
|||
3. **Auto-fix**: `lint-staged` runs `markdownlint-cli2 --fix` |
|||
4. **Commit**: Changes are committed with perfect formatting |
|||
|
|||
### Development Workflow |
|||
|
|||
1. **Create/Edit**: Use templates from `markdown_templates.mdc` |
|||
2. **Validate**: Run `npm run markdown:check` before committing |
|||
3. **Auto-fix**: Use `npm run markdown:fix` for bulk fixes |
|||
4. **Review**: Ensure content quality, not just formatting |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Starting Workflow |
|||
|
|||
- [ ] **Configuration Review**: Understand markdownlint rules and settings |
|||
- [ ] **Tool Availability**: Ensure markdownlint-cli2 is installed and working |
|||
- [ ] **File Scope**: Identify which files need validation or fixing |
|||
- [ ] **Backup Strategy**: Consider backing up files before bulk operations |
|||
|
|||
### During Workflow Execution |
|||
|
|||
- [ ] **Validation First**: Run `npm run markdown:check` to identify issues |
|||
- [ ] **Issue Analysis**: Review and understand each validation error |
|||
- [ ] **Auto-fix Application**: Use `npm run markdown:fix` for automatic fixes |
|||
- [ ] **Manual Review**: Check files that couldn't be auto-fixed |
|||
|
|||
### After Workflow Completion |
|||
|
|||
- [ ] **Final Validation**: Confirm all files pass `npm run markdown:check` |
|||
- [ ] **Quality Review**: Verify formatting meets project standards |
|||
- [ ] **Documentation Update**: Update any related documentation or guides |
|||
- [ ] **Team Communication**: Share workflow results and any manual fixes needed |
|||
|
|||
### Workflow-Specific Requirements |
|||
|
|||
- [ ] **Pre-commit Hooks**: Ensure lint-staged configuration is working |
|||
- [ ] **CI/CD Integration**: Verify build pipeline includes markdown validation |
|||
- [ ] **Team Guidelines**: Confirm all team members understand the workflow |
|||
- [ ] **Error Resolution**: Document common issues and their solutions |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards |
|||
- `.cursor/rules/docs/markdown_templates.mdc` for document templates |
|||
|
|||
**Status**: Active workflow and validation |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: markdown_core.mdc, markdown_templates.mdc |
|||
**Stakeholders**: Development team, Documentation team |
@ -0,0 +1,225 @@ |
|||
# Camera Platform-Specific Implementation |
|||
|
|||
> **Agent role**: |
|||
Reference this file for platform-specific camera implementation details. |
|||
|
|||
## Web Platform |
|||
|
|||
### Implementation Details |
|||
|
|||
- Uses `getUserMedia` API for camera access |
|||
|
|||
- Implements fallback to file input if camera unavailable |
|||
|
|||
- Handles browser compatibility issues |
|||
|
|||
- Requires HTTPS for camera access |
|||
|
|||
### Browser Support |
|||
|
|||
- Chrome: Full support |
|||
|
|||
- Firefox: Full support |
|||
|
|||
- Safari: Limited support |
|||
|
|||
- Edge: Full support |
|||
|
|||
### Fallback Mechanisms |
|||
|
|||
1. Camera access via getUserMedia |
|||
|
|||
2. File input for image upload |
|||
|
|||
3. Drag and drop support |
|||
|
|||
4. Clipboard paste support |
|||
|
|||
## Mobile Platform (Capacitor) |
|||
|
|||
### iOS Implementation |
|||
|
|||
- Uses `@capacitor-mlkit/barcode-scanning` |
|||
|
|||
- Implements proper permission handling |
|||
|
|||
- Supports both front and back cameras |
|||
|
|||
- Handles camera switching |
|||
|
|||
### Android Implementation |
|||
|
|||
- Uses `@capacitor-mlkit/barcode-scanning` |
|||
|
|||
- Implements proper permission handling |
|||
|
|||
- Supports both front and back cameras |
|||
|
|||
- Handles camera switching |
|||
|
|||
### Permission Handling |
|||
|
|||
- Camera permissions requested at runtime |
|||
|
|||
- Permission state tracked and cached |
|||
|
|||
- Graceful handling of denied permissions |
|||
|
|||
- Clear user guidance for enabling permissions |
|||
|
|||
## Desktop Platform (Electron) |
|||
|
|||
### Current Status |
|||
|
|||
- Camera implementation pending |
|||
|
|||
- Will use platform-specific APIs |
|||
|
|||
- Requires proper permission handling |
|||
|
|||
- Will support both built-in and external cameras |
|||
|
|||
### Planned Implementation |
|||
|
|||
- Native camera access via Electron |
|||
|
|||
- Platform-specific camera APIs |
|||
|
|||
- Proper permission handling |
|||
|
|||
- Camera switching support |
|||
|
|||
## Platform Detection |
|||
|
|||
### Implementation |
|||
|
|||
- Uses `PlatformServiceFactory` for platform detection |
|||
|
|||
- Implements platform-specific camera services |
|||
|
|||
- Handles platform-specific error conditions |
|||
|
|||
- Provides platform-specific user guidance |
|||
|
|||
### Service Selection |
|||
|
|||
- Web: `WebPlatformService` |
|||
|
|||
- Mobile: `CapacitorPlatformService` |
|||
|
|||
- Desktop: `ElectronPlatformService` |
|||
|
|||
## Cross-Platform Compatibility |
|||
|
|||
### Common Interface |
|||
|
|||
- Unified camera service interface |
|||
|
|||
- Platform-specific implementations |
|||
|
|||
- Consistent error handling |
|||
|
|||
- Unified user experience |
|||
|
|||
### Feature Parity |
|||
|
|||
- Core camera functionality across platforms |
|||
|
|||
- Platform-specific optimizations |
|||
|
|||
- Consistent user interface |
|||
|
|||
- Unified error messages |
|||
|
|||
## Platform-Specific Features |
|||
|
|||
### Web |
|||
|
|||
- Browser-based camera access |
|||
|
|||
- File upload fallback |
|||
|
|||
- Drag and drop support |
|||
|
|||
- Clipboard paste support |
|||
|
|||
### Mobile |
|||
|
|||
- Native camera access |
|||
|
|||
- Barcode scanning |
|||
|
|||
- Photo capture |
|||
|
|||
- Camera switching |
|||
|
|||
### Desktop |
|||
|
|||
- Native camera access (planned) |
|||
|
|||
- External camera support (planned) |
|||
|
|||
- Advanced camera controls (planned) |
|||
|
|||
## Testing Strategy |
|||
|
|||
### Platform Coverage |
|||
|
|||
- Web: Multiple browsers |
|||
|
|||
- Mobile: iOS and Android devices |
|||
|
|||
- Desktop: Windows, macOS, Linux |
|||
|
|||
### Test Scenarios |
|||
|
|||
- Permission handling |
|||
|
|||
- Camera access |
|||
|
|||
- Error conditions |
|||
|
|||
- Platform compatibility |
|||
|
|||
- Performance metrics |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/features/camera-implementation.mdc` for |
|||
|
|||
core implementation overview |
|||
|
|||
- `.cursor/rules/features/camera_technical.mdc` for |
|||
|
|||
technical implementation details |
|||
|
|||
**Status**: Active platform-specific implementation guide |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: camera-implementation.mdc |
|||
**Stakeholders**: Development team, Platform team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Camera Platform Implementation |
|||
|
|||
- [ ] **Platform Analysis**: Identify target platforms and their camera capabilities |
|||
- [ ] **Feature Planning**: Plan platform-specific camera features |
|||
- [ ] **Integration Planning**: Plan integration with existing camera systems |
|||
- [ ] **Testing Strategy**: Plan testing across all target platforms |
|||
|
|||
### During Camera Platform Implementation |
|||
|
|||
- [ ] **Platform Services**: Implement platform-specific camera functionality |
|||
- [ ] **Feature Development**: Implement planned camera features for each platform |
|||
- [ ] **Integration**: Integrate with existing camera infrastructure |
|||
- [ ] **Performance Optimization**: Optimize camera performance for each platform |
|||
|
|||
### After Camera Platform Implementation |
|||
|
|||
- [ ] **Cross-Platform Testing**: Test camera functionality across all platforms |
|||
- [ ] **Feature Validation**: Verify all planned features work correctly |
|||
- [ ] **Performance Testing**: Ensure camera performance meets requirements |
|||
- [ ] **Documentation Update**: Update platform-specific camera documentation |
@ -0,0 +1,203 @@ |
|||
# Camera Technical Implementation — Details and Best Practices |
|||
|
|||
> **Agent role**: Reference this file for |
|||
detailed technical implementation when working with camera features. |
|||
|
|||
## Platform-Specific Considerations |
|||
|
|||
### iOS |
|||
|
|||
- Requires `NSCameraUsageDescription` in Info.plist |
|||
|
|||
- Supports both front and back cameras |
|||
|
|||
- Implements proper permission handling |
|||
|
|||
### Android |
|||
|
|||
- Requires camera permissions in manifest |
|||
|
|||
- Supports both front and back cameras |
|||
|
|||
- Handles permission requests through Capacitor |
|||
|
|||
### Web |
|||
|
|||
- Requires HTTPS for camera access |
|||
|
|||
- Implements fallback mechanisms |
|||
|
|||
- Handles browser compatibility issues |
|||
|
|||
## Error Handling |
|||
|
|||
### Common Error Scenarios |
|||
|
|||
1. No camera found |
|||
|
|||
2. Permission denied |
|||
|
|||
3. Camera in use by another application |
|||
|
|||
4. HTTPS required |
|||
|
|||
5. Browser compatibility issues |
|||
|
|||
### Error Response |
|||
|
|||
- User-friendly error messages |
|||
|
|||
- Troubleshooting tips |
|||
|
|||
- Clear instructions for resolution |
|||
|
|||
- Platform-specific guidance |
|||
|
|||
## Security Considerations |
|||
|
|||
### Permission Management |
|||
|
|||
- Explicit permission requests |
|||
|
|||
- Permission state tracking |
|||
|
|||
- Graceful handling of denied permissions |
|||
|
|||
### Data Handling |
|||
|
|||
- Secure image processing |
|||
|
|||
- Proper cleanup of camera resources |
|||
|
|||
- No persistent storage of camera data |
|||
|
|||
## Best Practices |
|||
|
|||
### Camera Access |
|||
|
|||
1. Always check for camera availability |
|||
|
|||
2. Request permissions explicitly |
|||
|
|||
3. Handle all error conditions |
|||
|
|||
4. Provide clear user feedback |
|||
|
|||
5. Implement proper cleanup |
|||
|
|||
### Performance |
|||
|
|||
1. Optimize camera resolution |
|||
|
|||
2. Implement proper resource cleanup |
|||
|
|||
3. Handle camera switching efficiently |
|||
|
|||
4. Manage memory usage |
|||
|
|||
### User Experience |
|||
|
|||
1. Clear status indicators |
|||
|
|||
2. Intuitive camera controls |
|||
|
|||
3. Helpful error messages |
|||
|
|||
4. Smooth camera switching |
|||
|
|||
5. Responsive UI feedback |
|||
|
|||
## Future Improvements |
|||
|
|||
### Planned Enhancements |
|||
|
|||
1. Implement Electron camera support |
|||
|
|||
2. Add advanced camera features |
|||
|
|||
3. Improve error handling |
|||
|
|||
4. Enhance user feedback |
|||
|
|||
5. Optimize performance |
|||
|
|||
### Known Issues |
|||
|
|||
1. Electron camera implementation pending |
|||
|
|||
2. Some browser compatibility limitations |
|||
|
|||
3. Platform-specific quirks to address |
|||
|
|||
## Dependencies |
|||
|
|||
### Key Packages |
|||
|
|||
- `@capacitor-mlkit/barcode-scanning` |
|||
|
|||
- `qrcode-stream` |
|||
|
|||
- `vue-picture-cropper` |
|||
|
|||
- Platform-specific camera APIs |
|||
|
|||
## Testing |
|||
|
|||
### Test Scenarios |
|||
|
|||
1. Permission handling |
|||
|
|||
2. Camera switching |
|||
|
|||
3. Error conditions |
|||
|
|||
4. Platform compatibility |
|||
|
|||
5. Performance metrics |
|||
|
|||
### Test Environment |
|||
|
|||
- Multiple browsers |
|||
|
|||
- iOS and Android devices |
|||
|
|||
- Desktop platforms |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/features/camera-implementation.mdc` for |
|||
|
|||
core implementation overview |
|||
|
|||
- `.cursor/rules/features/camera_platforms.mdc` for platform-specific details |
|||
|
|||
**Status**: Active technical implementation guide |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: camera-implementation.mdc |
|||
**Stakeholders**: Development team, Camera feature team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Camera Implementation |
|||
|
|||
- [ ] **Platform Analysis**: Identify target platforms and camera capabilities |
|||
- [ ] **Permission Planning**: Plan permission handling for camera access |
|||
- [ ] **Dependency Review**: Review required camera packages and APIs |
|||
- [ ] **Testing Strategy**: Plan testing across multiple platforms |
|||
|
|||
### During Camera Implementation |
|||
|
|||
- [ ] **Platform Services**: Implement platform-specific camera services |
|||
- [ ] **Permission Handling**: Implement proper camera permission handling |
|||
- [ ] **Error Handling**: Implement graceful error handling for camera failures |
|||
- [ ] **Performance Optimization**: Optimize camera performance and responsiveness |
|||
|
|||
### After Camera Implementation |
|||
|
|||
- [ ] **Cross-Platform Testing**: Test camera functionality across all platforms |
|||
- [ ] **Permission Testing**: Test permission handling and user feedback |
|||
- [ ] **Performance Validation**: Verify camera performance meets requirements |
|||
- [ ] **Documentation Update**: Update camera technical documentation |
@ -1,225 +0,0 @@ |
|||
--- |
|||
globs: *.vue,*.ts,*.tsx |
|||
alwaysApply: false |
|||
--- |
|||
# Agent Contract — TimeSafari Logging (Unified, MANDATORY) |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-15 |
|||
**Status**: 🎯 **ACTIVE** - Mandatory logging standards |
|||
|
|||
## Overview |
|||
|
|||
This document defines unified logging standards for the TimeSafari project, |
|||
ensuring consistent, rest-parameter logging style using the project logger. |
|||
No `console.*` methods are allowed in production code. |
|||
|
|||
## Scope and Goals |
|||
|
|||
**Scope**: Applies to all diffs and generated code in this workspace unless |
|||
explicitly exempted below. |
|||
|
|||
**Goal**: One consistent, rest-parameter logging style using the project |
|||
logger; no `console.*` in production code. |
|||
|
|||
## Non‑Negotiables (DO THIS) |
|||
|
|||
- You **MUST** use the project logger; **DO NOT** use any `console.*` |
|||
methods. |
|||
- Import exactly as: |
|||
- `import { logger } from '@/utils/logger'` |
|||
- If `@` alias is unavailable, compute the correct relative path (do not |
|||
fail). |
|||
- Call signatures use **rest parameters**: `logger.info(message, ...args)` |
|||
- Prefer primitives/IDs and small objects in `...args`; **never build a |
|||
throwaway object** just to "wrap context". |
|||
- Production defaults: Web = `warn+`, Electron = `error`, Dev/Capacitor = |
|||
`info+` (override via `VITE_LOG_LEVEL`). |
|||
- **Database persistence**: `info|warn|error` are persisted; `debug` is not. |
|||
Use `logger.toDb(msg, level?)` for DB-only. |
|||
|
|||
## Available Logger API (Authoritative) |
|||
|
|||
- `logger.debug(message, ...args)` — verbose internals, timings, input/output |
|||
shapes |
|||
- `logger.log(message, ...args)` — synonym of `info` for general info |
|||
- `logger.info(message, ...args)` — lifecycle, state changes, success paths |
|||
- `logger.warn(message, ...args)` — recoverable issues, retries, degraded mode |
|||
- `logger.error(message, ...args)` — failures, thrown exceptions, aborts |
|||
- `logger.toDb(message, level?)` — DB-only entry (default level = `info`) |
|||
- `logger.toConsoleAndDb(message, isError)` — console + DB (use sparingly) |
|||
- `logger.withContext(componentName)` — returns a scoped logger |
|||
|
|||
## Level Guidelines (Use These Heuristics) |
|||
|
|||
### DEBUG |
|||
|
|||
Use for method entry/exit, computed values, filters, loops, retries, and |
|||
external call payload sizes. |
|||
|
|||
```typescript |
|||
logger.debug('[HomeView] reloadFeedOnChange() called'); |
|||
logger.debug('[HomeView] Current filter settings', |
|||
settings.filterFeedByVisible, |
|||
settings.filterFeedByNearby, |
|||
settings.searchBoxes?.length ?? 0); |
|||
logger.debug('[FeedFilters] Toggling nearby filter', |
|||
this.isNearby, this.settingChanged, this.activeDid); |
|||
``` |
|||
|
|||
**Avoid**: Vague messages (`'Processing data'`). |
|||
|
|||
### INFO |
|||
|
|||
Use for user-visible lifecycle and completed operations. |
|||
|
|||
```typescript |
|||
logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM); |
|||
logger.info('[StartView] User selected new seed generation'); |
|||
logger.info('[SearchAreaView] Search box stored', |
|||
searchBox.name, searchBox.bbox); |
|||
logger.info('[ContactQRScanShowView] Contact registration OK', |
|||
contact.did); |
|||
``` |
|||
|
|||
**Avoid**: Diagnostic details that belong in `debug`. |
|||
|
|||
### WARN |
|||
|
|||
Use for recoverable issues, fallbacks, unexpected-but-handled conditions. |
|||
|
|||
```typescript |
|||
logger.warn('[ContactQRScanShowView] Invalid scan result – no value', |
|||
resultType); |
|||
logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL'); |
|||
logger.warn('[ContactQRScanShowView] JWT missing "own" field'); |
|||
``` |
|||
|
|||
**Avoid**: Hard failures (those are `error`). |
|||
|
|||
### ERROR |
|||
|
|||
Use for unrecoverable failures, data integrity issues, and thrown |
|||
exceptions. |
|||
|
|||
```typescript |
|||
logger.error('[HomeView Settings] initializeIdentity() failed', err); |
|||
logger.error('[StartView] Failed to load initialization data', error); |
|||
logger.error('[ContactQRScanShowView] Error processing contact QR', |
|||
error, rawValue); |
|||
``` |
|||
|
|||
**Avoid**: Expected user cancels (use `info`/`debug`). |
|||
|
|||
## Context Hygiene (Consistent, Minimal, Helpful) |
|||
|
|||
- **Component context**: Prefer scoped logger. |
|||
|
|||
```typescript |
|||
const log = logger.withContext('UserService'); |
|||
log.info('User created', userId); |
|||
log.error('Failed to create user', error); |
|||
``` |
|||
|
|||
If not using `withContext`, prefix message with `[ComponentName]`. |
|||
|
|||
- **Emojis**: Optional and minimal for visual scanning. Recommended set: |
|||
- Start/finish: 🚀 / ✅ |
|||
- Retry/loop: 🔄 |
|||
- External call: 📡 |
|||
- Data/metrics: 📊 |
|||
- Inspection: 🔍 |
|||
|
|||
- **Sensitive data**: Never log secrets (tokens, keys, passwords) or |
|||
payloads >10KB. Prefer IDs over objects; redact/hash when needed. |
|||
|
|||
## Migration — Auto‑Rewrites (Apply Every Time) |
|||
|
|||
- Exact transforms: |
|||
- `console.debug(...)` → `logger.debug(...)` |
|||
- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when |
|||
clearly stateful) |
|||
- `console.info(...)` → `logger.info(...)` |
|||
- `console.warn(...)` → `logger.warn(...)` |
|||
- `console.error(...)` → `logger.error(...)` |
|||
|
|||
- Multi-arg handling: |
|||
- First arg becomes `message` (stringify safely if non-string). |
|||
- Remaining args map 1:1 to `...args`: |
|||
`console.info(msg, a, b)` → `logger.info(String(msg), a, b)` |
|||
|
|||
- Sole `Error`: |
|||
- `console.error(err)` → `logger.error(err.message, err)` |
|||
|
|||
- **Object-wrapping cleanup**: Replace `{{ userId, meta }}` wrappers with |
|||
separate args: |
|||
`logger.info('User signed in', userId, meta)` |
|||
|
|||
## DB Logging Rules |
|||
|
|||
- `debug` **never** persists automatically. |
|||
- `info|warn|error` persist automatically. |
|||
- For DB-only events (no console), call `logger.toDb('Message', |
|||
'info'|'warn'|'error')`. |
|||
|
|||
## Exceptions (Tightly Scoped) |
|||
|
|||
Allowed paths (still prefer logger): |
|||
|
|||
- `**/*.test.*`, `**/*.spec.*` |
|||
- `scripts/dev/**`, `scripts/migrate/**` |
|||
|
|||
To intentionally keep `console.*`, add a pragma on the previous line: |
|||
|
|||
```typescript |
|||
// cursor:allow-console reason="short justification" |
|||
console.log('temporary output'); |
|||
``` |
|||
|
|||
Without the pragma, rewrite to `logger.*`. |
|||
|
|||
## CI & Diff Enforcement |
|||
|
|||
- Do not introduce `console.*` anywhere outside allowed, pragma'd spots. |
|||
- If an import is missing, insert it and resolve alias/relative path |
|||
correctly. |
|||
- Enforce rest-parameter call shape in reviews; replace object-wrapped |
|||
context. |
|||
- Ensure environment log level rules remain intact (`VITE_LOG_LEVEL` |
|||
respected). |
|||
|
|||
## Quick Before/After |
|||
|
|||
### **Before** |
|||
|
|||
```typescript |
|||
console.log('User signed in', user.id, meta); |
|||
console.error('Failed to update profile', err); |
|||
console.info('Filter toggled', this.hasVisibleDid); |
|||
``` |
|||
|
|||
### **After** |
|||
|
|||
```typescript |
|||
import { logger } from '@/utils/logger'; |
|||
|
|||
logger.info('User signed in', user.id, meta); |
|||
logger.error('Failed to update profile', err); |
|||
logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid); |
|||
``` |
|||
|
|||
## Checklist (for every PR) |
|||
|
|||
- [ ] No `console.*` (or properly pragma'd in the allowed locations) |
|||
- [ ] Correct import path for `logger` |
|||
- [ ] Rest-parameter call shape (`message, ...args`) |
|||
- [ ] Right level chosen (debug/info/warn/error) |
|||
- [ ] No secrets / oversized payloads / throwaway context objects |
|||
- [ ] Component context provided (scoped logger or `[Component]` prefix) |
|||
|
|||
--- |
|||
|
|||
**Status**: Active and enforced |
|||
**Last Updated**: 2025-08-15 08:11:46Z |
|||
**Version**: 1.0 |
|||
**Maintainer**: Matthew Raymer |
@ -0,0 +1,172 @@ |
|||
# Meta-Rule: Bug Diagnosis |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-21 |
|||
**Status**: 🎯 **ACTIVE** - Bug investigation workflow bundling |
|||
|
|||
## Purpose |
|||
|
|||
This meta-rule bundles all the rules needed for systematic bug investigation |
|||
and root cause analysis. Use this when bugs are reported, performance |
|||
issues occur, or unexpected behavior happens. |
|||
|
|||
## When to Use |
|||
|
|||
- **Bug Reports**: Investigating reported bugs or issues |
|||
- **Performance Issues**: Diagnosing slow performance or bottlenecks |
|||
- **Unexpected Behavior**: Understanding why code behaves unexpectedly |
|||
- **Production Issues**: Investigating issues in live environments |
|||
- **Test Failures**: Understanding why tests are failing |
|||
- **Integration Problems**: Diagnosing issues between components |
|||
|
|||
## Bundled Rules |
|||
|
|||
### **Investigation Process** |
|||
|
|||
- **`development/research_diagnostic.mdc`** - Systematic investigation |
|||
workflow with evidence collection and analysis |
|||
- **`development/investigation_report_example.mdc`** - Investigation |
|||
documentation templates and examples |
|||
- **`core/harbor_pilot_universal.mdc`** - Technical guide creation |
|||
for complex investigations |
|||
|
|||
### **Evidence Collection** |
|||
|
|||
- **`development/logging_standards.mdc`** - Logging implementation |
|||
standards for debugging and evidence collection |
|||
- **`development/time.mdc`** - Timestamp requirements and time |
|||
handling standards for evidence |
|||
- **`development/time_examples.mdc`** - Practical examples of |
|||
proper time handling in investigations |
|||
|
|||
### **Technical Context** |
|||
|
|||
- **`app/timesafari.mdc`** - Core application context and |
|||
architecture for understanding the system |
|||
- **`app/timesafari_platforms.mdc`** - Platform-specific |
|||
considerations and constraints |
|||
|
|||
## Workflow Sequence |
|||
|
|||
### **Phase 1: Initial Investigation (Start Here)** |
|||
|
|||
1. **Research Diagnostic** - Use `research_diagnostic.mdc` for |
|||
systematic investigation approach |
|||
2. **Evidence Collection** - Apply `logging_standards.mdc` and |
|||
`time.mdc` for proper evidence gathering |
|||
3. **Context Understanding** - Review `timesafari.mdc` for |
|||
application context |
|||
|
|||
### **Phase 2: Deep Investigation** |
|||
|
|||
1. **Platform Analysis** - Check `timesafari_platforms.mdc` for |
|||
platform-specific issues |
|||
2. **Technical Guide Creation** - Use `harbor_pilot_universal.mdc` |
|||
for complex investigation documentation |
|||
3. **Evidence Analysis** - Apply `time_examples.mdc` for proper |
|||
timestamp handling |
|||
|
|||
### **Phase 3: Documentation & Reporting** |
|||
|
|||
1. **Investigation Report** - Use `investigation_report_example.mdc` |
|||
for comprehensive documentation |
|||
2. **Root Cause Analysis** - Synthesize findings into actionable |
|||
insights |
|||
|
|||
## Success Criteria |
|||
|
|||
- [ ] **Root cause identified** with supporting evidence |
|||
- [ ] **Evidence properly collected** with timestamps and context |
|||
- [ ] **Investigation documented** using appropriate templates |
|||
- [ ] **Platform factors considered** in diagnosis |
|||
- [ ] **Reproduction steps documented** for verification |
|||
- [ ] **Impact assessment completed** with scope defined |
|||
- [ ] **Next steps identified** for resolution |
|||
|
|||
## Common Pitfalls |
|||
|
|||
- **Don't skip evidence collection** - leads to speculation |
|||
- **Don't ignore platform differences** - misses platform-specific issues |
|||
- **Don't skip documentation** - loses investigation insights |
|||
- **Don't assume root cause** - verify with evidence |
|||
- **Don't ignore time context** - misses temporal factors |
|||
- **Don't skip reproduction steps** - makes verification impossible |
|||
|
|||
## Integration Points |
|||
|
|||
### **With Other Meta-Rules** |
|||
|
|||
- **Feature Planning**: Use complexity assessment for investigation planning |
|||
- **Bug Fixing**: Investigation results feed directly into fix implementation |
|||
- **Feature Implementation**: Investigation insights inform future development |
|||
|
|||
### **With Development Workflow** |
|||
|
|||
- Investigation findings inform testing strategy |
|||
- Root cause analysis drives preventive measures |
|||
- Evidence collection improves logging standards |
|||
|
|||
## Feedback & Improvement |
|||
|
|||
### **Sub-Rule Ratings (1-5 scale)** |
|||
|
|||
- **Research Diagnostic**: ___/5 - Comments: _______________ |
|||
- **Investigation Report**: ___/5 - Comments: _______________ |
|||
- **Technical Guide Creation**: ___/5 - Comments: _______________ |
|||
- **Logging Standards**: ___/5 - Comments: _______________ |
|||
- **Time Standards**: ___/5 - Comments: _______________ |
|||
|
|||
### **Workflow Feedback** |
|||
|
|||
- **Investigation Effectiveness**: How well did the process help find root cause? |
|||
- **Missing Steps**: What investigation steps should be added? |
|||
- **Process Gaps**: Where did the workflow break down? |
|||
|
|||
### **Sub-Rule Improvements** |
|||
|
|||
- **Clarity Issues**: Which rules were unclear or confusing? |
|||
- **Missing Examples**: What examples would make rules more useful? |
|||
- **Template Improvements**: How could investigation templates be better? |
|||
|
|||
### **Overall Experience** |
|||
|
|||
- **Time Saved**: How much time did this meta-rule save you? |
|||
- **Quality Improvement**: Did following these rules improve your investigation? |
|||
- **Recommendation**: Would you recommend this meta-rule to others? |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Bug Investigation |
|||
|
|||
- [ ] **Problem Definition**: Clearly define what needs to be investigated |
|||
- [ ] **Scope Definition**: Determine investigation scope and boundaries |
|||
- [ ] **Evidence Planning**: Plan evidence collection strategy |
|||
- [ ] **Stakeholder Identification**: Identify who needs to be involved |
|||
|
|||
### During Bug Investigation |
|||
|
|||
- [ ] **Rule Application**: Apply bundled rules in recommended sequence |
|||
- [ ] **Evidence Collection**: Collect evidence systematically with timestamps |
|||
- [ ] **Documentation**: Document investigation process and findings |
|||
- [ ] **Validation**: Verify findings with reproduction steps |
|||
|
|||
### After Bug Investigation |
|||
|
|||
- [ ] **Report Creation**: Create comprehensive investigation report |
|||
- [ ] **Root Cause Analysis**: Document root cause with evidence |
|||
- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness |
|||
- [ ] **Process Improvement**: Identify improvements for future investigations |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/meta_feature_planning.mdc` for planning investigation work |
|||
- `.cursor/rules/meta_bug_fixing.mdc` for implementing fixes |
|||
- `.cursor/rules/meta_feature_implementation.mdc` for preventive measures |
|||
|
|||
**Status**: Active meta-rule for bug diagnosis |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: All bundled sub-rules |
|||
**Stakeholders**: Development team, QA team, DevOps team |
@ -0,0 +1,175 @@ |
|||
# Meta-Rule: Bug Fixing |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-21 |
|||
**Status**: 🎯 **ACTIVE** - Bug fix implementation workflow bundling |
|||
|
|||
## Purpose |
|||
|
|||
This meta-rule bundles all the rules needed for implementing bug fixes |
|||
with proper testing and validation. Use this after diagnosis when |
|||
implementing the actual fix. |
|||
|
|||
## When to Use |
|||
|
|||
- **Post-Diagnosis**: After root cause is identified and fix is planned |
|||
- **Fix Implementation**: When coding the actual bug fix |
|||
- **Testing & Validation**: When testing the fix works correctly |
|||
- **Code Review**: When reviewing the fix implementation |
|||
- **Deployment**: When preparing the fix for deployment |
|||
- **Documentation**: When documenting the fix and lessons learned |
|||
|
|||
## Bundled Rules |
|||
|
|||
### **Implementation Standards** |
|||
|
|||
- **`development/software_development.mdc`** - Core development |
|||
principles, evidence requirements, and testing strategy |
|||
- **`development/type_safety_guide.mdc`** - Type-safe implementation |
|||
with proper error handling and type guards |
|||
- **`development/logging_migration.mdc`** - Proper logging |
|||
implementation and migration from console.* calls |
|||
|
|||
### **Code Quality & Review** |
|||
|
|||
- **`development/historical_comment_management.mdc`** - Code quality |
|||
standards and comment transformation rules |
|||
- **`development/historical_comment_patterns.mdc`** - Specific |
|||
patterns for transforming historical comments |
|||
- **`development/complexity_assessment.mdc`** - Complexity evaluation |
|||
for fix implementation |
|||
|
|||
### **Platform & Testing** |
|||
|
|||
- **`app/timesafari_development.mdc`** - TimeSafari-specific |
|||
development workflow and testing requirements |
|||
- **`app/timesafari_platforms.mdc`** - Platform-specific testing |
|||
and validation requirements |
|||
- **`architecture/build_validation.mdc`** - Build system validation |
|||
and testing procedures |
|||
|
|||
## Workflow Sequence |
|||
|
|||
### **Phase 1: Fix Implementation (Start Here)** |
|||
|
|||
1. **Development Standards** - Apply `software_development.mdc` for |
|||
core implementation principles |
|||
2. **Type Safety** - Use `type_safety_guide.mdc` for type-safe |
|||
implementation |
|||
3. **Logging Implementation** - Apply `logging_migration.mdc` for |
|||
proper logging |
|||
|
|||
### **Phase 2: Quality & Review** |
|||
|
|||
1. **Code Quality** - Use `historical_comment_management.mdc` for |
|||
code quality standards |
|||
2. **Complexity Assessment** - Apply `complexity_assessment.mdc` to |
|||
evaluate fix complexity |
|||
3. **Code Review** - Follow review standards from bundled rules |
|||
|
|||
### **Phase 3: Testing & Validation** |
|||
|
|||
1. **Platform Testing** - Use `timesafari_platforms.mdc` for |
|||
platform-specific testing |
|||
2. **Build Validation** - Apply `build_validation.mdc` for build |
|||
system compliance |
|||
3. **Final Validation** - Verify fix works across all platforms |
|||
|
|||
## Success Criteria |
|||
|
|||
- [ ] **Fix implemented** following development standards |
|||
- [ ] **Type safety maintained** with proper error handling |
|||
- [ ] **Logging properly implemented** with component context |
|||
- [ ] **Code quality standards met** with clean, maintainable code |
|||
- [ ] **Testing completed** across all target platforms |
|||
- [ ] **Build validation passed** with no build system issues |
|||
- [ ] **Code review completed** with all feedback addressed |
|||
- [ ] **Documentation updated** with fix details and lessons learned |
|||
|
|||
## Common Pitfalls |
|||
|
|||
- **Don't skip type safety** - leads to runtime errors |
|||
- **Don't ignore logging** - makes future debugging harder |
|||
- **Don't skip platform testing** - misses platform-specific issues |
|||
- **Don't ignore code quality** - creates technical debt |
|||
- **Don't skip build validation** - can break build system |
|||
- **Don't forget documentation** - loses fix context for future |
|||
|
|||
## Integration Points |
|||
|
|||
### **With Other Meta-Rules** |
|||
|
|||
- **Bug Diagnosis**: Investigation results drive fix implementation |
|||
- **Feature Implementation**: Fix patterns inform future development |
|||
- **Feature Planning**: Fix complexity informs future planning |
|||
|
|||
### **With Development Workflow** |
|||
|
|||
- Fix implementation follows development standards |
|||
- Testing strategy ensures fix quality |
|||
- Code review maintains code quality |
|||
|
|||
## Feedback & Improvement |
|||
|
|||
### **Sub-Rule Ratings (1-5 scale)** |
|||
|
|||
- **Development Standards**: ___/5 - Comments: _______________ |
|||
- **Type Safety**: ___/5 - Comments: _______________ |
|||
- **Logging Migration**: ___/5 - Comments: _______________ |
|||
- **Code Quality**: ___/5 - Comments: _______________ |
|||
- **Platform Testing**: ___/5 - Comments: _______________ |
|||
|
|||
### **Workflow Feedback** |
|||
|
|||
- **Implementation Clarity**: How clear was the implementation guidance? |
|||
- **Testing Coverage**: Were testing requirements sufficient or excessive? |
|||
- **Process Effectiveness**: How well did the workflow work for you? |
|||
|
|||
### **Sub-Rule Improvements** |
|||
|
|||
- **Clarity Issues**: Which rules were unclear or confusing? |
|||
- **Missing Examples**: What examples would make rules more useful? |
|||
- **Integration Problems**: Do any rules conflict or overlap? |
|||
|
|||
### **Overall Experience** |
|||
|
|||
- **Time Saved**: How much time did this meta-rule save you? |
|||
- **Quality Improvement**: Did following these rules improve your fix? |
|||
- **Recommendation**: Would you recommend this meta-rule to others? |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Bug Fixing |
|||
|
|||
- [ ] **Root Cause Understood**: Confirm root cause is clearly identified |
|||
- [ ] **Fix Strategy Planned**: Plan implementation approach and testing |
|||
- [ ] **Platform Impact Assessed**: Understand impact across all platforms |
|||
- [ ] **Testing Strategy Planned**: Plan testing approach for the fix |
|||
|
|||
### During Bug Fixing |
|||
|
|||
- [ ] **Rule Application**: Apply bundled rules in recommended sequence |
|||
- [ ] **Implementation**: Implement fix following development standards |
|||
- [ ] **Testing**: Test fix across all target platforms |
|||
- [ ] **Documentation**: Document implementation details and decisions |
|||
|
|||
### After Bug Fixing |
|||
|
|||
- [ ] **Validation**: Verify fix meets all success criteria |
|||
- [ ] **Code Review**: Complete code review with team |
|||
- [ ] **Deployment**: Deploy fix following deployment procedures |
|||
- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation workflow |
|||
- `.cursor/rules/meta_feature_implementation.mdc` for implementation patterns |
|||
- `.cursor/rules/meta_feature_planning.mdc` for planning future work |
|||
|
|||
**Status**: Active meta-rule for bug fixing |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: All bundled sub-rules |
|||
**Stakeholders**: Development team, QA team, DevOps team |
@ -0,0 +1,196 @@ |
|||
--- |
|||
alwaysApply: true |
|||
--- |
|||
|
|||
# Meta-Rule: Core Always-On Rules |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-21 |
|||
**Status**: 🎯 **ACTIVE** - Core rules for every prompt |
|||
|
|||
## Purpose |
|||
|
|||
This meta-rule bundles the core rules that should be applied to **every single |
|||
prompt** because they define fundamental behaviors, principles, and context |
|||
that are essential for all AI interactions. |
|||
|
|||
## When to Use |
|||
|
|||
**ALWAYS** - These rules apply to every single prompt, regardless of the task |
|||
or context. They form the foundation for all AI assistant behavior. |
|||
|
|||
## Bundled Rules |
|||
|
|||
### **Core Human Competence Principles** |
|||
|
|||
- **`core/base_context.mdc`** - Human competence first principles, interaction |
|||
guidelines, and output contract requirements |
|||
- **`core/less_complex.mdc`** - Minimalist solution principle and complexity |
|||
guidelines |
|||
|
|||
### **Time & Context Standards** |
|||
|
|||
- **`development/time.mdc`** - Time handling principles and UTC standards |
|||
- **`development/time_examples.mdc`** - Practical time implementation examples |
|||
- **`development/time_implementation.mdc`** - Detailed time implementation |
|||
guidelines |
|||
|
|||
### **Version Control & Process** |
|||
|
|||
- **`workflow/version_control.mdc`** - Version control principles and commit |
|||
guidelines |
|||
- **`workflow/commit_messages.mdc`** - Commit message format and conventions |
|||
|
|||
### **Application Context** |
|||
|
|||
- **`app/timesafari.mdc`** - Core TimeSafari application context and |
|||
development principles |
|||
- **`app/timesafari_development.mdc`** - TimeSafari-specific development |
|||
workflow and quality standards |
|||
|
|||
## Why These Rules Are Always-On |
|||
|
|||
### **Base Context** |
|||
|
|||
- **Human Competence First**: Every interaction must increase human competence |
|||
- **Output Contract**: All responses must follow the required structure |
|||
- **Competence Hooks**: Learning and collaboration must be built into every response |
|||
|
|||
### **Time Standards** |
|||
|
|||
- **UTC Consistency**: All timestamps must use UTC for system operations |
|||
- **Evidence Collection**: Time context is essential for debugging and investigation |
|||
- **Cross-Platform**: Time handling affects all platforms and features |
|||
|
|||
### **Version Control** |
|||
|
|||
- **Commit Standards**: Every code change must follow commit message conventions |
|||
- **Process Consistency**: Version control affects all development work |
|||
- **Team Collaboration**: Commit standards enable effective team communication |
|||
|
|||
### **Application Context** |
|||
|
|||
- **Platform Awareness**: Every task must consider web/mobile/desktop platforms |
|||
- **Architecture Principles**: All work must follow TimeSafari patterns |
|||
- **Development Standards**: Quality and testing requirements apply to all work |
|||
|
|||
## Application Priority |
|||
|
|||
### **Primary (Apply First)** |
|||
|
|||
1. **Base Context** - Human competence and output contract |
|||
2. **Time Standards** - UTC and timestamp requirements |
|||
3. **Application Context** - TimeSafari principles and platforms |
|||
|
|||
### **Secondary (Apply as Needed)** |
|||
|
|||
1. **Version Control** - When making code changes |
|||
2. **Complexity Guidelines** - When evaluating solution approaches |
|||
|
|||
## Integration with Other Meta-Rules |
|||
|
|||
### **Feature Planning** |
|||
|
|||
- Base context ensures human competence focus |
|||
- Time standards inform planning and estimation |
|||
- Application context drives platform considerations |
|||
|
|||
### **Bug Diagnosis** |
|||
|
|||
- Base context ensures systematic investigation |
|||
- Time standards enable proper evidence collection |
|||
- Application context provides system understanding |
|||
|
|||
### **Bug Fixing** |
|||
|
|||
- Base context ensures quality implementation |
|||
- Time standards maintain logging consistency |
|||
- Application context guides testing strategy |
|||
|
|||
### **Feature Implementation** |
|||
|
|||
- Base context ensures proper development approach |
|||
- Time standards maintain system consistency |
|||
- Application context drives architecture decisions |
|||
|
|||
## Success Criteria |
|||
|
|||
- [ ] **Base context applied** to every single prompt |
|||
- [ ] **Time standards followed** for all timestamps and logging |
|||
- [ ] **Version control standards** applied to all code changes |
|||
- [ ] **Application context considered** for all platform work |
|||
- [ ] **Human competence focus** maintained in all interactions |
|||
- [ ] **Output contract structure** followed in all responses |
|||
|
|||
## Common Pitfalls |
|||
|
|||
- **Don't skip base context** - loses human competence focus |
|||
- **Don't ignore time standards** - creates inconsistent timestamps |
|||
- **Don't forget application context** - misses platform considerations |
|||
- **Don't skip version control** - creates inconsistent commit history |
|||
- **Don't lose competence focus** - reduces learning value |
|||
|
|||
## Feedback & Improvement |
|||
|
|||
### **Rule Effectiveness Ratings (1-5 scale)** |
|||
|
|||
- **Base Context**: ___/5 - Comments: _______________ |
|||
- **Time Standards**: ___/5 - Comments: _______________ |
|||
- **Version Control**: ___/5 - Comments: _______________ |
|||
- **Application Context**: ___/5 - Comments: _______________ |
|||
|
|||
### **Always-On Effectiveness** |
|||
|
|||
- **Consistency**: Are these rules applied consistently across all prompts? |
|||
- **Value**: Do these rules add value to every interaction? |
|||
- **Overhead**: Are these rules too burdensome for simple tasks? |
|||
|
|||
### **Integration Feedback** |
|||
|
|||
- **With Other Meta-Rules**: How well do these integrate with workflow rules? |
|||
- **Context Switching**: Do these rules help or hinder context switching? |
|||
- **Learning Curve**: Are these rules easy for new users to understand? |
|||
|
|||
### **Overall Experience** |
|||
|
|||
- **Quality Improvement**: Do these rules improve response quality? |
|||
- **Efficiency**: Do these rules make interactions more efficient? |
|||
- **Recommendation**: Would you recommend keeping these always-on? |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Every Prompt |
|||
|
|||
- [ ] **Base Context**: Ensure human competence principles are active |
|||
- [ ] **Time Standards**: Verify UTC and timestamp requirements are clear |
|||
- [ ] **Application Context**: Confirm TimeSafari context is loaded |
|||
- [ ] **Version Control**: Prepare commit standards if code changes are needed |
|||
|
|||
### During Response Creation |
|||
|
|||
- [ ] **Output Contract**: Follow required response structure |
|||
- [ ] **Competence Hooks**: Include learning and collaboration elements |
|||
- [ ] **Time Consistency**: Apply UTC standards for all time references |
|||
- [ ] **Platform Awareness**: Consider all target platforms |
|||
|
|||
### After Response Creation |
|||
|
|||
- [ ] **Validation**: Verify all always-on rules were applied |
|||
- [ ] **Quality Check**: Ensure response meets competence standards |
|||
- [ ] **Context Review**: Confirm application context was properly considered |
|||
- [ ] **Feedback Collection**: Note any issues with always-on application |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/meta_feature_planning.mdc` for workflow-specific rules |
|||
- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation workflows |
|||
- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation |
|||
- `.cursor/rules/meta_feature_implementation.mdc` for feature development |
|||
|
|||
**Status**: Active core always-on meta-rule |
|||
**Priority**: Critical (applies to every prompt) |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: All bundled sub-rules |
|||
**Stakeholders**: All AI interactions, Development team |
@ -0,0 +1,237 @@ |
|||
# Meta-Rule: Documentation Writing & Education |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-21 |
|||
**Status**: 🎯 **ACTIVE** - Documentation writing and education workflow |
|||
|
|||
## Purpose |
|||
|
|||
This meta-rule bundles documentation-related rules to create comprehensive, |
|||
educational documentation that increases human competence rather than just |
|||
providing technical descriptions. |
|||
|
|||
## When to Use |
|||
|
|||
**Use this meta-rule when**: |
|||
- Writing new documentation |
|||
- Updating existing documentation |
|||
- Creating technical guides |
|||
- Writing migration documentation |
|||
- Creating architectural documentation |
|||
- Writing user guides or tutorials |
|||
|
|||
## Bundled Rules |
|||
|
|||
### **Core Documentation Standards** |
|||
|
|||
- **`docs/markdown_core.mdc`** - Core markdown formatting and automation |
|||
- **`docs/markdown_templates.mdc`** - Document templates and structure |
|||
- **`docs/markdown_workflow.mdc`** - Documentation validation workflows |
|||
|
|||
### **Documentation Principles** |
|||
|
|||
- **`core/base_context.mdc`** - Human competence first principles |
|||
- **`core/less_complex.mdc`** - Minimalist solution guidelines |
|||
- **`development/software_development.mdc`** - Development documentation standards |
|||
|
|||
### **Context-Specific Rules** |
|||
|
|||
- **`app/timesafari.mdc`** - TimeSafari application context |
|||
- **`app/timesafari_development.mdc`** - Development documentation patterns |
|||
- **`architecture/architectural_patterns.mdc`** - Architecture documentation |
|||
|
|||
## Core Documentation Philosophy |
|||
|
|||
### **Education Over Technical Description** |
|||
|
|||
**Primary Goal**: Increase human competence and understanding |
|||
**Secondary Goal**: Provide accurate technical information |
|||
**Approach**: Explain the "why" before the "how" |
|||
|
|||
### **Human Competence Principles** |
|||
|
|||
1. **Context First**: Explain the problem before the solution |
|||
2. **Learning Path**: Structure content for progressive understanding |
|||
3. **Real Examples**: Use concrete, relatable examples |
|||
4. **Common Pitfalls**: Warn about typical mistakes and misconceptions |
|||
5. **Decision Context**: Explain why certain choices were made |
|||
|
|||
### **Documentation Hierarchy** |
|||
|
|||
1. **Conceptual Understanding** - What is this and why does it matter? |
|||
2. **Context and Motivation** - When and why would you use this? |
|||
3. **Technical Implementation** - How do you implement it? |
|||
4. **Examples and Patterns** - What does it look like in practice? |
|||
5. **Troubleshooting** - What can go wrong and how to fix it? |
|||
|
|||
## Implementation Guidelines |
|||
|
|||
### **Document Structure** |
|||
|
|||
**Mandatory Sections**: |
|||
- **Overview**: Clear purpose and scope with educational context |
|||
- **Why This Matters**: Business value and user benefit explanation |
|||
- **Core Concepts**: Fundamental understanding before implementation |
|||
- **Implementation**: Step-by-step technical guidance |
|||
- **Examples**: Real-world usage patterns |
|||
- **Common Issues**: Troubleshooting and prevention |
|||
- **Next Steps**: Where to go from here |
|||
|
|||
**Optional Sections**: |
|||
- **Background**: Historical context and evolution |
|||
- **Alternatives**: Other approaches and trade-offs |
|||
- **Advanced Topics**: Deep dive into complex scenarios |
|||
- **References**: Additional learning resources |
|||
|
|||
### **Writing Style** |
|||
|
|||
**Educational Approach**: |
|||
- **Conversational tone**: Write as if explaining to a colleague |
|||
- **Progressive disclosure**: Start simple, add complexity gradually |
|||
- **Active voice**: "You can do this" not "This can be done" |
|||
- **Question format**: "What happens when..." to engage thinking |
|||
- **Analogies**: Use familiar concepts to explain complex ideas |
|||
|
|||
**Technical Accuracy**: |
|||
- **Precise language**: Use exact technical terms consistently |
|||
- **Code examples**: Working, tested code snippets |
|||
- **Version information**: Specify applicable versions and platforms |
|||
- **Limitations**: Clearly state what the solution doesn't do |
|||
|
|||
### **Content Quality Standards** |
|||
|
|||
**Educational Value**: |
|||
- [ ] **Concept clarity**: Reader understands the fundamental idea |
|||
- [ ] **Context relevance**: Reader knows when to apply the knowledge |
|||
- [ ] **Practical application**: Reader can implement the solution |
|||
- [ ] **Problem prevention**: Reader avoids common mistakes |
|||
- [ ] **Next steps**: Reader knows where to continue learning |
|||
|
|||
**Technical Accuracy**: |
|||
- [ ] **Fact verification**: All technical details are correct |
|||
- [ ] **Code validation**: Examples compile and run correctly |
|||
- [ ] **Version compatibility**: Platform and version requirements clear |
|||
- [ ] **Security consideration**: Security implications addressed |
|||
- [ ] **Performance notes**: Performance characteristics documented |
|||
|
|||
## Document Types and Templates |
|||
|
|||
### **Technical Guides** |
|||
|
|||
**Focus**: Implementation and technical details |
|||
**Structure**: Problem → Solution → Implementation → Examples |
|||
**Education**: Explain the "why" behind technical choices |
|||
|
|||
### **Migration Documentation** |
|||
|
|||
**Focus**: Process and workflow guidance |
|||
**Structure**: Context → Preparation → Steps → Validation → Troubleshooting |
|||
**Education**: Help users understand migration benefits and risks |
|||
|
|||
### **Architecture Documentation** |
|||
|
|||
**Focus**: System design and decision rationale |
|||
**Structure**: Problem → Constraints → Alternatives → Decision → Implementation |
|||
**Education**: Explain design trade-offs and decision factors |
|||
|
|||
### **User Guides** |
|||
|
|||
**Focus**: Task completion and user empowerment |
|||
**Structure**: Goal → Prerequisites → Steps → Verification → Next Steps |
|||
**Education**: Help users understand the system's capabilities |
|||
|
|||
## Quality Assurance |
|||
|
|||
### **Review Checklist** |
|||
|
|||
**Educational Quality**: |
|||
- [ ] **Clear learning objective**: What will the reader learn? |
|||
- [ ] **Appropriate complexity**: Matches target audience knowledge |
|||
- [ ] **Progressive disclosure**: Information builds logically |
|||
- [ ] **Practical examples**: Real-world scenarios and use cases |
|||
- [ ] **Common questions**: Anticipates and answers reader questions |
|||
|
|||
**Technical Quality**: |
|||
- [ ] **Accuracy**: All technical details verified |
|||
- [ ] **Completeness**: Covers all necessary information |
|||
- [ ] **Consistency**: Terminology and formatting consistent |
|||
- [ ] **Currency**: Information is up-to-date |
|||
- [ ] **Accessibility**: Clear for target audience |
|||
|
|||
### **Validation Workflows** |
|||
|
|||
1. **Content Review**: Subject matter expert review |
|||
2. **Educational Review**: Learning effectiveness assessment |
|||
3. **Technical Review**: Accuracy and completeness validation |
|||
4. **User Testing**: Real user comprehension testing |
|||
5. **Continuous Improvement**: Regular updates based on feedback |
|||
|
|||
## Success Metrics |
|||
|
|||
### **Educational Effectiveness** |
|||
|
|||
- **Comprehension**: Users understand the concepts |
|||
- **Application**: Users can implement the solutions |
|||
- **Confidence**: Users feel capable and empowered |
|||
- **Efficiency**: Users complete tasks faster |
|||
- **Satisfaction**: Users find documentation helpful |
|||
|
|||
### **Technical Quality** |
|||
|
|||
- **Accuracy**: Zero technical errors |
|||
- **Completeness**: All necessary information included |
|||
- **Consistency**: Uniform style and format |
|||
- **Maintainability**: Easy to update and extend |
|||
- **Accessibility**: Clear for target audience |
|||
|
|||
## Common Pitfalls |
|||
|
|||
### **Educational Mistakes** |
|||
|
|||
- **Assumption overload**: Assuming too much prior knowledge |
|||
- **Information dump**: Overwhelming with details |
|||
- **Context missing**: Not explaining why something matters |
|||
- **Example poverty**: Insufficient practical examples |
|||
- **Feedback missing**: No way to verify understanding |
|||
|
|||
### **Technical Mistakes** |
|||
|
|||
- **Outdated information**: Not keeping content current |
|||
- **Incomplete coverage**: Missing important details |
|||
- **Inconsistent terminology**: Using different terms for same concepts |
|||
- **Poor examples**: Non-working or confusing code |
|||
- **Missing validation**: No way to verify correctness |
|||
|
|||
## Feedback and Improvement |
|||
|
|||
### **Continuous Learning** |
|||
|
|||
- **User feedback**: Collect and analyze user comments |
|||
- **Usage metrics**: Track document usage and effectiveness |
|||
- **Review cycles**: Regular content review and updates |
|||
- **Community input**: Engage users in documentation improvement |
|||
- **Best practices**: Stay current with documentation standards |
|||
|
|||
### **Quality Metrics** |
|||
|
|||
- **Readability scores**: Measure content clarity |
|||
- **User satisfaction**: Survey-based quality assessment |
|||
- **Task completion**: Success rate of documented procedures |
|||
- **Support reduction**: Decrease in help requests |
|||
- **Knowledge retention**: Long-term user understanding |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards |
|||
- `.cursor/rules/docs/markdown_templates.mdc` for document templates |
|||
- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows |
|||
- `.cursor/rules/docs/meta_rule_usage_guide.md` for how to use meta-rules |
|||
- `.cursor/rules/core/base_context.mdc` for human competence principles |
|||
|
|||
**Status**: Active documentation meta-rule |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: All bundled sub-rules |
|||
**Stakeholders**: Documentation team, Development team, Users |
@ -0,0 +1,187 @@ |
|||
# Meta-Rule: Feature Implementation |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-21 |
|||
**Status**: 🎯 **ACTIVE** - Feature implementation workflow bundling |
|||
|
|||
## Purpose |
|||
|
|||
This meta-rule bundles all the rules needed for building features with |
|||
proper architecture and cross-platform support. Use this when implementing |
|||
planned features or refactoring existing code. |
|||
|
|||
## When to Use |
|||
|
|||
- **Feature Development**: Building new features from planning |
|||
- **Code Refactoring**: Restructuring existing code for better architecture |
|||
- **Platform Expansion**: Adding features to new platforms |
|||
- **Service Implementation**: Building new services or components |
|||
- **Integration Work**: Connecting features with existing systems |
|||
- **Performance Optimization**: Improving feature performance |
|||
|
|||
## Bundled Rules |
|||
|
|||
### **Development Foundation** |
|||
|
|||
- **`app/timesafari_development.mdc`** - TimeSafari-specific |
|||
development workflow and quality standards |
|||
- **`development/software_development.mdc`** - Core development |
|||
principles and evidence requirements |
|||
- **`development/type_safety_guide.mdc`** - Type-safe implementation |
|||
with proper error handling |
|||
|
|||
### **Architecture & Patterns** |
|||
|
|||
- **`app/architectural_patterns.mdc`** - Design patterns and |
|||
architectural examples for features |
|||
- **`app/architectural_examples.mdc`** - Implementation examples |
|||
and testing strategies |
|||
- **`app/architectural_implementation.mdc`** - Implementation |
|||
guidelines and best practices |
|||
|
|||
### **Platform & Services** |
|||
|
|||
- **`app/timesafari_platforms.mdc`** - Platform abstraction |
|||
patterns and platform-specific requirements |
|||
- **`development/asset_configuration.mdc`** - Asset management |
|||
and build integration |
|||
- **`development/logging_standards.mdc`** - Proper logging |
|||
implementation standards |
|||
|
|||
### **Quality & Validation** |
|||
|
|||
- **`architecture/build_validation.mdc`** - Build system |
|||
validation and testing procedures |
|||
- **`architecture/build_testing.mdc`** - Testing requirements |
|||
and feedback collection |
|||
- **`development/complexity_assessment.mdc`** - Complexity |
|||
evaluation for implementation |
|||
|
|||
## Workflow Sequence |
|||
|
|||
### **Phase 1: Implementation Foundation (Start Here)** |
|||
|
|||
1. **Development Workflow** - Use `timesafari_development.mdc` for |
|||
development standards and workflow |
|||
2. **Type Safety** - Apply `type_safety_guide.mdc` for type-safe |
|||
implementation |
|||
3. **Architecture Patterns** - Use `architectural_patterns.mdc` for |
|||
design patterns |
|||
|
|||
### **Phase 2: Feature Development** |
|||
|
|||
1. **Platform Services** - Apply `timesafari_platforms.mdc` for |
|||
platform abstraction |
|||
2. **Implementation Examples** - Use `architectural_examples.mdc` |
|||
for implementation guidance |
|||
3. **Asset Configuration** - Apply `asset_configuration.mdc` for |
|||
asset management |
|||
|
|||
### **Phase 3: Quality & Testing** |
|||
|
|||
1. **Logging Implementation** - Use `logging_standards.mdc` for |
|||
proper logging |
|||
2. **Build Validation** - Apply `build_validation.mdc` for build |
|||
system compliance |
|||
3. **Testing & Feedback** - Use `build_testing.mdc` for testing |
|||
requirements |
|||
|
|||
## Success Criteria |
|||
|
|||
- [ ] **Feature implemented** following development standards |
|||
- [ ] **Type safety maintained** with proper error handling |
|||
- [ ] **Architecture patterns applied** consistently |
|||
- [ ] **Platform abstraction implemented** correctly |
|||
- [ ] **Logging properly implemented** with component context |
|||
- [ ] **Assets configured** and integrated with build system |
|||
- [ ] **Build validation passed** with no build system issues |
|||
- [ ] **Testing completed** across all target platforms |
|||
- [ ] **Code review completed** with all feedback addressed |
|||
|
|||
## Common Pitfalls |
|||
|
|||
- **Don't skip architecture patterns** - leads to inconsistent design |
|||
- **Don't ignore platform abstraction** - creates platform-specific code |
|||
- **Don't skip type safety** - leads to runtime errors |
|||
- **Don't ignore logging** - makes future debugging harder |
|||
- **Don't skip build validation** - can break build system |
|||
- **Don't forget asset configuration** - leads to missing assets |
|||
|
|||
## Integration Points |
|||
|
|||
### **With Other Meta-Rules** |
|||
|
|||
- **Feature Planning**: Planning outputs drive implementation approach |
|||
- **Bug Fixing**: Implementation patterns inform fix strategies |
|||
- **Bug Diagnosis**: Implementation insights help with investigation |
|||
|
|||
### **With Development Workflow** |
|||
|
|||
- Implementation follows development standards |
|||
- Architecture decisions drive implementation approach |
|||
- Platform requirements inform testing strategy |
|||
|
|||
## Feedback & Improvement |
|||
|
|||
### **Sub-Rule Ratings (1-5 scale)** |
|||
|
|||
- **Development Workflow**: ___/5 - Comments: _______________ |
|||
- **Type Safety**: ___/5 - Comments: _______________ |
|||
- **Architecture Patterns**: ___/5 - Comments: _______________ |
|||
- **Platform Services**: ___/5 - Comments: _______________ |
|||
- **Build Validation**: ___/5 - Comments: _______________ |
|||
|
|||
### **Workflow Feedback** |
|||
|
|||
- **Implementation Clarity**: How clear was the implementation guidance? |
|||
- **Pattern Effectiveness**: How well did architecture patterns work? |
|||
- **Platform Coverage**: How well did platform guidance cover your needs? |
|||
|
|||
### **Sub-Rule Improvements** |
|||
|
|||
- **Clarity Issues**: Which rules were unclear or confusing? |
|||
- **Missing Examples**: What examples would make rules more useful? |
|||
- **Integration Problems**: Do any rules conflict or overlap? |
|||
|
|||
### **Overall Experience** |
|||
|
|||
- **Time Saved**: How much time did this meta-rule save you? |
|||
- **Quality Improvement**: Did following these rules improve your implementation? |
|||
- **Recommendation**: Would you recommend this meta-rule to others? |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Feature Implementation |
|||
|
|||
- [ ] **Planning Review**: Review feature planning and requirements |
|||
- [ ] **Architecture Planning**: Plan architecture and design patterns |
|||
- [ ] **Platform Analysis**: Understand platform-specific requirements |
|||
- [ ] **Testing Strategy**: Plan testing approach for the feature |
|||
|
|||
### During Feature Implementation |
|||
|
|||
- [ ] **Rule Application**: Apply bundled rules in recommended sequence |
|||
- [ ] **Implementation**: Implement feature following development standards |
|||
- [ ] **Testing**: Test feature across all target platforms |
|||
- [ ] **Documentation**: Document implementation details and decisions |
|||
|
|||
### After Feature Implementation |
|||
|
|||
- [ ] **Validation**: Verify feature meets all success criteria |
|||
- [ ] **Code Review**: Complete code review with team |
|||
- [ ] **Testing**: Complete comprehensive testing across platforms |
|||
- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/meta_feature_planning.mdc` for planning workflow |
|||
- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation patterns |
|||
- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation insights |
|||
|
|||
**Status**: Active meta-rule for feature implementation |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: All bundled sub-rules |
|||
**Stakeholders**: Development team, Architecture team, QA team |
@ -0,0 +1,165 @@ |
|||
# Meta-Rule: Feature Planning |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-21 |
|||
**Status**: 🎯 **ACTIVE** - Feature planning workflow bundling |
|||
|
|||
## Purpose |
|||
|
|||
This meta-rule bundles all the rules needed for comprehensive feature planning |
|||
across all platforms. Use this when starting any new feature development, |
|||
planning sprints, or estimating work effort. |
|||
|
|||
## When to Use |
|||
|
|||
- **New Feature Development**: Planning features from concept to implementation |
|||
- **Sprint Planning**: Estimating effort and breaking down work |
|||
- **Architecture Decisions**: Planning major architectural changes |
|||
- **Platform Expansion**: Adding features to new platforms |
|||
- **Refactoring Planning**: Planning significant code restructuring |
|||
|
|||
## Bundled Rules |
|||
|
|||
### **Core Planning Foundation** |
|||
|
|||
- **`development/planning_examples.mdc`** - Planning templates, examples, and |
|||
best practices for structured planning |
|||
- **`development/realistic_time_estimation.mdc`** - Time estimation framework |
|||
with complexity-based phases and milestones |
|||
- **`development/complexity_assessment.mdc`** - Technical and business |
|||
complexity evaluation with risk assessment |
|||
|
|||
### **Platform & Architecture** |
|||
|
|||
- **`app/timesafari_platforms.mdc`** - Platform-specific requirements, |
|||
constraints, and capabilities across web/mobile/desktop |
|||
- **`app/architectural_decision_record.mdc`** - ADR process for documenting |
|||
major architectural decisions and trade-offs |
|||
|
|||
### **Development Context** |
|||
|
|||
- **`app/timesafari.mdc`** - Core application context, principles, and |
|||
development focus areas |
|||
- **`app/timesafari_development.mdc`** - TimeSafari-specific development |
|||
workflow and quality standards |
|||
|
|||
## Workflow Sequence |
|||
|
|||
### **Phase 1: Foundation (Start Here)** |
|||
|
|||
1. **Complexity Assessment** - Use `complexity_assessment.mdc` to evaluate |
|||
technical and business complexity |
|||
2. **Time Estimation** - Apply `realistic_time_estimation.mdc` framework |
|||
based on complexity results |
|||
3. **Core Planning** - Use `planning_examples.mdc` for structured planning |
|||
approach |
|||
|
|||
### **Phase 2: Platform & Architecture** |
|||
|
|||
1. **Platform Analysis** - Review `timesafari_platforms.mdc` for |
|||
platform-specific requirements |
|||
2. **Architecture Planning** - Use `architectural_decision_record.mdc` if |
|||
major architectural changes are needed |
|||
|
|||
### **Phase 3: Implementation Planning** |
|||
|
|||
1. **Development Workflow** - Reference `timesafari_development.mdc` for |
|||
development standards and testing strategy |
|||
2. **Final Planning** - Consolidate all inputs into comprehensive plan |
|||
|
|||
## Success Criteria |
|||
|
|||
- [ ] **Complexity assessed** and documented with risk factors |
|||
- [ ] **Time estimate created** with clear phases and milestones |
|||
- [ ] **Platform requirements identified** for all target platforms |
|||
- [ ] **Architecture decisions documented** (if major changes needed) |
|||
- [ ] **Testing strategy planned** with platform-specific considerations |
|||
- [ ] **Dependencies mapped** between tasks and phases |
|||
- [ ] **Stakeholder input gathered** and incorporated |
|||
|
|||
## Common Pitfalls |
|||
|
|||
- **Don't skip complexity assessment** - leads to unrealistic estimates |
|||
- **Don't estimate without platform analysis** - misses platform-specific work |
|||
- **Don't plan without stakeholder input** - creates misaligned expectations |
|||
- **Don't ignore testing strategy** - leads to incomplete planning |
|||
- **Don't skip architecture decisions** - creates technical debt |
|||
|
|||
## Integration Points |
|||
|
|||
### **With Other Meta-Rules** |
|||
|
|||
- **Bug Diagnosis**: Use complexity assessment for bug investigation planning |
|||
- **Feature Implementation**: This planning feeds directly into implementation |
|||
- **Code Review**: Planning standards inform review requirements |
|||
|
|||
### **With Development Workflow** |
|||
|
|||
- Planning outputs become inputs for sprint planning |
|||
- Complexity assessment informs testing strategy |
|||
- Platform requirements drive architecture decisions |
|||
|
|||
## Feedback & Improvement |
|||
|
|||
### **Sub-Rule Ratings (1-5 scale)** |
|||
|
|||
- **Complexity Assessment**: ___/5 - Comments: _______________ |
|||
- **Time Estimation**: ___/5 - Comments: _______________ |
|||
- **Planning Examples**: ___/5 - Comments: _______________ |
|||
- **Platform Analysis**: ___/5 - Comments: _______________ |
|||
- **Architecture Decisions**: ___/5 - Comments: _______________ |
|||
|
|||
### **Workflow Feedback** |
|||
|
|||
- **Sequence Effectiveness**: Did the recommended order work for you? |
|||
- **Missing Guidance**: What additional information would have helped? |
|||
- **Process Gaps**: Where did the workflow break down? |
|||
|
|||
### **Sub-Rule Improvements** |
|||
|
|||
- **Clarity Issues**: Which rules were unclear or confusing? |
|||
- **Missing Examples**: What examples would make rules more useful? |
|||
- **Integration Problems**: Do any rules conflict or overlap? |
|||
|
|||
### **Overall Experience** |
|||
|
|||
- **Time Saved**: How much time did this meta-rule save you? |
|||
- **Quality Improvement**: Did following these rules improve your planning? |
|||
- **Recommendation**: Would you recommend this meta-rule to others? |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Feature Planning |
|||
|
|||
- [ ] **Scope Definition**: Clearly define the feature scope and boundaries |
|||
- [ ] **Stakeholder Identification**: Identify all stakeholders and decision makers |
|||
- [ ] **Platform Requirements**: Understand target platforms and constraints |
|||
- [ ] **Complexity Assessment**: Plan complexity evaluation approach |
|||
|
|||
### During Feature Planning |
|||
|
|||
- [ ] **Rule Application**: Apply bundled rules in recommended sequence |
|||
- [ ] **Documentation**: Document all planning decisions and rationale |
|||
- [ ] **Stakeholder Input**: Gather and incorporate stakeholder feedback |
|||
- [ ] **Validation**: Validate planning against success criteria |
|||
|
|||
### After Feature Planning |
|||
|
|||
- [ ] **Plan Review**: Review plan with stakeholders and team |
|||
- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness |
|||
- [ ] **Documentation Update**: Update relevant documentation |
|||
- [ ] **Process Improvement**: Identify improvements for future planning |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation planning |
|||
- `.cursor/rules/meta_feature_implementation.mdc` for implementation workflow |
|||
- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation |
|||
|
|||
**Status**: Active meta-rule for feature planning |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: All bundled sub-rules |
|||
**Stakeholders**: Development team, Product team, Architecture team |
@ -0,0 +1,247 @@ |
|||
# Meta-Rule: Enhanced Research Workflows |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-01-27 |
|||
**Status**: 🎯 **ACTIVE** - Research and investigation workflows |
|||
|
|||
## Purpose |
|||
|
|||
This meta-rule bundles research-specific rules that should be applied when conducting |
|||
systematic investigation, analysis, evidence collection, or research tasks. It provides |
|||
a comprehensive framework for thorough, methodical research workflows that produce |
|||
actionable insights and evidence-based conclusions. |
|||
|
|||
## When to Use |
|||
|
|||
**RESEARCH TASKS** - Apply this meta-rule when: |
|||
|
|||
- Investigating bugs, defects, or system issues |
|||
- Conducting technical research or feasibility analysis |
|||
- Analyzing codebases, architectures, or dependencies |
|||
- Researching solutions, alternatives, or best practices |
|||
- Collecting evidence for decision-making or documentation |
|||
- Performing root cause analysis or impact assessment |
|||
|
|||
## Bundled Rules |
|||
|
|||
### **Core Research Principles** |
|||
|
|||
- **`development/research_diagnostic.mdc`** - Systematic investigation workflow |
|||
and evidence collection methodology |
|||
- **`development/type_safety_guide.mdc`** - Type analysis and safety research |
|||
for TypeScript/JavaScript codebases |
|||
|
|||
### **Investigation & Analysis** |
|||
|
|||
- **`workflow/version_control.mdc`** - Git history analysis and commit research |
|||
- **`workflow/commit_messages.mdc`** - Commit pattern analysis and history |
|||
investigation |
|||
|
|||
### **Platform & Context Research** |
|||
|
|||
- **`app/timesafari.mdc`** - Application context research and platform |
|||
understanding |
|||
- **`app/timesafari_platforms.mdc`** - Platform-specific research and |
|||
capability analysis |
|||
|
|||
## Why These Rules Are Research-Focused |
|||
|
|||
### **Research Diagnostic** |
|||
|
|||
- **Systematic Approach**: Provides structured investigation methodology |
|||
- **Evidence Collection**: Ensures thorough data gathering and documentation |
|||
- **Root Cause Analysis**: Guides systematic problem investigation |
|||
- **Impact Assessment**: Helps evaluate scope and consequences |
|||
|
|||
### **Type Safety Research** |
|||
|
|||
- **Code Analysis**: Enables systematic type system investigation |
|||
- **Safety Assessment**: Guides research into type-related issues |
|||
- **Migration Planning**: Supports research for architectural changes |
|||
|
|||
### **Version Control Research** |
|||
|
|||
- **History Analysis**: Enables investigation of code evolution |
|||
- **Pattern Recognition**: Helps identify commit and change patterns |
|||
- **Timeline Research**: Supports chronological investigation |
|||
|
|||
### **Platform Research** |
|||
|
|||
- **Capability Analysis**: Guides research into platform-specific features |
|||
- **Context Understanding**: Ensures research considers application context |
|||
- **Cross-Platform Research**: Supports multi-platform investigation |
|||
|
|||
## Application Priority |
|||
|
|||
### **Primary (Apply First)** |
|||
|
|||
1. **Research Diagnostic** - Systematic investigation methodology |
|||
2. **Type Safety Guide** - Code analysis and type research |
|||
3. **Application Context** - Platform and context understanding |
|||
|
|||
### **Secondary (Apply as Needed)** |
|||
|
|||
1. **Version Control** - When investigating code history |
|||
2. **Platform Details** - When researching platform-specific capabilities |
|||
|
|||
## Integration with Other Meta-Rules |
|||
|
|||
### **Bug Diagnosis** |
|||
|
|||
- Research meta-rule provides investigation methodology |
|||
- Core always-on ensures systematic approach |
|||
- Application context provides system understanding |
|||
|
|||
### **Feature Planning** |
|||
|
|||
- Research meta-rule guides feasibility research |
|||
- Core always-on ensures competence focus |
|||
- Application context drives platform considerations |
|||
|
|||
### **Architecture Analysis** |
|||
|
|||
- Research meta-rule provides systematic analysis framework |
|||
- Core always-on ensures quality standards |
|||
- Application context informs architectural decisions |
|||
|
|||
### **Performance Investigation** |
|||
|
|||
- Research meta-rule guides systematic performance research |
|||
- Core always-on ensures thorough investigation |
|||
- Application context provides performance context |
|||
|
|||
## Research Workflow Phases |
|||
|
|||
### **Phase 1: Investigation Setup** |
|||
|
|||
1. **Scope Definition** - Define research boundaries and objectives |
|||
2. **Context Gathering** - Collect relevant application and platform context |
|||
3. **Methodology Selection** - Choose appropriate research approaches |
|||
|
|||
### **Phase 2: Evidence Collection** |
|||
|
|||
1. **Systematic Data Gathering** - Collect evidence using structured methods |
|||
2. **Documentation** - Record all findings and observations |
|||
3. **Validation** - Verify evidence accuracy and relevance |
|||
|
|||
### **Phase 3: Analysis & Synthesis** |
|||
|
|||
1. **Pattern Recognition** - Identify trends and patterns in evidence |
|||
2. **Root Cause Analysis** - Determine underlying causes and factors |
|||
3. **Impact Assessment** - Evaluate scope and consequences |
|||
|
|||
### **Phase 4: Conclusion & Action** |
|||
|
|||
1. **Evidence-Based Conclusions** - Draw conclusions from collected evidence |
|||
2. **Actionable Recommendations** - Provide specific, implementable guidance |
|||
3. **Documentation** - Create comprehensive research documentation |
|||
|
|||
## Success Criteria |
|||
|
|||
- [ ] **Research diagnostic applied** to all investigation tasks |
|||
- [ ] **Type safety research** conducted for code analysis |
|||
- [ ] **Evidence collection** systematic and comprehensive |
|||
- [ ] **Root cause analysis** thorough and accurate |
|||
- [ ] **Conclusions actionable** and evidence-based |
|||
- [ ] **Documentation complete** and searchable |
|||
|
|||
## Common Research Pitfalls |
|||
|
|||
- **Don't skip systematic approach** - leads to incomplete investigation |
|||
- **Don't ignore evidence validation** - creates unreliable conclusions |
|||
- **Don't forget context** - misses important factors |
|||
- **Don't skip documentation** - loses research value |
|||
- **Don't rush conclusions** - produces poor recommendations |
|||
|
|||
## Research Quality Standards |
|||
|
|||
### **Evidence Quality** |
|||
|
|||
- **Completeness**: All relevant evidence collected |
|||
- **Accuracy**: Evidence verified and validated |
|||
- **Relevance**: Evidence directly addresses research questions |
|||
- **Timeliness**: Evidence current and up-to-date |
|||
|
|||
### **Analysis Quality** |
|||
|
|||
- **Systematic**: Analysis follows structured methodology |
|||
- **Objective**: Analysis free from bias and assumptions |
|||
- **Thorough**: All evidence considered and evaluated |
|||
- **Logical**: Conclusions follow from evidence |
|||
|
|||
### **Documentation Quality** |
|||
|
|||
- **Comprehensive**: All findings and methods documented |
|||
- **Searchable**: Documentation easily findable and navigable |
|||
- **Actionable**: Recommendations specific and implementable |
|||
- **Maintainable**: Documentation structure supports updates |
|||
|
|||
## Feedback & Improvement |
|||
|
|||
### **Rule Effectiveness Ratings (1-5 scale)** |
|||
|
|||
- **Research Diagnostic**: ___/5 - Comments: _______________ |
|||
- **Type Safety Guide**: ___/5 - Comments: _______________ |
|||
- **Version Control**: ___/5 - Comments: _______________ |
|||
- **Platform Context**: ___/5 - Comments: _______________ |
|||
|
|||
### **Research Workflow Effectiveness** |
|||
|
|||
- **Investigation Quality**: Are research tasks producing thorough results? |
|||
- **Evidence Collection**: Is evidence gathering systematic and complete? |
|||
- **Conclusion Quality**: Are conclusions actionable and evidence-based? |
|||
- **Documentation Value**: Is research documentation useful and maintainable? |
|||
|
|||
### **Integration Feedback** |
|||
|
|||
- **With Other Meta-Rules**: How well does this integrate with workflow rules? |
|||
- **Context Switching**: Do these rules help or hinder research context? |
|||
- **Learning Curve**: Are these rules easy for new researchers to understand? |
|||
|
|||
### **Overall Research Experience** |
|||
|
|||
- **Quality Improvement**: Do these rules improve research outcomes? |
|||
- **Efficiency**: Do these rules make research more efficient? |
|||
- **Recommendation**: Would you recommend keeping this research meta-rule? |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Research Tasks |
|||
|
|||
- [ ] **Research Diagnostic**: Ensure systematic investigation methodology |
|||
- [ ] **Type Safety Guide**: Prepare for code analysis if needed |
|||
- [ ] **Application Context**: Load relevant platform and context information |
|||
- [ ] **Version Control**: Prepare for history analysis if needed |
|||
|
|||
### During Research Execution |
|||
|
|||
- [ ] **Systematic Approach**: Follow structured investigation methodology |
|||
- [ ] **Evidence Collection**: Gather comprehensive and validated evidence |
|||
- [ ] **Documentation**: Record all findings and observations |
|||
- [ ] **Context Awareness**: Consider application and platform context |
|||
|
|||
### After Research Completion |
|||
|
|||
- [ ] **Validation**: Verify all research phases completed |
|||
- [ ] **Quality Check**: Ensure research meets quality standards |
|||
- [ ] **Documentation Review**: Confirm research properly documented |
|||
- [ ] **Feedback Collection**: Note any issues with research process |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/meta_core_always_on.mdc` for core always-on rules |
|||
- `.cursor/rules/meta_feature_planning.mdc` for feature development workflows |
|||
- `.cursor/rules/meta_bug_diagnosis.mdc` for bug investigation workflows |
|||
- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation workflows |
|||
|
|||
**Status**: Active research meta-rule |
|||
**Priority**: High (applies to all research tasks) |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: All bundled sub-rules |
|||
**Stakeholders**: Development team, Research team, Quality Assurance team |
|||
description: |
|||
globs: |
|||
alwaysApply: false |
|||
--- |
@ -0,0 +1,103 @@ |
|||
# Meta-Rule Architecture Overview |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-01-27 |
|||
**Status**: 📋 **ACTIVE** - Meta-rule organization and relationships |
|||
|
|||
## Meta-Rule Structure |
|||
|
|||
### **Core Always-On Rules** (`meta_core_always_on.mdc`) |
|||
- **Purpose**: Applied to every single prompt |
|||
- **Scope**: Human competence, time standards, version control, application context |
|||
- **Priority**: Critical - foundation for all interactions |
|||
|
|||
### **Enhanced Research Workflows** (`meta_research.mdc`) ⭐ **NEW** |
|||
- **Purpose**: Applied to research, investigation, and analysis tasks |
|||
- **Scope**: Systematic investigation, evidence collection, root cause analysis |
|||
- **Priority**: High - applies to all research tasks |
|||
- **Bundles**: Research diagnostic, type safety, version control research, platform context |
|||
|
|||
### **Feature Development Workflows** (`meta_feature_planning.mdc`) |
|||
- **Purpose**: Applied to feature planning and development tasks |
|||
- **Scope**: Requirements analysis, architecture planning, implementation strategy |
|||
- **Priority**: High - applies to feature development |
|||
|
|||
### **Bug Investigation Workflows** (`meta_bug_diagnosis.mdc`) |
|||
- **Purpose**: Applied to bug investigation and diagnosis tasks |
|||
- **Scope**: Defect analysis, evidence collection, root cause identification |
|||
- **Priority**: High - applies to bug investigation |
|||
|
|||
### **Bug Fixing Workflows** (`meta_bug_fixing.mdc`) |
|||
- **Purpose**: Applied to bug fixing and resolution tasks |
|||
- **Scope**: Fix implementation, testing, validation |
|||
- **Priority**: High - applies to bug resolution |
|||
|
|||
## Research Meta-Rule Integration |
|||
|
|||
### **When to Use Research Meta-Rule** |
|||
|
|||
The research meta-rule should be applied when: |
|||
- **Investigating bugs** - systematic defect analysis |
|||
- **Researching solutions** - feasibility and alternative analysis |
|||
- **Analyzing codebases** - architecture and dependency research |
|||
- **Collecting evidence** - systematic data gathering |
|||
- **Root cause analysis** - systematic problem investigation |
|||
- **Impact assessment** - scope and consequence evaluation |
|||
|
|||
### **How It Complements Other Meta-Rules** |
|||
|
|||
- **Core Always-On**: Provides foundation (competence, time, context) |
|||
- **Research**: Adds systematic investigation methodology |
|||
- **Feature Planning**: Guides feasibility research and analysis |
|||
- **Bug Diagnosis**: Provides investigation framework |
|||
- **Bug Fixing**: Informs fix strategy through research |
|||
|
|||
### **Research Workflow Phases** |
|||
|
|||
1. **Investigation Setup** - Scope, context, methodology |
|||
2. **Evidence Collection** - Systematic data gathering |
|||
3. **Analysis & Synthesis** - Pattern recognition, root cause |
|||
4. **Conclusion & Action** - Evidence-based recommendations |
|||
|
|||
## Usage Examples |
|||
|
|||
### **Bug Investigation** |
|||
``` |
|||
Apply: meta_core_always_on + meta_research + meta_bug_diagnosis |
|||
Result: Systematic investigation with evidence collection and root cause analysis |
|||
``` |
|||
|
|||
### **Feature Research** |
|||
``` |
|||
Apply: meta_core_always_on + meta_research + meta_feature_planning |
|||
Result: Comprehensive feasibility research with platform context |
|||
``` |
|||
|
|||
### **Architecture Analysis** |
|||
``` |
|||
Apply: meta_core_always_on + meta_research |
|||
Result: Systematic architecture investigation with evidence-based conclusions |
|||
``` |
|||
|
|||
## Benefits of Enhanced Research Meta-Rule |
|||
|
|||
- **Systematic Approach**: Structured investigation methodology |
|||
- **Evidence-Based**: Comprehensive data collection and validation |
|||
- **Quality Standards**: Defined research quality criteria |
|||
- **Integration**: Seamless integration with existing workflows |
|||
- **Documentation**: Comprehensive research documentation standards |
|||
|
|||
## Next Steps |
|||
|
|||
1. **Test Research Meta-Rule** - Apply to next research task |
|||
2. **Validate Integration** - Ensure smooth workflow integration |
|||
3. **Collect Feedback** - Gather effectiveness ratings |
|||
4. **Iterate** - Refine based on usage experience |
|||
|
|||
--- |
|||
|
|||
**Status**: Active documentation |
|||
**Priority**: Medium |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: All meta-rules |
|||
**Stakeholders**: Development team, Research team |
@ -0,0 +1,196 @@ |
|||
# Commit Message Format and Templates |
|||
|
|||
> **Agent role**: |
|||
Reference this file for commit message formatting and templates. |
|||
|
|||
## Commit Message Format (Normative) |
|||
|
|||
### A. Subject Line (required) |
|||
|
|||
``` |
|||
|
|||
<type>(<scope>)<!>: <summary> |
|||
|
|||
``` |
|||
|
|||
- **type** (lowercase, Conventional Commits): |
|||
|
|||
`feat|fix|refactor|perf|docs|test|build|chore|ci|revert` |
|||
|
|||
- **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`) |
|||
|
|||
- **!**: include when a breaking change is introduced |
|||
|
|||
- **summary**: imperative mood, ≤ 72 chars, no trailing period |
|||
|
|||
**Examples** |
|||
|
|||
- `fix(api): handle null token in refresh path` |
|||
|
|||
- `feat(ui/login)!: require OTP after 3 failed attempts` |
|||
|
|||
### B. Body (optional, when it adds non-obvious value) |
|||
|
|||
- One blank line after subject. |
|||
|
|||
- Wrap at ~72 chars. |
|||
|
|||
- Explain **what** and **why**, not line-by-line "how". |
|||
|
|||
- Include brief notes like tests passing or TS/lint issues resolved |
|||
|
|||
**only if material**. |
|||
|
|||
**Body checklist** |
|||
|
|||
- [ ] Problem/symptom being addressed |
|||
|
|||
- [ ] High-level approach or rationale |
|||
|
|||
- [ ] Risks, tradeoffs, or follow-ups (if any) |
|||
|
|||
### C. Footer (optional) |
|||
|
|||
- Issue refs: `Closes #123`, `Refs #456` |
|||
|
|||
- Breaking change (alternative to `!`): |
|||
|
|||
`BREAKING CHANGE: <impact + migration note>` |
|||
|
|||
- Authors: `Co-authored-by: Name <email>` |
|||
|
|||
- Security: `CVE-XXXX-YYYY: <short note>` (if applicable) |
|||
|
|||
## Content Guidance |
|||
|
|||
### Include (when relevant) |
|||
|
|||
- Specific fixes/features delivered |
|||
|
|||
- Symptoms/problems fixed |
|||
|
|||
- Brief note that tests passed or TS/lint errors resolved |
|||
|
|||
### Avoid |
|||
|
|||
- Vague: *improved, enhanced, better* |
|||
|
|||
- Trivialities: tiny docs, one-liners, pure lint cleanups (separate, |
|||
|
|||
focused commits if needed) |
|||
|
|||
- Redundancy: generic blurbs repeated across files |
|||
|
|||
- Multi-purpose dumps: keep commits **narrow and focused** |
|||
|
|||
- Long explanations that good inline code comments already cover |
|||
|
|||
**Guiding Principle:** Let code and inline docs speak. Use commits to |
|||
highlight what isn't obvious. |
|||
|
|||
## Copy-Paste Templates |
|||
|
|||
### Minimal (no body) |
|||
|
|||
```text |
|||
|
|||
<type>(<scope>): <summary> |
|||
|
|||
``` |
|||
|
|||
### Standard (with body & footer) |
|||
|
|||
```text |
|||
|
|||
<type>(<scope>)<!>: <summary> |
|||
|
|||
<why-this-change?> |
|||
<what-it-does?> |
|||
<risks-or-follow-ups?> |
|||
|
|||
Closes #<id> |
|||
BREAKING CHANGE: <impact + migration> |
|||
Co-authored-by: <Name> <email> |
|||
|
|||
``` |
|||
|
|||
## Type Descriptions |
|||
|
|||
### feat |
|||
|
|||
New feature for the user |
|||
|
|||
### fix |
|||
|
|||
Bug fix for the user |
|||
|
|||
### docs |
|||
|
|||
Documentation only changes |
|||
|
|||
### style |
|||
|
|||
Changes that do not affect the meaning of the code |
|||
|
|||
### refactor |
|||
|
|||
Code change that neither fixes a bug nor adds a feature |
|||
|
|||
### perf |
|||
|
|||
Code change that improves performance |
|||
|
|||
### test |
|||
|
|||
Adding missing tests or correcting existing tests |
|||
|
|||
### build |
|||
|
|||
Changes that affect the build system or external dependencies |
|||
|
|||
### ci |
|||
|
|||
Changes to CI configuration files and scripts |
|||
|
|||
### chore |
|||
|
|||
Other changes that don't modify src or test files |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/workflow/version_control.mdc` for |
|||
|
|||
core version control principles |
|||
|
|||
- `.cursor/rules/workflow/version_sync.mdc` for version synchronization details |
|||
|
|||
**Status**: Active commit message guidelines |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: version_control.mdc |
|||
**Stakeholders**: Development team, AI assistants |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Creating Commits |
|||
|
|||
- [ ] **Change Review**: Review all changes to be committed |
|||
- [ ] **Scope Assessment**: Determine if changes belong in single or multiple commits |
|||
- [ ] **Message Planning**: Plan clear, descriptive commit message |
|||
- [ ] **Convention Check**: Review commit message format requirements |
|||
|
|||
### During Commit Creation |
|||
|
|||
- [ ] **Type Selection**: Choose appropriate commit type (feat, fix, docs, etc.) |
|||
- [ ] **Message Writing**: Write clear, concise commit message |
|||
- [ ] **Body Content**: Add detailed description if needed |
|||
- [ ] **Breaking Changes**: Document breaking changes with `!` and migration notes |
|||
|
|||
### After Commit Creation |
|||
|
|||
- [ ] **Message Review**: Verify commit message follows conventions |
|||
- [ ] **Change Validation**: Confirm all intended changes are included |
|||
- [ ] **Documentation**: Update any related documentation |
|||
- [ ] **Team Communication**: Communicate significant changes to team |
@ -1,153 +1,86 @@ |
|||
--- |
|||
alwaysApply: true |
|||
--- |
|||
# Directive: Peaceful Co-Existence with Developers |
|||
|
|||
## 1) Version-Control Ownership |
|||
|
|||
* **MUST NOT** run `git add`, `git commit`, or any write action. |
|||
* **MUST** leave staging/committing to the developer. |
|||
|
|||
## 2) Source of Truth for Commit Text |
|||
|
|||
* **MUST** derive messages **only** from: |
|||
|
|||
* files **staged** for commit (primary), and |
|||
* files **awaiting staging** (context). |
|||
* **MUST** use the **diffs** to inform content. |
|||
* **MUST NOT** invent changes or imply work not present in diffs. |
|||
|
|||
## 3) Mandatory Preview Flow |
|||
|
|||
* **ALWAYS** present, before any real commit: |
|||
|
|||
* file list + brief per-file notes, |
|||
* a **draft commit message** (copy-paste ready), |
|||
* nothing auto-applied. |
|||
|
|||
## 4) Version Synchronization Requirements |
|||
|
|||
* **MUST** check for version changes in `package.json` before committing |
|||
* **MUST** ensure `CHANGELOG.md` is updated when `package.json` version changes |
|||
* **MUST** validate version format consistency between both files |
|||
* **MUST** include version bump commits in changelog with proper semantic versioning |
|||
|
|||
### Version Sync Checklist (Before Commit) |
|||
|
|||
- [ ] `package.json` version matches latest `CHANGELOG.md` entry |
|||
- [ ] New version follows semantic versioning (MAJOR.MINOR.PATCH[-PRERELEASE]) |
|||
- [ ] Changelog entry includes all significant changes since last version |
|||
- [ ] Version bump commit message follows `build(version): bump to X.Y.Z` format |
|||
- [ ] Breaking changes properly documented with migration notes |
|||
- [ ] Alert developer in chat message that version has been updated |
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-19 |
|||
**Status**: 🎯 **ACTIVE** - Version control guidelines |
|||
|
|||
### Version Change Detection |
|||
## Core Principles |
|||
|
|||
* **Check for version changes** in staged/unstaged `package.json` |
|||
* **Alert developer** if version changed but changelog not updated |
|||
* **Suggest changelog update** with proper format and content |
|||
* **Validate semantic versioning** compliance |
|||
### 1) Version-Control Ownership |
|||
|
|||
### Implementation Notes |
|||
- **MUST NOT** run `git add`, `git commit`, or any write action. |
|||
- **MUST** leave staging/committing to the developer. |
|||
|
|||
* **Version Detection**: Compare `package.json` version field with latest changelog entry |
|||
* **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]` format |
|||
* **Changelog Format**: Follow [Keep a Changelog](https://keepachangelog.com/) standards |
|||
* **Breaking Changes**: Use `!` in commit message and `BREAKING CHANGE:` in changelog |
|||
* **Pre-release Versions**: Include beta/alpha/rc suffixes in both files consistently |
|||
### 2) Source of Truth for Commit Text |
|||
|
|||
--- |
|||
|
|||
# Commit Message Format (Normative) |
|||
|
|||
## A. Subject Line (required) |
|||
|
|||
``` |
|||
<type>(<scope>)<!>: <summary> |
|||
``` |
|||
- **MUST** derive messages **only** from: |
|||
|
|||
* **type** (lowercase, Conventional Commits): `feat|fix|refactor|perf|docs|test|build|chore|ci|revert` |
|||
* **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`) |
|||
* **!**: include when a breaking change is introduced |
|||
* **summary**: imperative mood, ≤ 72 chars, no trailing period |
|||
- files **staged** for commit (primary), and |
|||
- files **awaiting staging** (context). |
|||
|
|||
**Examples** |
|||
- **MUST** use the **diffs** to inform content. |
|||
- **MUST NOT** invent changes or imply work not present in diffs. |
|||
|
|||
* `fix(api): handle null token in refresh path` |
|||
* `feat(ui/login)!: require OTP after 3 failed attempts` |
|||
### 3) Mandatory Preview Flow |
|||
|
|||
## B. Body (optional, when it adds non-obvious value) |
|||
- **ALWAYS** present, before any real commit: |
|||
|
|||
* One blank line after subject. |
|||
* Wrap at \~72 chars. |
|||
* Explain **what** and **why**, not line-by-line “how”. |
|||
* Include brief notes like tests passing or TS/lint issues resolved **only if material**. |
|||
- file list + brief per-file notes, |
|||
- a **draft commit message** (copy-paste ready), |
|||
- nothing auto-applied. |
|||
|
|||
**Body checklist** |
|||
### 4) Version Synchronization Requirements |
|||
|
|||
* [ ] Problem/symptom being addressed |
|||
* [ ] High-level approach or rationale |
|||
* [ ] Risks, tradeoffs, or follow-ups (if any) |
|||
- **MUST** check for version changes in `package.json` before committing |
|||
- **MUST** ensure `CHANGELOG.md` is updated when `package.json` version changes |
|||
- **MUST** validate version format consistency between both files |
|||
- **MUST** include version bump commits in changelog with |
|||
proper semantic versioning |
|||
|
|||
## C. Footer (optional) |
|||
## Assistant Output Checklist (before showing the draft) |
|||
|
|||
* Issue refs: `Closes #123`, `Refs #456` |
|||
* Breaking change (alternative to `!`): |
|||
`BREAKING CHANGE: <impact + migration note>` |
|||
* Authors: `Co-authored-by: Name <email>` |
|||
* Security: `CVE-XXXX-YYYY: <short note>` (if applicable) |
|||
- [ ] List changed files + 1–2 line notes per file |
|||
- [ ] Provide **one** focused draft message (subject/body/footer) |
|||
- [ ] Subject ≤ 72 chars, imperative mood, correct `type(scope)!` syntax |
|||
- [ ] Body only if it adds non-obvious value |
|||
- [ ] No invented changes; aligns strictly with diffs |
|||
- [ ] Render as a single copy-paste block for the developer |
|||
- [ ] No invented changes; aligns strictly with diffs |
|||
- [ ] Render as a single copy-paste block for the developer |
|||
|
|||
--- |
|||
|
|||
## Content Guidance |
|||
**See also**: |
|||
|
|||
### Include (when relevant) |
|||
- `.cursor/rules/workflow/commit_messages.mdc` for commit message format and |
|||
templates |
|||
- `.cursor/rules/workflow/version_sync.mdc` for version synchronization details |
|||
|
|||
* Specific fixes/features delivered |
|||
* Symptoms/problems fixed |
|||
* Brief note that tests passed or TS/lint errors resolved |
|||
**Status**: Active version control guidelines |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: git, package.json, CHANGELOG.md |
|||
**Stakeholders**: Development team, AI assistants |
|||
|
|||
### Avoid |
|||
## Model Implementation Checklist |
|||
|
|||
* Vague: *improved, enhanced, better* |
|||
* Trivialities: tiny docs, one-liners, pure lint cleanups (separate, focused commits if needed) |
|||
* Redundancy: generic blurbs repeated across files |
|||
* Multi-purpose dumps: keep commits **narrow and focused** |
|||
* Long explanations that good inline code comments already cover |
|||
|
|||
**Guiding Principle:** Let code and inline docs speak. Use commits to highlight what isn’t obvious. |
|||
|
|||
--- |
|||
### Before Version Control Work |
|||
|
|||
# Copy-Paste Templates |
|||
- [ ] **File Analysis**: Review files staged and awaiting staging |
|||
- [ ] **Version Check**: Check for version changes in package.json |
|||
- [ ] **Changelog Review**: Verify CHANGELOG.md is updated if version changed |
|||
- [ ] **Diff Analysis**: Analyze actual changes from git diffs |
|||
|
|||
## Minimal (no body) |
|||
### During Version Control Work |
|||
|
|||
```text |
|||
<type>(<scope>): <summary> |
|||
``` |
|||
|
|||
## Standard (with body & footer) |
|||
|
|||
```text |
|||
<type>(<scope>)<!>: <summary> |
|||
|
|||
<why-this-change?> |
|||
<what-it-does?> |
|||
<risks-or-follow-ups?> |
|||
|
|||
Closes #<id> |
|||
BREAKING CHANGE: <impact + migration> |
|||
Co-authored-by: <Name> <email> |
|||
``` |
|||
|
|||
--- |
|||
- [ ] **Commit Preview**: Present file list with brief notes per file |
|||
- [ ] **Message Draft**: Provide focused draft commit message |
|||
- [ ] **Format Validation**: Ensure message follows type(scope)! syntax |
|||
- [ ] **Version Sync**: Validate version consistency between files |
|||
|
|||
# Assistant Output Checklist (before showing the draft) |
|||
### After Version Control Work |
|||
|
|||
* [ ] List changed files + 1–2 line notes per file |
|||
* [ ] Provide **one** focused draft message (subject/body/footer) |
|||
* [ ] Subject ≤ 72 chars, imperative mood, correct `type(scope)!` syntax |
|||
* [ ] Body only if it adds non-obvious value |
|||
* [ ] No invented changes; aligns strictly with diffs |
|||
* [ ] Render as a single copy-paste block for the developer |
|||
- [ ] **Developer Control**: Leave staging/committing to developer |
|||
- [ ] **Message Validation**: Verify message aligns strictly with diffs |
|||
- [ ] **Version Validation**: Confirm version format consistency |
|||
- [ ] **Documentation**: Update relevant version control documentation |
|||
|
@ -0,0 +1,176 @@ |
|||
# Version Synchronization and Changelog Management |
|||
|
|||
> **Agent role**: Reference this file for version synchronization |
|||
> requirements and changelog management. |
|||
|
|||
## Version Sync Checklist (Before Commit) |
|||
|
|||
- [ ] `package.json` version matches latest `CHANGELOG.md` entry |
|||
- [ ] New version follows semantic versioning |
|||
(MAJOR.MINOR.PATCH[-PRERELEASE]) |
|||
- [ ] Changelog entry includes all significant changes since last version |
|||
- [ ] Version bump commit message follows `build(version): bump to X.Y.Z` |
|||
format |
|||
- [ ] Breaking changes properly documented with migration notes |
|||
- [ ] Alert developer in chat message that version has been updated |
|||
|
|||
## Version Change Detection |
|||
|
|||
- **Check for version changes** in staged/unstaged `package.json` |
|||
- **Alert developer** if version changed but changelog not updated |
|||
- **Suggest changelog update** with proper format and content |
|||
- **Validate semantic versioning** compliance |
|||
|
|||
## Implementation Notes |
|||
|
|||
### Version Detection |
|||
|
|||
- Compare `package.json` version field with latest changelog entry |
|||
- Use semantic versioning validation |
|||
- Check for pre-release version consistency |
|||
|
|||
### Semantic Validation |
|||
|
|||
- Ensure version follows `X.Y.Z[-PRERELEASE]` format |
|||
- Validate major.minor.patch components |
|||
- Handle pre-release suffixes (beta, alpha, rc) |
|||
|
|||
### Changelog Format |
|||
|
|||
- Follow [Keep a Changelog](https://keepachangelog.com/) standards |
|||
- Use consistent section headers |
|||
- Include breaking change notes |
|||
- Maintain chronological order |
|||
|
|||
### Breaking Changes |
|||
|
|||
- Use `!` in commit message |
|||
- Include `BREAKING CHANGE:` in changelog |
|||
- Provide migration notes |
|||
- Document impact clearly |
|||
|
|||
### Pre-release Versions |
|||
|
|||
- Include beta/alpha/rc suffixes consistently |
|||
- Update both `package.json` and changelog |
|||
- Maintain version number alignment |
|||
- Document pre-release status |
|||
|
|||
## Changelog Sections |
|||
|
|||
### Added |
|||
|
|||
- New features |
|||
- New capabilities |
|||
- New dependencies |
|||
|
|||
### Changed |
|||
|
|||
- Changes in existing functionality |
|||
- API changes |
|||
- Performance improvements |
|||
|
|||
### Deprecated |
|||
|
|||
- Soon-to-be removed features |
|||
- Migration paths |
|||
- Sunset timelines |
|||
|
|||
### Removed |
|||
|
|||
- Removed features |
|||
- Breaking changes |
|||
- Deprecated items |
|||
|
|||
### Fixed |
|||
|
|||
- Bug fixes |
|||
- Security patches |
|||
- Performance fixes |
|||
|
|||
### Security |
|||
|
|||
- Security vulnerabilities |
|||
- CVE references |
|||
- Mitigation steps |
|||
|
|||
## Version Bump Guidelines |
|||
|
|||
### Patch (X.Y.Z+1) |
|||
|
|||
- Bug fixes |
|||
- Documentation updates |
|||
- Minor improvements |
|||
|
|||
### Minor (X.Y+1.Z) |
|||
|
|||
- New features |
|||
- Backward-compatible changes |
|||
- Significant improvements |
|||
|
|||
### Major (X+1.Y.Z) |
|||
|
|||
- Breaking changes |
|||
- Major API changes |
|||
- Incompatible changes |
|||
|
|||
## Pre-release Guidelines |
|||
|
|||
### Beta Versions |
|||
|
|||
- Feature complete |
|||
- Testing phase |
|||
- API stable |
|||
|
|||
### Alpha Versions |
|||
|
|||
- Early development |
|||
- API may change |
|||
- Limited testing |
|||
|
|||
### Release Candidates |
|||
|
|||
- Final testing |
|||
- API frozen |
|||
- Production ready |
|||
|
|||
--- |
|||
|
|||
**See also**: |
|||
|
|||
- `.cursor/rules/workflow/version_control.mdc` for core version |
|||
control principles |
|||
- `.cursor/rules/workflow/commit_messages.mdc` for commit message |
|||
format |
|||
|
|||
**Status**: Active version synchronization guide |
|||
**Priority**: High |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: version_control.mdc |
|||
**Stakeholders**: Development team, Release team |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Version Changes |
|||
|
|||
- [ ] **Version Review**: Check current version in `package.json` and `CHANGELOG.md` |
|||
- [ ] **Change Assessment**: Identify what type of version bump is needed (patch/minor/major) |
|||
- [ ] **Breaking Changes**: Review if any changes are breaking and require |
|||
major version |
|||
- [ ] **Pre-release Status**: Determine if this should be a pre-release version |
|||
|
|||
### During Version Synchronization |
|||
|
|||
- [ ] **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]` format |
|||
- [ ] **Package Update**: Update `package.json` version field |
|||
- [ ] **Changelog Entry**: Add entry to `CHANGELOG.md` following Keep a Changelog |
|||
format |
|||
- [ ] **Breaking Changes**: Document breaking changes with migration notes |
|||
if applicable |
|||
|
|||
### After Version Changes |
|||
|
|||
- [ ] **Commit Format**: Use `build(version): bump to X.Y.Z` commit message format |
|||
- [ ] **Developer Alert**: Alert developer that version has been updated |
|||
- [ ] **Validation**: Verify `package.json` and `CHANGELOG.md` are in sync |
|||
- [ ] **Pre-release Handling**: Ensure pre-release versions are consistently formatted |
@ -1,142 +0,0 @@ |
|||
name: Asset Validation & CI Safeguards |
|||
|
|||
on: |
|||
pull_request: |
|||
paths: |
|||
- 'resources/**' |
|||
- 'config/assets/**' |
|||
- 'capacitor-assets.config.json' |
|||
- 'capacitor.config.ts' |
|||
- 'capacitor.config.json' |
|||
push: |
|||
branches: [main, develop] |
|||
paths: |
|||
- 'resources/**' |
|||
- 'config/assets/**' |
|||
- 'capacitor-assets.config.json' |
|||
- 'capacitor.config.ts' |
|||
- 'capacitor.config.json' |
|||
|
|||
jobs: |
|||
asset-validation: |
|||
runs-on: ubuntu-latest |
|||
steps: |
|||
- name: Checkout code |
|||
uses: actions/checkout@v4 |
|||
|
|||
- name: Setup Node.js |
|||
uses: actions/setup-node@v4 |
|||
with: |
|||
node-version-file: '.nvmrc' |
|||
cache: 'npm' |
|||
|
|||
- name: Install dependencies |
|||
run: npm ci |
|||
|
|||
- name: Validate asset configuration |
|||
run: npm run assets:validate |
|||
|
|||
- name: Check for committed platform assets (Android) |
|||
run: | |
|||
if git ls-files -z android/app/src/main/res | grep -E '(AppIcon.*\.png|Splash.*\.png|mipmap-.*/ic_launcher.*\.png)' > /dev/null; then |
|||
echo "❌ Android platform assets found in VCS - these should be generated at build-time" |
|||
git ls-files -z android/app/src/main/res | grep -E '(AppIcon.*\.png|Splash.*\.png|mipmap-.*/ic_launcher.*\.png)' |
|||
exit 1 |
|||
fi |
|||
echo "✅ No Android platform assets committed" |
|||
|
|||
- name: Check for committed platform assets (iOS) |
|||
run: | |
|||
if git ls-files -z ios/App/App/Assets.xcassets | grep -E '(AppIcon.*\.png|Splash.*\.png)' > /dev/null; then |
|||
echo "❌ iOS platform assets found in VCS - these should be generated at build-time" |
|||
git ls-files -z ios/App/App/Assets.xcassets | grep -E '(AppIcon.*\.png|Splash.*\.png)' |
|||
exit 1 |
|||
fi |
|||
echo "✅ No iOS platform assets committed" |
|||
|
|||
- name: Test asset generation |
|||
run: | |
|||
echo "🧪 Testing asset generation workflow..." |
|||
npm run build:capacitor |
|||
npx cap sync |
|||
npx capacitor-assets generate --dry-run || npx capacitor-assets generate |
|||
echo "✅ Asset generation test completed" |
|||
|
|||
- name: Verify clean tree after build |
|||
run: | |
|||
if [ -n "$(git status --porcelain)" ]; then |
|||
echo "❌ Dirty tree after build - asset configs were modified" |
|||
git status |
|||
git diff |
|||
exit 1 |
|||
fi |
|||
echo "✅ Build completed with clean tree" |
|||
|
|||
schema-validation: |
|||
runs-on: ubuntu-latest |
|||
steps: |
|||
- name: Checkout code |
|||
uses: actions/checkout@v4 |
|||
|
|||
- name: Setup Node.js |
|||
uses: actions/setup-node@v4 |
|||
with: |
|||
node-version-file: '.nvmrc' |
|||
cache: 'npm' |
|||
|
|||
- name: Install dependencies |
|||
run: npm ci |
|||
|
|||
- name: Validate schema compliance |
|||
run: | |
|||
echo "🔍 Validating schema compliance..." |
|||
node -e " |
|||
const fs = require('fs'); |
|||
const config = JSON.parse(fs.readFileSync('capacitor-assets.config.json', 'utf8')); |
|||
const schema = JSON.parse(fs.readFileSync('config/assets/schema.json', 'utf8')); |
|||
|
|||
// Basic schema validation |
|||
if (!config.icon || !config.splash) { |
|||
throw new Error('Missing required sections: icon and splash'); |
|||
} |
|||
|
|||
if (!config.icon.source || !config.splash.source) { |
|||
throw new Error('Missing required source fields'); |
|||
} |
|||
|
|||
if (!/^resources\/.*\.(png|svg)$/.test(config.icon.source)) { |
|||
throw new Error('Icon source must be in resources/ directory'); |
|||
} |
|||
|
|||
if (!/^resources\/.*\.(png|svg)$/.test(config.splash.source)) { |
|||
throw new Error('Splash source must be in resources/ directory'); |
|||
} |
|||
|
|||
console.log('✅ Schema validation passed'); |
|||
" |
|||
|
|||
- name: Check source file existence |
|||
run: | |
|||
echo "📁 Checking source file existence..." |
|||
node -e " |
|||
const fs = require('fs'); |
|||
const config = JSON.parse(fs.readFileSync('capacitor-assets.config.json', 'utf8')); |
|||
|
|||
const requiredFiles = [ |
|||
config.icon.source, |
|||
config.splash.source |
|||
]; |
|||
|
|||
if (config.splash.darkSource) { |
|||
requiredFiles.push(config.splash.darkSource); |
|||
} |
|||
|
|||
const missingFiles = requiredFiles.filter(file => !fs.existsSync(file)); |
|||
|
|||
if (missingFiles.length > 0) { |
|||
console.error('❌ Missing source files:', missingFiles); |
|||
process.exit(1); |
|||
} |
|||
|
|||
console.log('✅ All source files exist'); |
|||
" |
@ -1,27 +0,0 @@ |
|||
name: Playwright Tests |
|||
on: |
|||
push: |
|||
branches: [ main, master ] |
|||
pull_request: |
|||
branches: [ main, master ] |
|||
jobs: |
|||
test: |
|||
timeout-minutes: 60 |
|||
runs-on: ubuntu-latest |
|||
steps: |
|||
- uses: actions/checkout@v4 |
|||
- uses: actions/setup-node@v4 |
|||
with: |
|||
node-version: lts/* |
|||
- name: Install dependencies |
|||
run: npm ci |
|||
- name: Install Playwright Browsers |
|||
run: npx playwright install --with-deps |
|||
- name: Run Playwright tests |
|||
run: npx playwright test |
|||
- uses: actions/upload-artifact@v4 |
|||
if: always() |
|||
with: |
|||
name: playwright-report |
|||
path: playwright-report/ |
|||
retention-days: 30 |
@ -0,0 +1,40 @@ |
|||
#!/usr/bin/env sh |
|||
# |
|||
# Husky Helper Script |
|||
# This file is sourced by all Husky hooks |
|||
# |
|||
if [ -z "$husky_skip_init" ]; then |
|||
debug () { |
|||
if [ "$HUSKY_DEBUG" = "1" ]; then |
|||
echo "husky (debug) - $1" |
|||
fi |
|||
} |
|||
|
|||
readonly hook_name="$(basename -- "$0")" |
|||
debug "starting $hook_name..." |
|||
|
|||
if [ "$HUSKY" = "0" ]; then |
|||
debug "HUSKY env variable is set to 0, skipping hook" |
|||
exit 0 |
|||
fi |
|||
|
|||
if [ -f ~/.huskyrc ]; then |
|||
debug "sourcing ~/.huskyrc" |
|||
. ~/.huskyrc |
|||
fi |
|||
|
|||
readonly husky_skip_init=1 |
|||
export husky_skip_init |
|||
sh -e "$0" "$@" |
|||
exitCode="$?" |
|||
|
|||
if [ $exitCode != 0 ]; then |
|||
echo "husky - $hook_name hook exited with code $exitCode (error)" |
|||
fi |
|||
|
|||
if [ $exitCode = 127 ]; then |
|||
echo "husky - command not found in PATH=$PATH" |
|||
fi |
|||
|
|||
exit $exitCode |
|||
fi |
@ -0,0 +1,10 @@ |
|||
#!/usr/bin/env bash |
|||
# |
|||
# Husky Commit Message Hook |
|||
# Validates commit message format using commitlint |
|||
# |
|||
. "$(dirname -- "$0")/_/husky.sh" |
|||
|
|||
# Run commitlint but don't fail the commit (|| true) |
|||
# This provides helpful feedback without blocking commits |
|||
npx commitlint --edit "$1" || true |
@ -0,0 +1,33 @@ |
|||
#!/usr/bin/env bash |
|||
# |
|||
# Husky Pre-commit Hook |
|||
# Runs lint-fix and Build Architecture Guard on staged files |
|||
# |
|||
. "$(dirname -- "$0")/_/husky.sh" |
|||
|
|||
echo "🔍 Running pre-commit hooks..." |
|||
|
|||
# Run lint-fix first |
|||
echo "📝 Running lint-fix..." |
|||
npm run lint-fix || { |
|||
echo |
|||
echo "❌ Linting failed. Please fix the issues and try again." |
|||
echo "💡 To bypass this check for emergency commits, use:" |
|||
echo " git commit --no-verify" |
|||
echo |
|||
exit 1 |
|||
} |
|||
|
|||
# Then run Build Architecture Guard |
|||
echo "🏗️ Running Build Architecture Guard..." |
|||
bash ./scripts/build-arch-guard.sh --staged || { |
|||
echo |
|||
echo "❌ Build Architecture Guard failed. Please fix the issues and try again." |
|||
echo "💡 To bypass this check for emergency commits, use:" |
|||
echo " git commit --no-verify" |
|||
echo |
|||
exit 1 |
|||
} |
|||
|
|||
echo "✅ All pre-commit checks passed!" |
|||
|
@ -0,0 +1,27 @@ |
|||
#!/usr/bin/env bash |
|||
# |
|||
# Husky Pre-push Hook |
|||
# Runs Build Architecture Guard to check commits being pushed |
|||
# |
|||
. "$(dirname -- "$0")/_/husky.sh" |
|||
|
|||
echo "🔍 Running Build Architecture Guard (pre-push)..." |
|||
|
|||
# Get the remote branch we're pushing to |
|||
REMOTE_BRANCH="origin/$(git rev-parse --abbrev-ref HEAD)" |
|||
|
|||
# Check if remote branch exists |
|||
if git show-ref --verify --quiet "refs/remotes/$REMOTE_BRANCH"; then |
|||
RANGE="$REMOTE_BRANCH...HEAD" |
|||
else |
|||
# If remote branch doesn't exist, check last commit |
|||
RANGE="HEAD~1..HEAD" |
|||
fi |
|||
|
|||
bash ./scripts/build-arch-guard.sh --range "$RANGE" || { |
|||
echo |
|||
echo "💡 To bypass this check for emergency pushes, use:" |
|||
echo " git push --no-verify" |
|||
echo |
|||
exit 1 |
|||
} |
@ -0,0 +1,53 @@ |
|||
{ |
|||
// Markdownlint configuration for TimeSafari .cursor/rules |
|||
"config": { |
|||
// Core formatting rules that can be auto-fixed |
|||
"MD013": { |
|||
"line_length": 80, |
|||
"code_blocks": false, |
|||
"tables": false, |
|||
"headings": false |
|||
}, |
|||
"MD012": true, // No multiple consecutive blank lines |
|||
"MD022": true, // Headings should be surrounded by blank lines |
|||
"MD031": true, // Fenced code blocks should be surrounded by blank lines |
|||
"MD032": true, // Lists should be surrounded by blank lines |
|||
"MD047": true, // Files should end with a single newline |
|||
"MD009": true, // No trailing spaces |
|||
"MD010": true, // No hard tabs |
|||
"MD004": { "style": "dash" }, // Consistent list markers |
|||
"MD029": { "style": "ordered" }, // Ordered list item prefix |
|||
|
|||
// Disable rules that conflict with existing content structure |
|||
"MD041": false, // First line heading requirement |
|||
"MD025": false, // Multiple top-level headings |
|||
"MD024": false, // Duplicate headings |
|||
"MD036": false, // Emphasis as headings |
|||
"MD003": false, // Heading style consistency |
|||
"MD040": false, // Fenced code language |
|||
"MD055": false, // Table pipe style |
|||
"MD056": false, // Table column count |
|||
"MD034": false, // Bare URLs |
|||
"MD023": false // Heading indentation |
|||
}, |
|||
|
|||
"globs": [ |
|||
".cursor/rules/**/*.mdc", |
|||
"*.md", |
|||
"*.markdown", |
|||
"scripts/**/*.md", |
|||
"src/**/*.md", |
|||
"test-playwright/**/*.md", |
|||
"resources/**/*.md", |
|||
"doc/**/*.md", |
|||
"ios/**/*.md", |
|||
"electron/**/*.md" |
|||
], |
|||
"ignores": [ |
|||
"node_modules/**", |
|||
".git/**", |
|||
"**/node_modules/**", |
|||
"**/dist/**", |
|||
"**/build/**" |
|||
] |
|||
} |
@ -1 +1,27 @@ |
|||
{"MD013": {"code_blocks": false}} |
|||
{ |
|||
"MD013": { |
|||
"line_length": 80, |
|||
"code_blocks": false, |
|||
"tables": false, |
|||
"headings": false |
|||
}, |
|||
"MD012": true, |
|||
"MD022": true, |
|||
"MD031": true, |
|||
"MD032": true, |
|||
"MD047": true, |
|||
"MD009": true, |
|||
"MD010": true, |
|||
"MD004": { "style": "dash" }, |
|||
"MD029": { "style": "ordered" }, |
|||
"MD041": false, |
|||
"MD025": false, |
|||
"MD024": false, |
|||
"MD036": false, |
|||
"MD003": false, |
|||
"MD040": false, |
|||
"MD055": false, |
|||
"MD056": false, |
|||
"MD034": false, |
|||
"MD023": false |
|||
} |
File diff suppressed because it is too large
@ -0,0 +1,82 @@ |
|||
# Pull Request Template |
|||
|
|||
## Location |
|||
|
|||
The Build Architecture Guard PR template is located at: |
|||
|
|||
- **`pull_request_template.md`** (root directory) |
|||
|
|||
## Usage |
|||
|
|||
When creating a pull request in Gitea, this template will automatically populate the PR description with the required checklist. |
|||
|
|||
## Template Features |
|||
|
|||
### Change Level Classification |
|||
|
|||
- **L1**: Minor changes, documentation updates |
|||
- **L2**: Moderate changes, new features, environment changes |
|||
- **L3**: Major changes, architecture changes, new platforms |
|||
|
|||
### Required Fields for All Levels |
|||
|
|||
- Change level selection |
|||
- Scope and impact description |
|||
- Commands executed and their output |
|||
- Documentation updates (BUILDING.md) |
|||
- Rollback verification steps |
|||
|
|||
### Additional Requirements for L3 |
|||
|
|||
- **ADR link**: Must provide URL to Architectural Decision Record |
|||
- **Artifacts with SHA256**: Must list artifacts with cryptographic hashes |
|||
|
|||
## Integration |
|||
|
|||
This template works with: |
|||
|
|||
- **Gitea Actions**: `.gitea/workflows/build-guard.yml` |
|||
- **Client-side hooks**: `.husky/` pre-commit and pre-push hooks |
|||
- **Guard script**: `scripts/build-arch-guard.sh` |
|||
|
|||
## Example Usage |
|||
|
|||
```markdown |
|||
### Change Level |
|||
- [x] Level: **L2** |
|||
|
|||
**Why:** Adding new build script for Docker deployment |
|||
|
|||
### Scope & Impact |
|||
- [x] Files & platforms touched: scripts/build-docker.sh, |
|||
BUILDING.md |
|||
- [x] Risk triggers: Docker build process changes |
|||
- [x] Mitigations/validation done: Tested on local Docker environment |
|||
|
|||
### Commands Run |
|||
- [x] Web: `npm run build:web:docker` ✅ |
|||
- [x] Docker: `docker build -t test-image .` ✅ |
|||
|
|||
### Artifacts |
|||
- [x] Names + **sha256** of artifacts/installers: |
|||
|
|||
Artifacts: |
|||
```text |
|||
test-image.tar a1b2c3d4e5f6... |
|||
``` |
|||
|
|||
### Docs |
|||
- [x] **BUILDING.md** updated (sections): Docker deployment |
|||
- [x] Troubleshooting updated: Added Docker troubleshooting section |
|||
|
|||
### Rollback |
|||
- [x] Verified steps to restore previous behavior: |
|||
1. `git revert HEAD` |
|||
2. `docker rmi test-image` |
|||
3. Restore previous BUILDING.md |
|||
``` |
|||
|
|||
--- |
|||
|
|||
**Note**: This template is enforced by the Build Architecture Guard |
|||
system. Complete all required fields to ensure your PR can be merged. |
@ -0,0 +1,44 @@ |
|||
package app.timesafari.safearea; |
|||
|
|||
import android.os.Build; |
|||
import android.view.WindowInsets; |
|||
import com.getcapacitor.JSObject; |
|||
import com.getcapacitor.Plugin; |
|||
import com.getcapacitor.PluginCall; |
|||
import com.getcapacitor.PluginMethod; |
|||
import com.getcapacitor.annotation.CapacitorPlugin; |
|||
|
|||
@CapacitorPlugin(name = "SafeArea") |
|||
public class SafeAreaPlugin extends Plugin { |
|||
|
|||
@PluginMethod |
|||
public void getSafeAreaInsets(PluginCall call) { |
|||
JSObject result = new JSObject(); |
|||
|
|||
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) { |
|||
WindowInsets insets = getActivity().getWindow().getDecorView().getRootWindowInsets(); |
|||
if (insets != null) { |
|||
int top = insets.getInsets(WindowInsets.Type.statusBars()).top; |
|||
int bottom = insets.getInsets(WindowInsets.Type.navigationBars()).bottom; |
|||
int left = insets.getInsets(WindowInsets.Type.systemBars()).left; |
|||
int right = insets.getInsets(WindowInsets.Type.systemBars()).right; |
|||
|
|||
result.put("top", top); |
|||
result.put("bottom", bottom); |
|||
result.put("left", left); |
|||
result.put("right", right); |
|||
|
|||
call.resolve(result); |
|||
return; |
|||
} |
|||
} |
|||
|
|||
// Fallback values
|
|||
result.put("top", 0); |
|||
result.put("bottom", 0); |
|||
result.put("left", 0); |
|||
result.put("right", 0); |
|||
|
|||
call.resolve(result); |
|||
} |
|||
} |
@ -0,0 +1,9 @@ |
|||
module.exports = { |
|||
extends: ['@commitlint/config-conventional'], |
|||
rules: { |
|||
// Downgrade strict case rules to warnings (level 1) instead of errors (level 2)
|
|||
// This eliminates red error messages while maintaining helpful guidance
|
|||
'subject-case': [1, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']], |
|||
'subject-full-stop': [1, 'never', '.'], |
|||
} |
|||
}; |
@ -0,0 +1,336 @@ |
|||
# Build Architecture Guard - Husky Implementation |
|||
|
|||
## Overview |
|||
|
|||
The Build Architecture Guard protects your build system by enforcing |
|||
documentation requirements through **Git hooks**. When you modify |
|||
build-critical files, the system automatically blocks commits/pushes |
|||
until you update `BUILDING.md`. |
|||
|
|||
## 🎯 **Why Husky-Only?** |
|||
|
|||
**Advantages:** |
|||
|
|||
- ✅ **Immediate feedback** - Hooks run before commit/push |
|||
- ✅ **Works everywhere** - No server-side CI/CD required |
|||
- ✅ **Simple setup** - One tool, one configuration |
|||
- ✅ **Fast execution** - No network delays or server queues |
|||
- ✅ **Offline support** - Works without internet connection |
|||
|
|||
**Trade-offs:** |
|||
|
|||
- ⚠️ **Can be bypassed** - `git commit --no-verify` or `git push --no-verify` |
|||
- ⚠️ **Developer discipline** - Relies on team following the rules |
|||
|
|||
## 🏗️ **Architecture** |
|||
|
|||
```bash |
|||
Developer Workflow: |
|||
1. Modify build files (scripts/, vite.config.*, etc.) |
|||
2. Try to commit → Husky pre-commit hook runs |
|||
3. Guard script checks if BUILDING.md was updated |
|||
4. ✅ Commit succeeds if docs updated |
|||
5. ❌ Commit blocked if docs missing |
|||
``` |
|||
|
|||
## 🚀 **Quick Start** |
|||
|
|||
### 1. Install Dependencies |
|||
|
|||
```bash |
|||
npm install |
|||
npm run prepare # Sets up Husky hooks |
|||
``` |
|||
|
|||
### 2. Test the System |
|||
|
|||
```bash |
|||
# Modify a build file without updating BUILDING.md |
|||
echo "# test" >> scripts/test.sh |
|||
|
|||
# Try to commit (should be blocked) |
|||
git add scripts/test.sh |
|||
git commit -m "test: add build script" |
|||
# ❌ Hook blocks commit with helpful message |
|||
``` |
|||
|
|||
### 3. Fix and Retry |
|||
|
|||
```bash |
|||
# Update BUILDING.md with your changes |
|||
echo "## New Build Script" >> BUILDING.md |
|||
echo "Added test.sh for testing purposes" >> BUILDING.md |
|||
|
|||
# Now commit should succeed |
|||
git add BUILDING.md |
|||
git commit -m "feat: add test build script with docs" |
|||
# ✅ Commit succeeds |
|||
``` |
|||
|
|||
## 🔧 **How It Works** |
|||
|
|||
### Pre-commit Hook (`.husky/pre-commit`) |
|||
|
|||
- **When**: Every `git commit` |
|||
- **What**: Runs `./scripts/build-arch-guard.sh --staged` |
|||
- **Result**: Blocks commit if build files changed without BUILDING.md update |
|||
|
|||
### Pre-push Hook (`.husky/pre-push`) |
|||
|
|||
- **When**: Every `git push` |
|||
- **What**: Runs `./scripts/build-arch-guard.sh --range` |
|||
- **Result**: Blocks push if commits contain undocumented build changes |
|||
|
|||
### Guard Script (`scripts/build-arch-guard.sh`) |
|||
|
|||
- **Detects**: Changes to build-sensitive file patterns |
|||
- **Validates**: BUILDING.md was updated alongside changes |
|||
- **Reports**: Clear error messages with guidance |
|||
|
|||
## 📁 **Protected File Patterns** |
|||
|
|||
The guard script monitors these paths for changes: |
|||
|
|||
```text |
|||
Build Configuration: |
|||
├── vite.config.* # Vite configuration |
|||
├── capacitor.config.ts # Capacitor configuration |
|||
├── package.json # Package configuration |
|||
├── package-lock.json # Lock files |
|||
├── yarn.lock |
|||
└── pnpm-lock.yaml |
|||
|
|||
Build Scripts: |
|||
├── scripts/** # All build and automation scripts |
|||
├── electron/** # Electron build files |
|||
├── android/** # Android build configuration |
|||
├── ios/** # iOS build configuration |
|||
├── sw_scripts/** # Service worker scripts |
|||
└── sw_combine.js # Service worker combination |
|||
|
|||
Deployment: |
|||
├── Dockerfile # Docker configuration |
|||
└── docker/** # Docker services |
|||
``` |
|||
|
|||
## 🎭 **Usage Scenarios** |
|||
|
|||
### Scenario 1: Adding a New Build Script |
|||
|
|||
```bash |
|||
# ❌ This will be blocked |
|||
echo '#!/bin/bash' > scripts/new-build.sh |
|||
git add scripts/new-build.sh |
|||
git commit -m "feat: add new build script" |
|||
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated" |
|||
|
|||
# ✅ This will succeed |
|||
echo '#!/bin/bash' > scripts/new-build.sh |
|||
echo '## New Build Script' >> BUILDING.md |
|||
echo 'Added new-build.sh for feature X' >> BUILDING.md |
|||
git add scripts/new-build.sh BUILDING.md |
|||
git commit -m "feat: add new build script with docs" |
|||
# ✅ Commit succeeds |
|||
``` |
|||
|
|||
### Scenario 2: Updating Vite Configuration |
|||
|
|||
```bash |
|||
# ❌ This will be blocked |
|||
echo 'export default { newOption: true }' >> vite.config.ts |
|||
git add vite.config.ts |
|||
git commit -m "config: add new vite option" |
|||
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated" |
|||
|
|||
# ✅ This will succeed |
|||
echo 'export default { newOption: true }' >> vite.config.ts |
|||
echo '### New Vite Option' >> BUILDING.md |
|||
echo 'Added newOption for improved performance' >> BUILDING.md |
|||
git add vite.config.ts BUILDING.md |
|||
git commit -m "config: add new vite option with docs" |
|||
# ✅ Commit succeeds |
|||
``` |
|||
|
|||
## 🚨 **Emergency Bypass** |
|||
|
|||
**⚠️ Use sparingly and only for emergencies:** |
|||
|
|||
```bash |
|||
# Skip pre-commit hook |
|||
git commit -m "emergency: critical fix" --no-verify |
|||
|
|||
# Skip pre-push hook |
|||
git push --no-verify |
|||
|
|||
# Remember to update BUILDING.md later! |
|||
``` |
|||
|
|||
## 🔍 **Troubleshooting** |
|||
|
|||
### Hooks Not Running |
|||
|
|||
```bash |
|||
# Reinstall hooks |
|||
npm run prepare |
|||
|
|||
# Check hook files exist and are executable |
|||
ls -la .husky/ |
|||
chmod +x .husky/* |
|||
|
|||
# Verify Git hooks path |
|||
git config core.hooksPath |
|||
# Should show: .husky |
|||
``` |
|||
|
|||
### Guard Script Issues |
|||
|
|||
```bash |
|||
# Test guard script manually |
|||
./scripts/build-arch-guard.sh --help |
|||
|
|||
# Check script permissions |
|||
chmod +x scripts/build-arch-guard.sh |
|||
|
|||
# Test with specific files |
|||
./scripts/build-arch-guard.sh --staged |
|||
``` |
|||
|
|||
### False Positives |
|||
|
|||
```bash |
|||
# If guard blocks legitimate changes, check: |
|||
# 1. Are you modifying a protected file pattern? |
|||
# 2. Did you update BUILDING.md? |
|||
# 3. Is BUILDING.md staged for commit? |
|||
|
|||
# View what the guard sees |
|||
git diff --name-only --cached |
|||
``` |
|||
|
|||
## 📋 **Best Practices** |
|||
|
|||
### For Developers |
|||
|
|||
1. **Update BUILDING.md first** - Document changes before implementing |
|||
2. **Test locally** - Run `./scripts/build-arch-guard.sh --staged` before committing |
|||
3. **Use descriptive commits** - Include context about build changes |
|||
4. **Don't bypass lightly** - Only use `--no-verify` for true emergencies |
|||
|
|||
### For Teams |
|||
|
|||
1. **Document the system** - Ensure everyone understands the guard |
|||
2. **Review BUILDING.md updates** - Verify documentation quality |
|||
3. **Monitor bypass usage** - Track when hooks are skipped |
|||
4. **Regular audits** - Check that BUILDING.md stays current |
|||
|
|||
### For Maintainers |
|||
|
|||
1. **Update protected patterns** - Modify `scripts/build-arch-guard.sh` as needed |
|||
2. **Monitor effectiveness** - Track how often the guard catches issues |
|||
3. **Team training** - Help developers understand the system |
|||
4. **Continuous improvement** - Refine patterns and error messages |
|||
|
|||
## 🚨 **Troubleshooting** |
|||
|
|||
### Common Issues |
|||
|
|||
#### mapfile Command Not Found |
|||
|
|||
**Problem**: Pre-commit hook fails with `mapfile: command not found` |
|||
|
|||
**Cause**: The `mapfile` command is bash-specific and not available in all shell environments |
|||
|
|||
**Solution**: The script has been updated to use portable alternatives. If you encounter this issue: |
|||
|
|||
```bash |
|||
# Verify the script is executable |
|||
chmod +x scripts/build-arch-guard.sh |
|||
|
|||
# Test the script directly |
|||
./scripts/build-arch-guard.sh --help |
|||
|
|||
# Check your shell environment |
|||
echo $SHELL |
|||
bash --version |
|||
``` |
|||
|
|||
**Prevention**: Ensure your development environment uses bash and the script has proper permissions |
|||
|
|||
### False Positives |
|||
|
|||
```bash |
|||
# If guard blocks legitimate changes, check: |
|||
# 1. Are you modifying a protected file pattern? |
|||
# 2. Did you update BUILDING.md? |
|||
# 3. Is BUILDING.md staged for commit? |
|||
|
|||
# View what the guard sees |
|||
git diff --name-only --cached |
|||
``` |
|||
|
|||
## 🔄 **Customization** |
|||
|
|||
### Adding New Protected Paths |
|||
|
|||
Edit `scripts/build-arch-guard.sh`: |
|||
|
|||
```bash |
|||
SENSITIVE=( |
|||
# ... existing patterns ... |
|||
"new-pattern/**" # Add your new pattern |
|||
"*.config.js" # Add file extensions |
|||
) |
|||
``` |
|||
|
|||
### Modifying Error Messages |
|||
|
|||
Edit the guard script to customize: |
|||
|
|||
- Error message content |
|||
- File pattern matching |
|||
- Documentation requirements |
|||
- Bypass instructions |
|||
|
|||
### Adding New Validation Rules |
|||
|
|||
Extend the guard script to check for: |
|||
|
|||
- Specific file content patterns |
|||
- Required documentation sections |
|||
- Commit message formats |
|||
- Branch naming conventions |
|||
|
|||
## 📚 **Integration with PR Template** |
|||
|
|||
The `pull_request_template.md` works with this system by: |
|||
|
|||
- **Guiding developers** through required documentation |
|||
- **Ensuring consistency** across all build changes |
|||
- **Providing checklist** for comprehensive updates |
|||
- **Supporting L1/L2/L3** change classification |
|||
|
|||
## 🎯 **Success Metrics** |
|||
|
|||
Track the effectiveness of your Build Architecture Guard: |
|||
|
|||
- **Hook execution rate** - How often hooks run successfully |
|||
- **Bypass frequency** - How often `--no-verify` is used |
|||
- **Documentation quality** - BUILDING.md stays current |
|||
- **Build failures** - Fewer issues from undocumented changes |
|||
- **Team adoption** - Developers follow the process |
|||
|
|||
--- |
|||
|
|||
**Status**: Active protection system |
|||
**Architecture**: Client-side Git hooks only |
|||
**Dependencies**: Husky, Git, Bash |
|||
**Maintainer**: Development team |
|||
**Related**: `pull_request_template.md`, `scripts/build-arch-guard.sh` |
|||
|
|||
## 📝 **Changelog** |
|||
|
|||
### 2025-08-22 - Shell Compatibility Fix |
|||
- **Fixed**: Replaced `mapfile` command with portable alternative for cross-shell compatibility |
|||
- **Impact**: Resolves "mapfile: command not found" errors in pre-commit hooks |
|||
- **Files**: `scripts/build-arch-guard.sh` |
|||
- **Testing**: Script now works across different shell environments |
@ -0,0 +1,238 @@ |
|||
# Android Asset Validation System |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-22 |
|||
**Status**: 🎯 **ACTIVE** - Production Ready |
|||
|
|||
## Overview |
|||
|
|||
The Android Asset Validation System automatically detects and fixes missing Android resources before building, preventing common build failures related to missing splash screens and app icons. |
|||
|
|||
## Problem Solved |
|||
|
|||
Previously, Android builds would fail with errors like: |
|||
``` |
|||
error: resource drawable/splash (aka app.timesafari.app:drawable/splash) not found. |
|||
error: resource mipmap/ic_launcher (aka app.timesafari.app:mipmap/ic_launcher) not found. |
|||
``` |
|||
|
|||
This happened when: |
|||
- Source assets existed but weren't generated into Android resources |
|||
- Android resource directories were missing |
|||
- Asset generation tools weren't run before building |
|||
|
|||
## Solution |
|||
|
|||
### Enhanced Build Script Validation |
|||
|
|||
The `scripts/build-android.sh` script now includes comprehensive asset validation that: |
|||
|
|||
1. **Checks Source Assets**: Validates that required source files exist in `resources/` |
|||
2. **Checks Android Resources**: Verifies that generated Android resources exist |
|||
3. **Auto-Regenerates**: Automatically regenerates missing resources when detected |
|||
4. **Verifies Results**: Confirms that regeneration was successful |
|||
|
|||
### Validation Process |
|||
|
|||
```bash |
|||
# Validates and regenerates if needed |
|||
npm run assets:validate:android |
|||
|
|||
# Full build with validation |
|||
npm run build:android:studio |
|||
``` |
|||
|
|||
### What Gets Validated |
|||
|
|||
#### Source Assets (Required) |
|||
- `resources/icon.png` - App icon source |
|||
- `resources/splash.png` - Splash screen source |
|||
- `resources/splash_dark.png` - Dark mode splash source |
|||
|
|||
#### Android Resources (Generated) |
|||
- `android/app/src/main/res/drawable/splash.png` - Splash screen drawable |
|||
- `android/app/src/main/res/mipmap-*/ic_launcher.png` - App icons for all densities |
|||
- `android/app/src/main/res/mipmap-*/ic_launcher_round.png` - Round app icons for all densities |
|||
|
|||
### Density Levels Checked |
|||
- `mipmap-mdpi` (1x) |
|||
- `mipmap-hdpi` (1.5x) |
|||
- `mipmap-xhdpi` (2x) |
|||
- `mipmap-xxhdpi` (3x) |
|||
- `mipmap-xxxhdpi` (4x) |
|||
|
|||
## Usage |
|||
|
|||
### Automatic Validation (Recommended) |
|||
The validation runs automatically during all Android builds: |
|||
|
|||
```bash |
|||
# Development build with validation |
|||
npm run build:android:studio |
|||
|
|||
# Production build with validation |
|||
npm run build:android:prod |
|||
|
|||
# Debug build with validation |
|||
npm run build:android:debug |
|||
``` |
|||
|
|||
### Manual Validation |
|||
Run validation only to check/fix assets: |
|||
|
|||
```bash |
|||
# Validate and regenerate if needed |
|||
npm run assets:validate:android |
|||
|
|||
# Alternative command |
|||
./scripts/build-android.sh --assets-only |
|||
``` |
|||
|
|||
### Validation Only (No Regeneration) |
|||
Check configuration without fixing: |
|||
|
|||
```bash |
|||
npm run assets:validate |
|||
``` |
|||
|
|||
## Error Handling |
|||
|
|||
### Missing Source Assets |
|||
If source assets are missing, the build fails with clear error messages: |
|||
|
|||
``` |
|||
[ERROR] Missing source assets: |
|||
[ERROR] - resources/icon.png |
|||
[ERROR] - resources/splash.png |
|||
[ERROR] Please ensure all required assets are present in the resources/ directory. |
|||
``` |
|||
|
|||
### Missing Generated Resources |
|||
If generated resources are missing, they're automatically regenerated: |
|||
|
|||
``` |
|||
[WARN] Missing Android resources detected: |
|||
[WARN] - drawable/splash.png |
|||
[WARN] - mipmap-mdpi/ic_launcher.png |
|||
[INFO] Regenerating Android assets... |
|||
[SUCCESS] Android assets regenerated successfully |
|||
``` |
|||
|
|||
### Generation Failure |
|||
If regeneration fails, helpful guidance is provided: |
|||
|
|||
``` |
|||
[ERROR] Failed to generate Android assets |
|||
[INFO] You may need to manually create the missing resources: |
|||
[INFO] - android/app/src/main/res/drawable/splash.png |
|||
[INFO] - android/app/src/main/res/mipmap-mdpi/ic_launcher.png |
|||
``` |
|||
|
|||
## Integration Points |
|||
|
|||
### Build Script Integration |
|||
The validation is integrated into the main build process: |
|||
|
|||
```bash |
|||
# In scripts/build-android.sh |
|||
validate_dependencies |
|||
validate_android_assets || { |
|||
log_error "Android asset validation failed. Please fix the issues above and try again." |
|||
exit 9 |
|||
} |
|||
``` |
|||
|
|||
### NPM Scripts |
|||
New npm scripts for asset management: |
|||
|
|||
```json |
|||
{ |
|||
"assets:validate": "npx tsx scripts/assets-validator.ts", |
|||
"assets:validate:android": "./scripts/build-android.sh --assets-only", |
|||
"assets:clean": "rimraf android/app/src/main/res/mipmap-* ios/App/App/Assets.xcassets/**/AppIcon*.png ios/App/App/Assets.xcassets/**/Splash*.png || true" |
|||
} |
|||
``` |
|||
|
|||
## Benefits |
|||
|
|||
### For Developers |
|||
- **No More Build Failures**: Automatic detection and fixing of missing resources |
|||
- **Faster Development**: No need to manually run asset generation tools |
|||
- **Clear Error Messages**: Helpful guidance when issues occur |
|||
- **Consistent Results**: Same validation on all development machines |
|||
|
|||
### For CI/CD |
|||
- **Reliable Builds**: Consistent asset validation across environments |
|||
- **Early Detection**: Catches issues before they reach production |
|||
- **Automated Fixes**: Self-healing builds when possible |
|||
|
|||
### For Project Maintenance |
|||
- **Reduced Support**: Fewer "build doesn't work" issues |
|||
- **Documentation**: Clear requirements for required assets |
|||
- **Standardization**: Consistent asset structure across the project |
|||
|
|||
## Troubleshooting |
|||
|
|||
### Common Issues |
|||
|
|||
#### "No assets found in the asset path" |
|||
This occurs when the `assets/` directory is empty. The validation system automatically copies source assets and regenerates them. |
|||
|
|||
#### "Failed to generate Android assets" |
|||
Check that: |
|||
- Source assets exist in `resources/` |
|||
- `@capacitor/assets` is installed |
|||
- You have write permissions to the Android directories |
|||
|
|||
#### "Asset generation completed but some resources are still missing" |
|||
This indicates a problem with the asset generation tool. Try: |
|||
1. Running `npm install` to ensure dependencies are up to date |
|||
2. Manually running `npx @capacitor/assets generate` |
|||
3. Checking the asset generation logs for specific errors |
|||
|
|||
### Manual Recovery |
|||
If automatic regeneration fails, you can manually create the missing resources: |
|||
|
|||
```bash |
|||
# Create missing directories |
|||
mkdir -p android/app/src/main/res/drawable |
|||
mkdir -p android/app/src/main/res/mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi} |
|||
|
|||
# Copy source assets to assets directory |
|||
cp resources/icon.png assets/ |
|||
cp resources/splash.png assets/ |
|||
cp resources/splash_dark.png assets/ |
|||
|
|||
# Generate assets manually |
|||
npx @capacitor/assets generate |
|||
|
|||
# Clean up |
|||
rm assets/icon.png assets/splash.png assets/splash_dark.png |
|||
``` |
|||
|
|||
## Future Enhancements |
|||
|
|||
### Planned Improvements |
|||
- **iOS Asset Validation**: Extend validation to iOS assets |
|||
- **Asset Quality Checks**: Validate image dimensions and formats |
|||
- **Performance Optimization**: Cache validation results |
|||
- **CI/CD Integration**: Add validation to GitHub Actions |
|||
|
|||
### Configuration Options |
|||
- **Custom Asset Paths**: Support for different asset directory structures |
|||
- **Validation Rules**: Configurable validation requirements |
|||
- **Skip Options**: Ability to skip validation for specific scenarios |
|||
|
|||
## References |
|||
|
|||
- [Capacitor Assets Documentation](https://github.com/ionic-team/capacitor-assets) |
|||
- [Android Resource System](https://developer.android.com/guide/topics/resources/providing-resources) |
|||
- [Build Script Documentation](./build-android.sh) |
|||
- [Asset Configuration](./capacitor-assets.config.json) |
|||
|
|||
--- |
|||
|
|||
**Status**: Active validation system |
|||
**Priority**: High |
|||
**Maintainer**: Development team |
|||
**Next Review**: 2025-09-22 |
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue