From cc8e84ff0b5aefd0d8b1d43cd1f71a9a97bcde21 Mon Sep 17 00:00:00 2001 From: Isaac Connor Date: Thu, 8 Jan 2026 17:48:16 -0500 Subject: [PATCH] Rough in a quick AGENTS.md cutnpasted from @pliablepixel's zmNg --- AGENTS.md | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..197793574 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,169 @@ +# Development Guidelines + +## Quick Reference +1. **Feature Workflow**: New features → Create GH issue → Feature branch → Implement fully → Get approval → Merge to master +2. **Internationalization**: Update ALL language files (en, de, es, fr, zh + any future) +3. **Testing**: MANDATORY - Write tests first, run AND verify pass before commit +4. **Coding**: DRY principles, keep code files small and modular + +--- + +## Testing (MANDATORY - No Exceptions) + +### Test-First Development Workflow + +**Rule**: Write tests BEFORE or DURING implementation, NEVER skip tests. + +**Why**: Tests written "later" are usually never written. Tests verify code actually works. + +**Workflow**: +1. Understand the bug/feature requirement +2. Write a failing test that reproduces the issue or validates the feature +3. Implement the fix/feature +4. Run tests - verify they now PASS +5. Run full test suite to check for regressions +6. Only then commit + +### Unit Tests (REQUIRED - No Exceptions) + +**When**: For ALL code changes - no matter how small +- ✅ New functionality → Write new tests FIRST +- ✅ Bug fixes → Write test that reproduces bug FIRST +- ✅ Refactoring → Ensure existing tests still pass +- ✅ Changes to existing functionality → Update tests BEFORE changing code +- ✅ New components → Write tests as you build +- ✅ Store changes → Update store tests +- ✅ Utility functions → Test all logic paths + +**What to Test**: +- Happy path (normal usage) +- Edge cases (empty arrays, null values, undefined, boundary conditions) +- Error cases (network failures, invalid input, missing data) +- State changes (verify before/after behavior) + +**Location**: Next to source in `tests/` subdirectory + +## Feature Development Workflow (MANDATORY) + +**When the user requests a new feature, follow this workflow:** + +### 1. Create GitHub Issue +- Create a GitHub issue for the feature request using `gh issue create` +- Label it as `enhancement` +- Include clear description of what the feature should do +- Example: + ```bash + gh issue create --title "Add event favorites feature" \ + --body "Allow users to mark events as favorites and filter by favorites" \ + --label "enhancement" + ``` + +### 2. Create Feature Branch +- Create a new branch from master with descriptive name +- Branch naming: `feature/` or `feat/-` +- Example: + ```bash + git checkout -b feature/event-favorites + ``` + +### 3. Implement Feature Completely +- **CRITICAL:** Implement the ENTIRE feature - do not stop in the middle +- Follow all testing requirements (unit tests, E2E tests, type check, build) +- Commit work in logical chunks with descriptive messages +- Reference the issue in commit messages: `refs #` +- Make multiple commits if the feature has multiple logical components + +### 4. Request User Feedback +- Once implementation is complete and all tests pass, ask user for feedback +- DO NOT merge or push without user approval +- Example: "Feature implementation complete. All tests passing. Ready for your review." + +### 5. Merge and Cleanup (After User Approval Only) +- Merge feature branch to master +- Delete the feature branch (local and remote) +- Reference the issue in final commit/merge: `fixes #` +- Push to master +- Verify issue is automatically closed (due to `fixes #`) + +**Example Complete Workflow:** +```bash +# 1. Create issue +gh issue create --title "Add dark mode toggle" --body "..." --label "enhancement" +# Note the issue number (e.g., #42) + +# 2. Create branch +git checkout -b feature/dark-mode + +# 3. Implement + test + commit +git add +git commit -m "feat: add dark mode toggle component refs #42" +# ... more commits as needed + +# 4. Ask user for approval +# (Wait for user confirmation) + +# 5. After approval, merge and cleanup +git checkout master +git merge feature/dark-mode +git push origin master +git branch -d feature/dark-mode +git push origin --delete feature/dark-mode +# Verify issue #42 is closed +``` + +**Important Notes:** +- Never merge to master without user approval +- Never leave a feature half-implemented +- Always include tests before requesting approval +- Feature branches keep master stable and allow for review + +--- + +## Commits + +- Commit messages must be detailed and descriptive (no vague summaries) +- Split unrelated changes into separate commits (one logical change per commit) +- Avoid superlative language (no "comprehensive", "critical", "major", "massive", etc.) +- Keep commit messages factual and objective +- **Use conventional commit format:** + - `feat:` - New feature + - `fix:` - Bug fix + - `docs:` - Documentation + - `test:` - Tests + - `chore:` - Maintenance + - `refactor:` - Code restructuring +- When you commit code, and the code contains multiple things, break each item into separate commits + +**Examples:** +- ✅ Good: `fix: resolve overflow issue in flex containers` +- ✅ Good: `feat: add haptic feedback to buttons` +- ❌ Bad: `fix: comprehensive overflow handling improvements` +- ❌ Bad: `feat: critical haptic feedback system` + + + + +## Issue handling +- When Github issues are created, make sure code fixes refer to that issue in commit messages +- Use `refs #` for references and `fixes #` when the commit should close the issue +- When working in github issues, make changes, validate tests and then ask me to test before pushing code to github + +--- + +## Pre-Commit Checklist + +### ALL Changes (MANDATORY - No Exceptions) +- [ ] Tests written/updated BEFORE or DURING implementation + +### Before Stating "Done" or Committing +- [ ] ALL applicable tests have been run (not just build) +- [ ] ALL tests PASS (not just "no errors") +- [ ] State which tests were run and passed + +### Never Commit or Claim Complete If +- ❌ Tests are failing +- ❌ Tests don't exist for new/changed functionality +- ❌ You haven't actually run the tests +- ❌ Build fails +- ❌ You only ran build but not unit/e2e tests +