AmitRaikwar-in · ar022 · Jun 14, 2026 · Jun 14, 2026
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -0,0 +1,129 @@
+# CLAUDE.md
+
+This file provides a high-level entry point for Claude-based tools working in the **Amit Raikwar Portfolio** repository.
+
+## Overview
+
+This is a **React Web Application** (using Craco for configuration) representing Amit Raikwar's portfolio website.
+
+- **Web Framework**: React 18.2+
+- **Styling**: Chakra UI v2 (Space Mono typography, brand colors) and Tailwind CSS
+- **State Management**: Zustand, React Query
+- **Animations/Graphics**: Framer Motion, GSAP, React Three Fiber (Three.js), TSParticles
+- **Routing**: React Router DOM v6
+
+## 📘 Primary Documentation
+
+For comprehensive technical documentation, architectural decisions, file conventions, and agent-specific skills, always refer to the Agent Guide section:
+
+👉 **[Agent Guide](#AGENT)**
+
+## 💻 Code Style Guidelines
+
+- **React Components**: Avoid using `React.FC` or `React.FunctionComponent` to define functional components. Instead, type props directly in the function arguments: `const MyComponent = ({ prop1 }: Props) => { ... }`.
+
+## Essential Commands
+
+These are the most common commands for development:
+
+```bash
+yarn install                   # Install all dependencies
+yarn start                     # Start local development server
+yarn build                     # Create production build for web
+yarn test                      # Run Jest tests
+yarn prettier:write            # Format code with Prettier
+yarn lint                      # Run ESLint and check issues
+yarn lint:fix                  # Run ESLint and fix web issues
+```
+
+## Antigravity Skills
+
+Advanced agent instructions are modularized in the `.claude/skills/` directory.
+
+- [Commit Workflow](file:///Users/mr.robot/z-stash/AmitRaikwar-in/amitraikwar/.claude/skills/commit/SKILL.md)
+- [Jira Management](file:///Users/mr.robot/z-stash/AmitRaikwar-in/amitraikwar/.claude/skills/jira/SKILL.md)
+- [Pull Request Skill](file:///Users/mr.robot/z-stash/AmitRaikwar-in/amitraikwar/.claude/skills/pr/SKILL.md)
+- [Frontend Design](file:///Users/mr.robot/z-stash/AmitRaikwar-in/amitraikwar/.claude/skills/frontend-design/SKILL.md)
+- [Web Development](file:///Users/mr.robot/z-stash/AmitRaikwar-in/amitraikwar/.claude/skills/web/SKILL.md)
+- [README Guidelines](file:///Users/mr.robot/z-stash/AmitRaikwar-in/amitraikwar/.claude/skills/readme/SKILL.md)
+
+## 🌐 Localization Guidelines
+
+All user-facing copy strings (headings, paragraphs, labels, button texts, tooltips, placeholders, etc.) MUST be defined in the localization JSON files located in `src/localization/locales/` (`main.json`, `common.json`, and `error.json` under each locale directory) and retrieved dynamically in code using the `useTranslation` hook (`t('key')`). Never hardcode text strings directly in component files.
+
+## 🧪 Testing Guidelines
+
+Always add or update the unit tests (and their snapshots) to align with the requested feature implementations or changes. Run the test suite using `yarn test` to verify that all changes are fully covered, correct, and pass successfully.
+
+---
+
+# AGENT
+
+This section serves as the primary source of truth for AI agents working on the **Amit Raikwar Portfolio** project. It provides architectural context, directory structures, and established development patterns.
+
+## 1. Project Overview
+
+| Core Stack           | Technology                                                                       |
+| :------------------- | :------------------------------------------------------------------------------- |
+| **Framework**        | [React 18.2+](https://react.dev/)                                                |
+| **UI Library**       | [Chakra UI v2](https://v2.chakra-ui.com/)                                        |
+| **State Management** | [Zustand v4](https://zustand.docs.pmnd.rs/)                                      |
+| **Routing**          | [React Router DOM v6](https://reactrouter.com/)                                  |
+| **Styling**          | Vanilla CSS + Chakra UI v2 + Tailwind CSS                                        |
+| **Language**         | [TypeScript](https://www.typescriptlang.org/)                                    |
+| **Testing**          | Jest + React Testing Library + Cypress                                           |
+| **Package Manager**  | [Yarn 4](https://yarnpkg.com/)                                                   |
+| **Aesthetic**        | Interactive, Dark mode, Dynamic elements (canvas, physics text, spotlight cards) |
+| **Brand Colors**     | Black background (#000000) & Violet/Blue details                                 |
+
+## 2. Directory Structure
+
+```text
+/
+├── .claude/                # Agent skills and settings
+├── src/                    # Primary source code
+│   ├── assets/             # Global assets, icons & media mapping
+│   ├── components/         # Reusable UI components (custom cursor, marquee, etc.)
+│   ├── data/               # Static dataset files (Projects, Work, Contact details)
+│   ├── hooks/              # Custom React hooks (useMoveToTop, etc.)
+│   ├── localization/       # Locale configuration & translation JSON resources
+│   ├── providers/          # App-wide React context providers (Theme, Router, Locales)
+│   ├── router/             # React Router routing definition and public routes
+│   ├── screens/            # Complete screen flows (Main flow, projects, articles)
+│   ├── store/              # Zustand slices and hooks
+│   ├── index.tsx           # React bootstrap script
+│   └── App.tsx             # Root Application component
+├── public/                 # Static public files & index.html
+├── craco.config.js         # Webpack and craco configuration
+├── tsconfig.json           # TS compile configuration
+├── tailwind.config.js      # Tailwind configurations
+└── package.json            # Main package dependencies & scripts
+```
+
+## 3. Development Patterns & Rules
+
+### State Management (Zustand)
+
+- **Selectors**: Use appropriate selector patterns when extracting state variables to prevent unnecessary re-renders.
+- **Testing**: State updates within tests MUST be wrapped in `act()` from `@testing-library/react`.
+
+### TypeScript
+
+- All files use `.ts` or `.tsx`.
+- Adhere to path aliases defined in `tsconfig.path.json` (e.g., `@components`, `@data`, `@providers`, `@screens`).
+
+## 4. Testing & Verification
+
+- **Unit/Integration**: `yarn test`
+- **Build**: `yarn build` (Always verify build compatibility after modifications).
+
+## 5. Agent Workflow
+
+1.  **Understand**: Review this file and `.claude/CLAUDE.md`.
+2.  **Verify**: Always run `yarn lint` and `yarn test` before declaring a task complete.
+3.  **Documentation**: Always check if a README update is required for any modified components.
+4.  **Governance**: Follow Conventional Commits and link all changes to the **Amit Raikwar Portfolio** Jira project using `prefix/AR-XXX` branch naming.
+
+---
+
+© 2026 Amit Raikwar Portfolio | Confidential and Proprietary
diff --git a/.claude/agents/DEVELOPER.md b/.claude/agents/DEVELOPER.md
@@ -0,0 +1,54 @@
+---
+name: developer
+description: Agent responsible for end-to-end development lifecycle, from testing changes and Jira ticket creation to committing code and opening Pull Requests.
+---
+
+# Developer Workflow Agent
+
+This agent ruleset defines the standard end-to-end workflow for an AI Agent handling development tasks in the **Amit Raikwar Portfolio** project.
+
+## Workflow Steps
+
+When assigned to process a set of changes, the agent MUST follow these steps in exact order:
+
+### 1. Test Formatting and Functionality
+
+- Before committing anything, verify the code formatting and functionality.
+- Run appropriate linters (`yarn lint:fix`) and test commands (`yarn test`).
+- Ensure there are no outstanding errors or build failures.
+
+### 2. Check and Update Documentation
+
+- Always check if a README update is required for any modified components (e.g., changes to routes, state keys, config settings, dependencies, or APIs).
+- If required, update or write the corresponding `README.md` file following the guidelines and templates defined in the [readme skill](file:///Users/mr.robot/z-stash/AmitRaikwar-in/amitraikwar/.claude/skills/readme/SKILL.md).
+
+### 3. Create Jira Ticket
+
+- Automatically create a Jira ticket in the `AR` project.
+- **IMPORTANT**: The ticket description must focus on the **requirement** and the **purpose of the requirement**. Do NOT write it like a PR description (i.e. do not just list the technical changes made). Instead, explain the 'why' and the 'what' from a functional/requirement perspective.
+- **IMPORTANT**: You must ask the user which Epic the ticket should be linked to. Provide the user with these options:
+  - `1` for **Infrastructure & Dependencies** (`AR-1`)
+  - `2` for **Portfolio Content & Features** (`AR-2`)
+  - `3` for **Interactive Styling & Animations** (`AR-3`)
+  - `4` for **Translations & Accessibility** (`AR-4`)
+  - `5` for **Coverage & Quality Assurance** (`AR-5`)
+- Wait for the user's response. Once the user provides the Epic choice, link the newly created ticket to the corresponding Epic using `parent: "EPIC-KEY"` (e.g., `parent: "AR-1"`).
+- Follow all standard naming and template guidelines from `.claude/skills/jira/SKILL.md` (e.g., prefixing `[Web]`, `[Core]`, `[Design]`, or `[Testing]` to the title, and applying the corresponding label).
+
+### 4. Create Commit
+
+- After the Jira ticket is successfully created, initiate the commit process.
+- Follow the rules defined in `.claude/skills/commit/SKILL.md`.
+- Use the standard branch naming convention: `amitraikwar/{ticket-number}/{short-description}`.
+- **IMPORTANT**: Use `make commit` with a **detailed, multi-line body**.
+- The commit body MUST explain the "Why" and "What" of the changes, including a bulleted list of modifications and the specific requirements addressed.
+- Example format: `<type>(<ticket-number>): <short description>\n\n- Detailed change 1\n- Detailed change 2\n...`
+
+### 5. Create Pull Request
+
+- If all the above steps (testing, documentation, ticket creation, committing) have succeeded, proceed to create a Pull Request.
+- Follow the rules defined in `.claude/skills/pr/SKILL.md`.
+- Target the `onemanfighter/amitraikwar` repository.
+- Set the base branch to `development`.
+- Use the appropriate title and description templates.
+- Trigger the `jira-pr-created` step to comment on the Jira ticket and move it to "In Review".
diff --git a/.claude/agents/REVIEW.md b/.claude/agents/REVIEW.md
@@ -0,0 +1,33 @@
+---
+name: review
+description: Single unified Agent responsible for dynamically reviewing and testing Pull Requests based on modified files.
+---
+
+# Unified PR Review & Merge Agent
+
+This agent ruleset defines the responsibilities and workflows for the AI Agent assigned to review and merge Pull Requests in the **Amit Raikwar Portfolio** project.
+
+## 1. Trigger Conditions
+
+This agent should be invoked when any Pull Request is opened or updated in the repository.
+
+## 2. Review Checklist
+
+The agent MUST perform the following checks before approving a PR:
+
+- **PR Metadata**: Verify that the PR title and description follow the templates defined in `.claude/skills/pr/SKILL.md`.
+- **Branch Naming**: Verify the branch name follows `amitraikwar/{ticket-number}/{short-description}`.
+- **Dynamic Build & Test Verification**: Execute `yarn test` and `yarn build` commands. Ensure they complete successfully without errors.
+- **Code Quality**: Ensure the changes adhere to project standards (e.g., clean component structures, no excessive logging, appropriate framework usage).
+
+## 3. Merge Protocol
+
+If the PR passes all checks:
+
+1. Use the `github-mcp-server` to submit an **Approve** review with a summary of the checks performed.
+2. Merge the Pull Request using the `merge_pull_request` tool.
+3. Execute the `jira-pr-merged` skill steps from `.claude/skills/pr/SKILL.md` to update the associated Jira ticket.
+
+If the PR fails any check (e.g. tests fail, formatting is incorrect):
+
+1. Use the `github-mcp-server` to submit a **Request Changes** review, clearly detailing which checks failed and providing actionable feedback.
diff --git a/.claude/skills/commit/SKILL.md b/.claude/skills/commit/SKILL.md
@@ -0,0 +1,81 @@
+---
+name: commit
+description: Manage Conventional Commits, branch naming conventions, and interactive commit workflows using the project's standardized makefile commands.
+trigger: /commit
+---
+
+# Commit Command
+
+This file provides guidance for using Claude Code to commit changes following the project's Commit Workflow.
+
+> [!IMPORTANT]
+> You MUST always use `make commit` to initiate a commit. This ensures all commits follow the conventional commit standard.
+
+## Commit Workflow
+
+1. Create a feature branch: `git checkout -b amitraikwar/{ticket-number}/{short-description}`
+2. Stage your changes: `git add <files>`
+3. Create initial commit: `make commit` (opens interactive conventional commit prompt)
+4. Amend with detailed message: `git commit --amend` to add requirements and detailed descriptions of changes.
+
+## Branch Naming
+
+All feature and fix branches MUST follow this naming pattern:
+
+`amitraikwar/{ticket-number}/{short-description}`
+
+**Example:**
+`amitraikwar/AR-18/update-branding`
+
+## Commit Message Format
+
+> [!IMPORTANT]
+> Always use `make commit` for the initial commit. DO NOT use `git commit -m`.
+> **Every commit MUST include a detailed body.** A single-line description is NOT sufficient.
+
+When using Claude Code to commit changes:
+
+- **Initial Commit**: Use the `/commit` skill or run `make commit` with a detailed body.
+- **Body Content**: The commit body MUST explain:
+  - **Why**: The rationale behind the changes.
+  - **What**: A summary of key modifications (use bullet points for multiple items).
+  - **Requirements**: List any specific requirements or JIRA criteria addressed.
+- **Format**: `<type>(<ticket-number>): <short description>` followed by a detailed body.
+
+## Examples
+
+### Initial Commit with Detailed Message
+
+To provide a high-quality commit message in one go:
+
+```bash
+# Pattern: printf "tag_index\nscope\ntitle\nDetailed body explanation with bullet points.\n\n" | make commit
+printf "3\AR-19\nadd branding and skills\n- Implement portfolio branding across core components.\n- Add custom SVG icons for the design system.\n- Update global styles to use the vibrant portfolio color palette.\n- Adhere to requirements specified in AR-19 for visual excellence.\n\n" | make commit
+```
+
+### Initial Commit (Interactive)
+
+```bash
+git add src/components/NewFeature.tsx
+make commit
+# Select type: feat, fix, etc.
+# Enter ticket number as scope (e.g. AR-19)
+# Enter brief description
+```
+
+### Amend Commit
+
+```bash
+git commit --amend
+# Edit the commit message to add:
+# - Detailed description of changes
+# - Requirements addressed
+# - Any breaking changes or special notes
+```
+
+## Best Practices
+
+- Keep subject line under 50 characters
+- Use body to explain "why" not just "what"
+- Reference related issues if applicable
+- Ensure commit passes linting and tests before pushing
diff --git a/.claude/skills/frontend-design/SKILL.md b/.claude/skills/frontend-design/SKILL.md
@@ -0,0 +1,45 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.