Imported from ethanx40/wallpaper (AGENTS.md). Install upstream with npx skills add ethanx40/wallpaper. Copyright stays with the author.

OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open @/openspec/AGENTS.md when the request:

• Mentions planning or proposals (words like proposal, spec, change, plan)
• Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
• Sounds ambiguous and you need the authoritative spec before coding

Use @/openspec/AGENTS.md to learn:

• How to create and apply change proposals
• Spec format and conventions
• Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

Project Instructions for AI Assistants

Build, Lint, Test Commands

# Build
cd WallpaperApp && swift build              # Build the project
cd WallpaperApp && swift run                # Build and run the app

# Testing
swift test                                  # Run all tests
swift test --filter "WallpaperTests"        # Run specific test class
swift test --filter "testWallpaperInitialization"  # Run specific test method
swift test --filter "WallpaperAppTests.WallpaperTests/testWallpaperInitialization"  # Fully qualified test name

# Development
swift test list                             # List all available tests

# OpenSpec commands (run from project root)
openspec list              # List active changes
openspec list --specs      # List specifications
openspec show [item]       # Display change or spec details
openspec validate [item]   # Validate changes or specs
openspec archive <id> [-y] # Archive completed changes
openspec init [path]       # Initialize OpenSpec in new directory
openspec update [path]     # Update instruction files

Code Style Guidelines

General Principles

• Follow existing patterns before introducing new ones
• Use descriptive names that reveal intent
• Keep functions small and focused (<50 lines when possible)
• Prefer explicit over implicit
• Write code that reads like prose

Naming Conventions

• camelCase for variables, functions, properties
• PascalCase for types (structs, classes, enums, protocols)
• Prefix protocols with descriptive naming (e.g., WallpaperDataSource)
• Use private or private(set) for internal implementation details
• Private helper functions should start with lowercase

Type Safety

• Use explicit types for function parameters when not obvious
• Leverage Swift's type inference for simple cases
• Use any for protocol existential types when needed
• Define structs for value types, classes for reference types with identity
• Use actors for concurrent data access

Async/Concurrency

• Use async/await over completion handlers
• Mark actors with actor keyword for thread-safe data access
• Use @MainActor for UI code and ViewModels
• Prefer Task { } for fire-and-forget async operations

Error Handling

• Never use empty catch blocks
• Define custom error types conforming to LocalizedError or Error
• Provide meaningful error descriptions and recovery suggestions
• Use try/await for async throwing functions
• Handle expected errors gracefully
• Fail fast and loud on unexpected errors

Property Wrappers

• Use @Published for ObservableObject properties that trigger UI updates
• Use @State for SwiftUI view-local state
• Use @MainActor for ViewModels and UI-related classes
• Use dependency injection via initializers instead of global state

Import Organization

• Group imports: standard library → third-party → project modules
• Sort imports alphabetically within groups
• Remove unused imports
• Place imports at top of file, before other statements

SwiftUI Patterns

• Use struct for Views conforming to View
• Extract reusable components into separate View structs
• Use modifiers at end of view builder chains
• Prefer @ViewBuilder for complex view composition

Comment Guidelines

• Comment why, not what (code already says what)
• Use /// documentation comments for public APIs
• Mark TODOs with actionable items
• Remove outdated comments
• Use Chinese comments for user-facing strings per project convention

Project Structure

.
├── AGENTS.md                # This file - AI assistant instructions
├── WallpaperApp/           # Main Swift package
│   ├── Package.swift       # Swift package configuration
│   ├── Sources/
│   │   ├── App/           # App entry point and AppDelegate
│   │   ├── Core/
│   │   │   ├── Domain/    # Models, protocols, errors
│   │   │   ├── Data/      # Repositories, data sources, services
│   │   │   └── Presentation/ # ViewModels, Views
│   │   └── Assets.xcassets
│   └── Tests/              # XCTest test suites
├── openspec/
│   ├── AGENTS.md           # OpenSpec workflow instructions
│   ├── project.md          # Project context and conventions
│   ├── specs/              # Current truth - what IS built
│   │   └── [capability]/
│   │       ├── spec.md     # Requirements and scenarios
│   │       └── design.md   # Technical patterns
│   └── changes/            # Proposals - what SHOULD change
│       ├── [change-id]/
│       │   ├── proposal.md # Why, what, impact
│       │   ├── tasks.md    # Implementation checklist
│       │   ├── design.md   # Technical decisions (optional)
│       │   └── specs/      # Delta changes
│       └── archive/        # Completed changes
└── .opencode/              # OpenSpec tooling

OpenSpec Workflow

When to Create a Proposal

• New features or functionality
• Breaking changes (API, schema)
• Architecture or pattern changes
• Performance optimizations (behavior-changing)
• Security pattern updates

When to Skip Proposal

• Bug fixes (restore intended behavior)
• Typos, formatting, comments
• Non-breaking dependency updates
• Configuration changes
• Tests for existing behavior

Implementation Checklist

Before starting implementation:

• Read proposal.md to understand what's being built
• Read design.md (if exists) for technical decisions
• Read tasks.md for implementation checklist
• Read relevant specs/ files to understand current state
• Verify proposal is approved before coding

After completing work:

• All tasks.md items are complete
• All tests pass
• Linting passes
• Changes are validated: openspec validate <id> --strict

Getting Started

1. Understand the project: Read openspec/project.md for context
2. Check existing work: Run openspec list and openspec list --specs
3. Start with small changes: Follow OpenSpec workflow for features
4. Ask questions: If anything is unclear, ask before assuming

Important Notes

• This project is in early development - conventions will evolve
• Always consult OpenSpec instructions for spec-driven development
• Use openspec validate --strict before submitting changes
• Keep documentation up to date as the codebase grows