Skip to content

Commit 099f75e

Browse files
rprabhatrprabhat
committed
chore: add agent-skills workflow documentation
1 parent 902d5fe commit 099f75e

1 file changed

Lines changed: 128 additions & 128 deletions

File tree

‎AGENTS.md‎

Lines changed: 128 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -1,147 +1,147 @@
1-
# CardSnap - Agent Guidelines
1+
# Agent Instructions - Auto-Merge Workflow
22

3-
This file provides instructions for AI agents operating in this repository. It covers project setup, development workflows, code style, and best practices.
3+
## 📋 Available Skills
44

5-
## 🔴 CRITICAL: Sensible Analytics Workflow
5+
This repository has access to production-grade engineering skills from addyosmani/agent-skills. These skills are automatically loaded from `~/.config/opencode/skills/`.
66

7-
- ❌ NEVER push to main/master
8-
- ❌ NEVER commit directly
9-
- ✅ ALWAYS create feature branch (`feat/`, `fix/`, `refactor/`, `docs/`)
10-
- ✅ ALWAYS use PR workflow
11-
- ✅ Target PR size: < 200 lines changed
12-
- ✅ Include AI Disclosure in PRs
7+
### Intent → Skill Mapping
138

14-
## 📋 Project Overview
9+
The agent should automatically map user intent to skills:
1510

16-
CardSnap (CardSnap) is a **native Kotlin Android application** for scanning business cards using OCR technology.
11+
| Task Type | Skills to Use |
12+
|-----------|---------------|
13+
| New feature / functionality | `spec-driven-development` → `planning-and-task-breakdown` → `incremental-implementation` + `test-driven-development` |
14+
| Planning / breakdown | `planning-and-task-breakdown` |
15+
| Bug / failure / unexpected behavior | `debugging-and-error-recovery` |
16+
| Code review | `code-review-and-quality` |
17+
| Refactoring / simplification | `code-simplification` |
18+
| API or interface design | `api-and-interface-design` |
19+
| UI work | `frontend-ui-engineering` |
20+
| Security sensitive code | `security-and-hardening` |
21+
| Performance requirements | `performance-optimization` |
22+
| Git/Version control | `git-workflow-and-versioning` |
23+
| CI/CD setup | `ci-cd-and-automation` |
24+
| Deploy to production | `shipping-and-launch` |
25+
| Documentation | `documentation-and-adrs` |
1726

18-
### Tech Stack
19-
- **Kotlin 1.9.22** with Coroutines + Flow
20-
- **Jetpack Compose** (Material 3)
21-
- **CameraX** for camera functionality
22-
- **ML Kit Text Recognition** for OCR
23-
- **Room Database** for persistent storage
24-
- **DataStore Preferences** for app settings
25-
- **Espresso + Compose Testing** for E2E testing
26-
- **JUnit 5** for unit testing
27+
### Development Lifecycle Mapping
2728

28-
### Build Configuration
29-
- **AGP**: 8.6.0
30-
- **Gradle**: 8.8
31-
- **compileSdk**: 35, **minSdk**: 26, **targetSdk**: 34
32-
- **KSP**: 1.9.22-1.0.17
29+
- **DEFINE** → `spec-driven-development`, `idea-refine`
30+
- **PLAN** → `planning-and-task-breakdown`
31+
- **BUILD** → `incremental-implementation`, `test-driven-development`, `context-engineering`, `frontend-ui-engineering`, `api-and-interface-design`
32+
- **VERIFY** → `debugging-and-error-recovery`, `browser-testing-with-devtools`
33+
- **REVIEW** → `code-review-and-quality`, `code-simplification`, `security-and-hardening`, `performance-optimization`
34+
- **SHIP** → `git-workflow-and-versioning`, `ci-cd-and-automation`, `deprecation-and-migration`, `documentation-and-adrs`, `shipping-and-launch`
3335

34-
## 🛠️ Development Commands
36+
### Core Rules
3537

36-
### Building
37-
```bash
38-
cd android
39-
# Build debug APK
40-
./gradlew assembleDebug
38+
- If a task matches a skill, you MUST invoke it using the `skill` tool
39+
- Skills are located in `~/.config/opencode/skills/<skill-name>/SKILL.md`
40+
- Never implement directly if a skill applies
41+
- Always follow the skill instructions exactly (do not partially apply them)
42+
- Verification is non-negotiable - always provide evidence (tests passing, build output, etc.)
4143

42-
# Build test APK
43-
./gradlew assembleDebugAndroidTest
44+
### Anti-Rationalization
4445

45-
# Run unit tests
46-
./gradlew testDebugUnitTest
46+
The following thoughts are incorrect and must be ignored:
47+
- "This is too small for a skill"
48+
- "I can just quickly implement this"
49+
- "I will gather context first"
4750

48-
# Run E2E tests (requires running emulator)
49-
./gradlew connectedAndroidTest
50-
```
51+
Correct behavior: Always check for and use skills first.
52+
53+
## ⚠️ IMPORTANT: This repository has branch protection enabled
54+
55+
Direct pushes to `main`/`master` are **BLOCKED**. All changes must go through Pull Requests.
56+
57+
## 🚀 Automated GitHub Flow
58+
59+
Once you push and open a PR:
60+
1. CI runs automatically
61+
2. GitHub auto-merges when CI passes
62+
3. GitHub auto-deletes the branch
63+
64+
**You never need to manually approve or merge your own PRs.**
65+
66+
## Required Workflow
67+
68+
### Making Changes
69+
70+
1. **Create a feature branch** (never work on main/master):
71+
```bash
72+
git checkout -b feat/your-feature-name
73+
# or
74+
git checkout -b fix/issue-description
75+
```
76+
77+
2. **Make your changes and commit**:
78+
```bash
79+
git add .
80+
git commit -m "feat: descriptive commit message"
81+
```
82+
83+
3. **Push the branch**:
84+
```bash
85+
git push origin feat/your-feature-name
86+
```
87+
88+
4. **Create a Pull Request** with auto-merge enabled:
89+
```bash
90+
gh pr create --title "feat: Add new feature" --body "Description of changes" --auto
91+
```
5192

52-
### Linting
93+
Or enable auto-merge after creating:
94+
```bash
95+
gh pr merge --auto --squash --delete-branch
96+
```
97+
98+
### Branch Naming Conventions
99+
100+
- `feat/` - New features
101+
- `fix/` - Bug fixes
102+
- `docs/` - Documentation changes
103+
- `refactor/` - Code refactoring
104+
- `test/` - Test additions/changes
105+
- `chore/` - Maintenance tasks
106+
107+
### What You MUST NOT Do
108+
109+
- ❌ Never push directly to `main` or `master`
110+
- ❌ Never use `git push --force` on protected branches
111+
- ❌ Never delete the `main` or `master` branch
112+
- ❌ Never commit directly without a PR
113+
114+
### Git Configuration
115+
116+
When working with this repository, ensure your git config includes:
53117
```bash
54-
cd android
55-
./gradlew lint
118+
git config user.name "Your Name"
119+
git config user.email "your.email@example.com"
56120
```
57121

58-
## 📁 Project Structure
122+
## Security Considerations
59123

60-
```
61-
CardSnap/
62-
├── android/
63-
│ ├── app/
64-
│ │ ├── src/
65-
│ │ │ ├── main/java/com/cardsnap/
66-
│ │ │ │ ├── data/ # Room DB, DAO, Repositories
67-
│ │ │ │ ├── domain/ # Models, OCR, Parser
68-
│ │ │ │ ├── ui/ # Screens, Navigation, Theme
69-
│ │ │ │ ├── util/ # Utilities
70-
│ │ │ │ └── MainActivity.kt
71-
│ │ │ ├── androidTest/ # Espresso E2E tests
72-
│ │ │ └── test/ # JUnit unit tests
73-
│ │ └── build.gradle.kts
74-
│ ├── build.gradle.kts
75-
│ ├── settings.gradle.kts
76-
│ └── gradle.properties
77-
├── docs/
78-
└── assets/
124+
- No force pushes allowed
125+
- Branch deletion is prevented
126+
- CI checks must pass before merge (enforced by auto-merge)
127+
128+
## Quick Reference
129+
130+
```bash
131+
# Start new work
132+
git checkout -b feat/new-feature
133+
134+
# After making changes
135+
git add . && git commit -m "feat: add new feature"
136+
git push origin feat/new-feature
137+
138+
# Create PR with auto-merge
139+
gh pr create --title "feat: Add new feature" --body "What it does" --auto
140+
141+
# Or enable auto-merge after creating PR
142+
gh pr merge --auto --squash --delete-branch
143+
144+
# Back to main
145+
git checkout main && git pull
79146
```
80147

81-
## 🎨 Code Style Guidelines
82-
83-
### Kotlin Conventions
84-
- Use `val` by default, `var` only when necessary
85-
- Prefer expression bodies for simple functions
86-
- Use data classes for models
87-
- Use sealed classes/interfaces for state
88-
- Follow Android Kotlin style guide
89-
- Use coroutines for async operations
90-
- Use Flow for reactive streams
91-
92-
### Compose Conventions
93-
- Keep composables small and focused
94-
- Use `@Composable` functions for UI only
95-
- Move business logic to ViewModels
96-
- Use `remember` and `collectAsState()` appropriately
97-
- Use `Modifier.testTag()` for E2E test identifiers
98-
99-
### Architecture
100-
- **MVVM pattern**: ViewModel + StateFlow + Compose
101-
- **Repository pattern**: Data access through repositories
102-
- **Single Activity**: MainActivity hosts NavHost
103-
- **Dependency Injection**: Manual DI (no Hilt/Dagger)
104-
105-
## 🧪 Testing Standards
106-
107-
### Unit Tests (JUnit)
108-
- Location: `android/app/src/test/`
109-
- Run: `./gradlew testDebugUnitTest`
110-
- Test domain logic, parsers, utilities
111-
112-
### E2E Tests (Espresso + Compose Testing)
113-
- Location: `android/app/src/androidTest/`
114-
- Run: `./gradlew connectedAndroidTest`
115-
- Requires running Android emulator
116-
- Use `createAndroidComposeRule<MainActivity>()`
117-
- Use `Modifier.testTag()` for component identification
118-
119-
## 🔐 Security
120-
- NO API keys in code
121-
- Use Android Keystore for sensitive data
122-
- Run lint before commit
123-
- Write tests for new features
124-
125-
## 📋 PR Requirements
126-
127-
Every PR MUST include:
128-
- [ ] Summary (what + why)
129-
- [ ] Changes (detailed list)
130-
- [ ] Testing (how to verify)
131-
- [ ] AI Disclosure (AI-Generated: Yes/No, Model, Platform)
132-
- [ ] No debug code (Log.d, TODO, FIXME)
133-
- [ ] No secrets
134-
- [ ] Lint passes
135-
136-
---
137-
138-
## 📄 Governance Documents
139-
140-
- [Privacy Policy](docs/PRIVACY_POLICY.md)
141-
- [Security Policy](docs/SECURITY.md)
142-
- [Code of Conduct](docs/CODE_OF_CONDUCT.md)
143-
144-
---
145-
146-
*Last updated: 2026-04-06*
147-
*Migration: React Native → Native Kotlin Android*

0 commit comments

Comments
 (0)