Claude AI Subagents System
Relevant source files
The following files were used as context for generating this wiki page:
The Claude AI Subagents System represents a specialized set of development guidelines and context-aware rules designed to facilitate efficient maintenance and feature development within the Portfolio OS project. The system utilizes specific Markdown-based configuration files to define domain-specific knowledge for AI assistants (subagents), ensuring they adhere to the project's unique architectural patterns and technical constraints.
These subagents are organized by functional areas, such as UI development, window management logic, and internationalization, allowing for targeted expertise when modifying the codebase. The system explicitly acknowledges that the underlying framework (Next.js) in this project may deviate from standard conventions, requiring subagents to consult internal documentation before executing tasks.
Sources: CLAUDE.md:1, AGENTS.md:1-6
Architecture and Subagent Domains
The subagent system is structured to provide granular oversight across the portfolio's macOS-style environment. Each agent is responsible for a specific technical domain, ensuring that complex features like the windowing system or the contact form workflow maintain internal consistency.
Specialized Agent Modules
| Agent | Primary Responsibility | Key Files Involved |
|---|---|---|
| Portfolio UI | Styling, Glassmorphism, Layout | app/globals.css, features/desktop/components/ |
| Window System | State management, z-index, resizing | context/WindowManagerContext.tsx, workflows/windowManager.ts |
| I18n Translator | Localization (English/Persian) | messages/en.json, messages/fa.json, app/layout.tsx |
Sources: AGENTS.md:1-6, CLAUDE.md:1, context/WindowManagerContext.tsx:1-40
Core System Workflows
The system governs several critical workflows, primarily handled through React Context and Reducer patterns. The most complex logic resides in the Window Manager, which simulates a desktop operating system environment.
Window Management Logic
The subagent responsible for the window system manages window states including opening, focusing, minimizing, and resizing. It ensures single-instance application behavior where re-opening an app focuses the existing window rather than creating a duplicate.
The diagram shows the logic flow for opening and focusing windows within the portfolio desktop.
Sources: workflows/windowManager.test.ts:16-33, context/WindowManagerContext.tsx:28-36
Contact Form State Machine
The contact system utilizes a reducer-based state machine to track the lifecycle of a message submission.
The state machine for handling user contact requests through the portfolio interface.
Sources: workflows/contactForm.test.ts:4-28
Implementation Details
Window Reducer Actions
The system defines a set of standardized actions that subagents must use when interacting with the windowing state.
| Action Type | Parameters | Effect |
|---|---|---|
open | appId, geometry | Adds a window to the state or focuses an existing one. |
focus | id | Sets focusedId and brings the window to the front via z-index. |
minimize | id | Sets isMinimized to true and clears active focus. |
close | id | Removes the window object from the state array. |
move | id, x, y | Updates the X and Y coordinates of the target window. |
Sources: workflows/windowManager.test.ts:42-65, context/WindowManagerContext.tsx:10-18
Internationalization (I18n) Support
The subagents handle multi-language support by interacting with the next-intl provider. The MenuBar component facilitates language switching between English and Persian, which involves updating the user locale and refreshing the router.
// From features/desktop/components/MenuBar.tsx
function changeLocale(next: string) {
startTransition(async () => {
await setUserLocale(next as Locale);
router.refresh();
});
}
Sources: features/desktop/components/MenuBar.tsx:29-34, app/layout.tsx:26-32
Summary
The Claude AI Subagents System acts as a bridge between the project's custom Next.js implementation and the AI assistants managing it. By defining clear boundaries for UI, window state, and localization, the system ensures that automated modifications adhere to the "Portfolio OS" architecture, specifically the simulated desktop environment and its underlying state machines.