docs: restructure commands and add coding guidelines

docs/commands/README.md

@@ -0,0 +1,53 @@
+# Cursor User Commands
+
+This folder contains shared Cursor IDE user commands for the team. These commands help standardize our AI-assisted development workflow.
+
+## Setup
+
+To use these commands, copy them to your local Cursor commands folder:
+
+```bash
+# macOS/Linux
+cp docs/commands/*.md ~/.cursor/commands/
+
+# Or create symlinks to stay in sync
+ln -sf "$(pwd)/docs/commands/"*.md ~/.cursor/commands/
+```
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/new-feature` | Start a new feature or bug fix connected to a GitHub issue |
+| `/prototype-ui` | Explore UI/UX approaches before committing to implementation |
+| `/cleanup-ai-slop` | Review and remove AI-generated code patterns that don't match our codebase style |
+| `/commit` | Create well-structured git commits with conventional commit format |
+| `/test` | Run all checks (lint, types, tests) and fix failures iteratively |
+| `/review-pr` | Run automated checks and code review before asking for human review |
+| `/create-pr` | Create a pull request with proper description, labels, and reviewers |
+| `/ship-feature` | Post-merge cleanup: close issues, changelog, docs ⚠️ *WIP* |
+
+## Workflow
+
+**Starting a feature:**
+1. `/new-feature` - Create branch from GitHub issue, clarify requirements, validate understanding
+2. `/prototype-ui` - *(optional)* Explore UI approaches before building
+
+**During development:**
+- `/test` - Run tests after making changes, fix failures iteratively
+
+**When finishing a feature:**
+1. `/cleanup-ai-slop` - Clean up any AI artifacts
+2. `/commit` - Create atomic, well-described commits
+3. `/review-pr` - Run in a **new chat session** to validate before human review
+4. `/create-pr` - Open a PR with proper metadata
+
+**After merge:**
+- `/ship-feature` - Close issues, update changelog, trigger docs ⚠️ *WIP*
+
+## Contributing
+
+When updating these commands:
+1. Edit the files in this folder
+2. Test the changes locally
+3. Commit with `docs(commands): <description>`

docs/commands/cleanup-ai-slop.md

@@ -0,0 +1,12 @@
+# cleanup-ai-slop
+
+Check the diff against main, and remove all AI generated slop introduced in this branch.
+
+This includes:
+
+- Extra comments that a human wouldn't add or is inconsistent with the rest of the file
+- Extra defensive checks or try/catch blocks that are abnormal for that area of the codebase (especially if called by trusted / validated codepaths)
+- Casts to any to get around type issues
+- Any other style that is inconsistent with the file
+
+Report at the end with only a 1-3 sentence summary of what you changed

docs/commands/commit.md

@@ -0,0 +1,48 @@
+# commit
+
+You are tasked with creating git commits for the changes made during this session.
+
+## Process:
+
+1. **Think about what changed:**
+   - Review the conversation history and understand what was accomplished
+   - Run `git status` to see current changes
+   - Run `git diff` to understand the modifications
+   - Consider whether changes should be one commit or multiple logical commits
+   - Check if the user ran the following cursor command: /cleanup-ai-slop, and if not prompt him to do it first
+
+2. **Plan your commit(s):**
+   - Identify which files belong together
+   - Draft clear, descriptive commit messages
+   - Use imperative mood in commit messages
+   - Focus on why the changes were made, not just what
+
+3. **Present your plan to the user:**
+   - List the files you plan to add for each commit
+   - Show the commit message(s) you'll use
+   - Ask: "I plan to create [N] commit(s) with these changes. Shall I proceed?"
+
+4. **Execute upon confirmation:**
+   - Use `git add` with specific files (never use `-A` or `.`)
+   - Create commits with your planned messages
+   - Show the result with `git log --oneline -n [number]`
+
+5. **Push/sync changes:**
+   - After committing, push the changes to the remote branch
+   - Use `git push` (or `git push -u origin <branch>` if the branch doesn't have an upstream)
+   - Confirm the push was successful
+
+## Important:
+- **NEVER add co-author information or Claude attribution**
+- Commits should be authored solely by the user
+- Do not include any "Generated with Claude" messages
+- Do not add "Co-Authored-By" lines
+- Write commit messages as if the user wrote them
+- Keep descriptions concise, lowercase, and in present tense without periods.
+- Use Conventional Commits format: `<type>(scope): <description>`. Scope is optional. Use types like feat:, fix:, chore:, docs:, refactor:, perf:, test:. Add ! for breaking changes (e.g., feat!: or feat(api)!:). 
+
+## Remember:
+- You have the full context of what was done in this session
+- Group related changes together
+- Keep commits focused and atomic when possible
+- The user trusts your judgment - they asked you to commit

docs/commands/create-pr.md

@@ -0,0 +1,33 @@
+# create-pr
+
+## Overview
+Create a well-structured pull request with proper description, labels, and reviewers.
+
+## Steps
+1. **Pre-flight check**
+   - Ask the user: "Have you run `/review-pr` in a fresh session? (yes/no)"
+   - If no, prompt them to run it first before creating the PR
+
+2. **Prepare branch**
+   - Ensure all changes are committed
+   - Push branch to remote
+   - Verify branch is up to date with main
+
+3. **Write PR description**
+   - Summarize changes clearly
+   - Include context and motivation
+   - List any breaking changes
+   - Add screenshots if UI changes
+
+4. **Set up PR**
+   - Create PR with descriptive title
+   - Add appropriate labels (by default should be "talent-app", but ask user to confirm)
+   - Assign reviewers (by default assign to @simaonogueira101 and @0xleal, but ask user to confirm)
+   - Make me (@filmacedo) the Assignee
+   - Link related issues
+
+## PR Template
+- [ ] Feature A
+- [ ] Bug fix B
+- [ ] Unit tests pass
+- [ ] Manual testing completed

docs/commands/new-feature.md

@@ -0,0 +1,27 @@
+# new-feature
+
+Start working on a new feature or bug fix connected to a GitHub issue.
+
+## Process
+
+1. **Get context:**
+   - Ask: "What's the GitHub issue number or URL?"
+   - Fetch the issue details with `gh issue view <number>`
+   - Read and understand the requirements
+   - Review @coding-guidelines.md to understand architecture patterns
+
+2. **Clarify before building:**
+   - If requirements are unclear, ask up to 5 clarifying questions
+   - Ensure there's no ambiguity before starting implementation
+   - Don't assume — if something could be interpreted multiple ways, ask
+
+3. **Create branch:**
+   - Branch from main: `git checkout main && git pull && git checkout -b <type>/<issue>-<short-description>`
+   - Use `feat/` for features, `fix/` for bugs (e.g., `feat/123-add-dark-mode`)
+
+4. **Quick validation:**
+   - Summarize what needs to be done in 2-3 sentences
+   - Ask: "Does this match your understanding? Anything to add or clarify?"
+
+5. **Start working:**
+   - Once confirmed, begin implementation

docs/commands/prototype-ui.md

@@ -0,0 +1,37 @@
+# prototype-ui
+
+Explore UI/UX approaches before committing to implementation.
+
+## When to Use
+
+- New pages or major UI features
+- When the design isn't obvious from the requirements
+- When you want to see options before building
+
+## Process
+
+1. **Get context:**
+   - Ask for the feature description or GitHub issue
+   - Understand the user flow and data requirements
+   - Review existing similar components in the codebase
+
+2. **Generate 3 approaches:**
+   - Describe each approach in natural language (no code yet)
+   - Focus on layout, interaction patterns, and user flow
+   - Highlight trade-offs between approaches
+   - Use simple diagrams or ASCII sketches if helpful
+
+3. **Get feedback:**
+   - Ask: "Which approach do you prefer, or what would you combine?"
+   - Incorporate feedback into a final direction
+
+4. **Build the prototype:**
+   - Create a functional prototype with real or mock data
+   - Focus on the UI structure and interactions
+   - Don't worry about edge cases or error handling yet
+   - Follow @coding-guidelines.md for component patterns
+
+5. **Iterate:**
+   - Show the prototype and ask for feedback
+   - Refine until the direction is confirmed
+   - Then proceed to full implementation

docs/commands/review-pr.md

@@ -0,0 +1,58 @@
+# review-pr
+
+Pre-review checklist to run before asking a human to review your PR.
+
+## Pre-flight Check
+
+**Start fresh:** If you've been working in this session, the context may be polluted.
+
+Ask the user: "Is this a fresh chat session? (yes/no)"
+- If no: "Please start a new chat and run /review-pr again."
+- If yes: Proceed with the review.
+
+## Process
+
+1. **Run automated checks:**
+   ```bash
+   npx turbo run lint check-types && npm test
+   ```
+   - Fix all errors and warnings before proceeding
+   - If tests fail, investigate and fix the root cause
+
+2. **Review the diff:**
+   - Run `git diff main` to see all changes
+   - Check for component reuse - are we duplicating existing components?
+   - Verify styles match the rest of the app
+   - Look for hardcoded values that should be constants or configs
+   - Ensure no console.logs or debugging code left behind
+
+3. **Code quality check:**
+   - Proper error handling where needed
+   - No unused imports or variables
+   - Consistent naming conventions
+   - Types are specific (avoid `any`)
+
+4. **Architecture compliance:**
+   - Review @coding-guidelines.md
+   - Verify hooks use `isServer` pattern
+   - Verify services use `unstable_cache`
+   - Check semantic colors only (no `bg-gray-*`, use `bg-muted` etc.)
+   - Ensure components use hooks, not direct API calls
+
+5. **Security check:**
+   - No hardcoded secrets, API keys, or credentials
+   - Input validation on user-facing endpoints
+   - Sensitive data not logged or exposed in errors
+   - No dangerous patterns (eval, dangerouslySetInnerHTML without sanitization)
+
+6. **Report findings:**
+   - List any issues found with file locations
+   - Suggest fixes or improvements
+   - Confirm when all checks pass
+
+## Output
+
+End with a summary:
+- ✅ Checks passed / ❌ Issues found
+- List of changes made (if any)
+- "Ready for human review" or "Fix these issues first"

docs/commands/ship-feature.md

@@ -0,0 +1,41 @@
+# ship-feature
+
+> ⚠️ **WIP**: This command is a work in progress. Versioning and changelog workflows are not yet established.
+
+Post-merge cleanup after a PR has been merged.
+
+## When to Use
+
+Run this after your PR has been merged to main.
+
+## Process
+
+1. **Confirm merge:**
+   - Ask: "Has the PR been merged? What was the PR number?"
+   - Verify the PR is closed/merged on GitHub
+
+2. **Update GitHub issue:**
+   - Close the linked issue if not auto-closed
+   - Add a comment summarizing what was implemented
+   - Link to the merged PR
+
+3. **Changelog entry:** *(future)*
+   - Create `docs/changelog/YYYY-MM-DD-<short-description>.md`
+   - Include: what changed, why, any breaking changes
+   - Keep it user-facing (not implementation details)
+
+4. **Version bump:** *(future)*
+   - Determine bump type: patch (fixes), minor (features), major (breaking)
+   - Ask user to confirm before bumping
+
+5. **Documentation:**
+   - Ask: "Does this feature need documentation updates?"
+   - If yes, identify what docs need updating
+   - Update inline code comments if helpful for future maintainers
+
+## Output
+
+Summary of post-merge tasks completed:
+- ✅ Issue closed
+- ✅ Changelog entry created
+- ✅ Docs updated (if needed)

docs/commands/test.md

@@ -0,0 +1,19 @@
+# test
+
+Run the full test suite and systematically fix any failures.
+
+## Process
+
+1. **Run all checks:**
+   ```bash
+   npx turbo run lint check-types && npm test
+   ```
+
+2. **On failure:**
+   - Fix one issue at a time
+   - Re-run after each fix
+   - Never skip or disable tests without explicit user approval
+
+3. **Report:**
+   - ✅ All checks pass / ❌ N issues found
+   - Brief summary of fixes made