Skip to content

Commit 87d2fbe

Browse files
EmiD-10EmiD-10
committed
feat: divide AGEND.md into skills
1 parent ec99621 commit 87d2fbe

14 files changed

Lines changed: 1004 additions & 280 deletions

File tree

‎.ai/skills/README.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Agent Skills for ADAMANT iOS
2+
3+
This directory contains [Agent Skills](https://agentskills.io) — modular, reusable expertise that AI agents can discover and use.
4+
5+
## Available Skills
6+
7+
### [ios-architecture](ios-architecture/)
8+
9+
Expert knowledge of ADAMANT iOS app architecture, modules, runtime flow, and system organization.
10+
11+
**Use when:**
12+
13+
- Exploring codebase structure
14+
- Understanding dependencies and data flow
15+
- Planning architectural changes
16+
- Working with DI container
17+
- Understanding wallet or messaging pipeline
18+
19+
### [github-workflow](github-workflow/)
20+
21+
GitHub workflow conventions for issues, labels, and PRs following ADAMANT org standards.
22+
23+
**Use when:**
24+
25+
- Creating issues or PRs
26+
- Selecting appropriate labels
27+
- Formatting titles and descriptions
28+
- Understanding org governance
29+
30+
### [testing-validation](testing-validation/)
31+
32+
Testing requirements and validation procedures for ensuring code quality.
33+
34+
**Use when:**
35+
36+
- Writing tests
37+
- Validating changes before commit
38+
- Setting up CI/CD
39+
- Investigating test failures
40+
41+
### [code-style](code-style/)
42+
43+
iOS platform rules, Swift conventions, dependency injection patterns, and code quality standards.
44+
45+
**Use when:**
46+
47+
- Writing new code
48+
- Reviewing code for style compliance
49+
- Refactoring existing code
50+
- Working with Core Data or DI
51+
52+
### [documentation](documentation/)
53+
54+
Documentation standards, writing style, markdown conventions, and sources of truth.
55+
56+
**Use when:**
57+
58+
- Writing or updating documentation
59+
- Formatting markdown files
60+
- Resolving documentation conflicts
61+
- Understanding documentation sources
62+
63+
## Skill Structure
64+
65+
Each skill follows the [Agent Skills specification](https://agentskills.io/specification):
66+
67+
```
68+
skill-name/
69+
├── SKILL.md # Metadata + instructions (required)
70+
├── references/ # Additional documentation
71+
├── scripts/ # Executable code
72+
└── assets/ # Templates, resources
73+
```
74+
75+
## Using Skills
76+
77+
AI agents should automatically discover and activate relevant skills based on the task context. Skills are designed for progressive disclosure:
78+
79+
1. **Metadata** — Name and description loaded at startup
80+
2. **Instructions** — Full SKILL.md loaded when activated
81+
3. **Resources** — Referenced files loaded as needed
82+
83+
## Contributing
84+
85+
When adding or updating skills:
86+
87+
- Follow the [Agent Skills specification](https://agentskills.io/specification)
88+
- Keep SKILL.md focused (< 500 lines recommended)
89+
- Move detailed content to reference files
90+
- Include clear "When to Use" guidance
91+
- Test with the reference validator: `skills-ref validate ./skill-name`

‎.ai/skills/code-style/SKILL.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
name: code-style
3+
description: iOS platform rules, Swift conventions, dependency injection patterns, and code quality standards for ADAMANT iOS. Use when writing or reviewing code.
4+
license: Apache-2.0
5+
compatibility: Swift 5.9+, iOS 15.0+, UIKit, Swinject
6+
metadata:
7+
project: adamant-ios
8+
domain: code-quality
9+
---
10+
11+
# Code Style and Quality
12+
13+
Code style conventions, platform rules, and quality standards for ADAMANT iOS.
14+
15+
## iOS Platform and Swift Rules
16+
17+
- **Target iOS 15.0+** as specified in `Podfile` and package manifests
18+
- **Use Swift 5.9+** language features as appropriate
19+
- **Follow UIKit patterns**; this is not a SwiftUI project
20+
- **Respect iOS lifecycle events** and state restoration
21+
- **Handle memory warnings and background transitions** properly
22+
- **Use `@MainActor`** or `DispatchQueue.main.async` for UI updates from background threads
23+
- **Avoid force unwrapping (`!`)** except in truly safe scenarios; prefer optional binding or guard statements
24+
- **Use Swift's type safety and value semantics** where appropriate
25+
26+
## Dependency Injection Rules
27+
28+
- **All services must be registered** in appropriate assembly files (`Adamant/App/DI/*`, module-specific assemblies)
29+
- **Use protocol-based abstractions** defined in `Adamant/ServiceProtocols/`
30+
- **Follow Swinject container patterns** already established in the codebase
31+
- **Prefer constructor injection** over property injection
32+
- **Use `.inObjectScope(.container)`** for singleton services
33+
- **Do not create service instances directly**; resolve them through the DI container
34+
35+
## Code Style and Quality Rules
36+
37+
- **Follow existing code style and patterns** in the repository
38+
- **SwiftLint is configured** but many rules are disabled (see `.swiftlint.yml`); follow the enabled rules strictly
39+
- **SwiftFormat configuration exists** (`.swiftformat`); use it for consistent formatting
40+
- **Prefer clarity over cleverness**
41+
- **Write self-documenting code**; add comments only when necessary to explain "why" not "what"
42+
- **Keep functions focused and reasonably sized**
43+
- **Avoid massive view controllers**; extract logic to services, view models, or coordinators
44+
- **Use extensions** to organize code by protocol conformance or functionality
45+
- **Follow Swift naming conventions**: clear, descriptive names without unnecessary abbreviations
46+
47+
## Protocol and Compatibility Rules
48+
49+
- **Keep transaction bytes, signing behavior, and verification** compatible with ADAMANT network expectations unless a coordinated protocol update is planned
50+
- **For protocol-impacting changes**, align with AIPs and update related docs/spec references
51+
- **Maintain backward compatibility** with existing user data and Core Data models
52+
- **Use Core Data migrations properly** when schema changes are required
53+
- **Test migration paths** from previous app versions
54+
55+
## Change Discipline
56+
57+
- **Prefer focused patches** with explicit rationale
58+
- **Preserve backward compatibility** for user data and persisted state where possible
59+
- **When touching legacy code**, improve locally without broad unrelated rewrites
60+
- **Add or update tests** near the changed behavior
61+
- **Update localization strings** when adding new user-facing text
62+
- **Update all supported languages** or mark missing translations with English fallback
63+
64+
## UX Rules for Security-Critical Flows
65+
66+
- **Keep onboarding fast**, but do not hide irreversible risk
67+
- **Preserve clear passphrase responsibility warnings**; never imply recoverability when none exists
68+
- **Keep transaction confirmations explicit and informative**
69+
- **Avoid introducing friction** that does not improve security or safety
70+
- **Provide clear feedback** for all user actions
71+
- **Handle loading states and network delays** with appropriate UI indicators
72+
- **Maintain accessibility support** (VoiceOver, Dynamic Type, etc.)
73+
74+
## When to Use This Skill
75+
76+
Activate this skill when:
77+
78+
- Writing new code
79+
- Reviewing code for style compliance
80+
- Refactoring existing code
81+
- Setting up DI registrations
82+
- Working with Core Data models
83+
- Making UI changes
84+
85+
## See Also
86+
87+
- [Swift Rules](references/SWIFT-RULES.md) for detailed Swift conventions
88+
- [DI Patterns](references/DI-PATTERNS.md) for dependency injection examples

‎.ai/skills/code-style/references/DI-PATTERNS.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Dependency Injection Patterns
2+
3+
Swinject DI patterns used in ADAMANT iOS.
4+
5+
## Service Registration
6+
7+
Services are registered in assembly files:
8+
9+
```swift
10+
// In Adamant/App/DI/SomeAssembly.swift
11+
final class SomeAssembly: Assembly {
12+
func assemble(container: Container) {
13+
// Register service
14+
container.register(MyServiceProtocol.self) { r in
15+
MyService(
16+
dependency1: r.resolve(Dependency1Protocol.self)!,
17+
dependency2: r.resolve(Dependency2Protocol.self)!
18+
)
19+
}.inObjectScope(.container) // Singleton
20+
}
21+
}
22+
```
23+
24+
## Service Resolution
25+
26+
Services are resolved through the container:
27+
28+
```swift
29+
// In view controller or coordinator
30+
final class MyViewController: UIViewController {
31+
// MARK: - Dependencies
32+
private let myService: MyServiceProtocol
33+
34+
// MARK: - Init
35+
init(myService: MyServiceProtocol) {
36+
self.myService = myService
37+
super.init(nibName: nil, bundle: nil)
38+
}
39+
}
40+
41+
// In factory or coordinator
42+
let myService = container.resolve(MyServiceProtocol.self)!
43+
let viewController = MyViewController(myService: myService)
44+
```
45+
46+
## Protocol-Based Abstractions
47+
48+
All services have protocol definitions:
49+
50+
```swift
51+
// In Adamant/ServiceProtocols/MyServiceProtocol.swift
52+
protocol MyServiceProtocol {
53+
func performOperation() async throws -> Result
54+
}
55+
56+
// In Adamant/Services/MyService.swift
57+
final class MyService: MyServiceProtocol {
58+
// Implementation
59+
}
60+
```
61+
62+
## Scope Management
63+
64+
Use appropriate object scopes:
65+
66+
- `.container` — Singleton (shared instance)
67+
- `.transient` — New instance each time (default)
68+
- `.weak` — Weak reference to shared instance
69+
70+
```swift
71+
// Singleton service
72+
container.register(ApiService.self) { r in
73+
ApiServiceImpl()
74+
}.inObjectScope(.container)
75+
76+
// Transient (new instance)
77+
container.register(ViewModel.self) { r in
78+
ViewModelImpl()
79+
}
80+
```
81+
82+
## Circular Dependencies
83+
84+
Avoid circular dependencies. If needed, use property injection:
85+
86+
```swift
87+
container.register(ServiceA.self) { r in
88+
let service = ServiceAImpl()
89+
service.serviceB = r.resolve(ServiceB.self)
90+
return service
91+
}.inObjectScope(.container)
92+
```
93+
94+
## Assembly Organization
95+
96+
- `AppAssembly.swift` — Main app assembly
97+
- Module-specific assemblies for feature modules
98+
- Each assembly focuses on related services

‎.ai/skills/code-style/references/SWIFT-RULES.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Swift Rules
2+
3+
Detailed Swift conventions for ADAMANT iOS.
4+
5+
## Optionals
6+
7+
- Use optional binding or guard statements instead of force unwrapping
8+
- Prefer `if let` for single optional unwrapping
9+
- Prefer `guard let` when early return is needed
10+
11+
```swift
12+
// Good
13+
guard let value = optionalValue else { return }
14+
15+
// Good
16+
if let value = optionalValue {
17+
// use value
18+
}
19+
20+
// Avoid
21+
let value = optionalValue!
22+
```
23+
24+
## Error Handling
25+
26+
- Use proper error handling; avoid generic catch-all error handlers
27+
- Provide meaningful error messages
28+
- Don't silently swallow errors
29+
30+
```swift
31+
// Good
32+
do {
33+
try riskyOperation()
34+
} catch let error as SpecificError {
35+
log.error("Operation failed: \(error.localizedDescription)")
36+
// Handle specific error
37+
} catch {
38+
log.error("Unexpected error: \(error)")
39+
// Handle general error
40+
}
41+
42+
// Avoid
43+
do {
44+
try riskyOperation()
45+
} catch {
46+
// Silent failure
47+
}
48+
```
49+
50+
## Threading
51+
52+
- Use `@MainActor` for UI updates
53+
- Use `DispatchQueue.main.async` when needed
54+
- Be explicit about threading requirements
55+
56+
```swift
57+
// Good
58+
@MainActor
59+
func updateUI() {
60+
label.text = "Updated"
61+
}
62+
63+
// Good
64+
DispatchQueue.main.async {
65+
self.updateUI()
66+
}
67+
```
68+
69+
## Memory Management
70+
71+
- Use `[weak self]` in closures when appropriate
72+
- Avoid retain cycles in delegates (use `weak` references)
73+
- Be mindful of memory warnings
74+
75+
```swift
76+
// Good
77+
service.fetchData { [weak self] result in
78+
guard let self = self else { return }
79+
// use self safely
80+
}
81+
```
82+
83+
## Naming Conventions
84+
85+
- Use clear, descriptive names
86+
- Avoid unnecessary abbreviations
87+
- Follow Swift API Design Guidelines
88+
89+
```swift
90+
// Good
91+
func fetchUserProfile(for userId: String)
92+
var isAuthenticated: Bool
93+
94+
// Avoid
95+
func fetUsrProf(for id: String)
96+
var authd: Bool
97+
```
98+
99+
## Extensions
100+
101+
- Use extensions to organize code by protocol conformance
102+
- Group related functionality in extensions
103+
- Add MARK comments for clarity
104+
105+
```swift
106+
// MARK: - UITableViewDataSource
107+
extension MyViewController: UITableViewDataSource {
108+
// table view data source methods
109+
}
110+
111+
// MARK: - Private Methods
112+
private extension MyViewController {
113+
// private helper methods
114+
}
115+
```

0 commit comments

Comments
 (0)